Setting up a Hyva child theme and Tailwind pipeline

Part 5 of the Hyva series — building the core storefront. Implementation-focused.

Why a child theme

You never edit the Hyva/Theme base directly. You create a child theme that inherits it and override only what you need. This keeps the base upgradable: when Hyva ships a fix, composer update moves the base forward and your overrides survive.

A child theme declares its parent in theme.xml:

<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd">
    <title>Example Store Hyva</title>
    <parent>Hyva/theme-frontend-hyva</parent>
</theme>

Register it the way any Magento theme is registered, then assign it to your store view in the admin.

The Tailwind entry points

A Hyva theme ships two source files that drive the CSS build:

• web/tailwind/tailwind.source.css — the Tailwind directives plus any custom layers.
• web/tailwind/tailwind.config.js — the content globs and theme tokens.

The source file is minimal:

@tailwind base;
@tailwind components;
@tailwind utilities;

Tailwind scans your PHTML templates, your layout, and your *.phtml overrides to decide which utilities to emit. Because the compiler only keeps classes it finds in source, every class you use must exist as a literal string in a scanned file — dynamically composed class names are purged and disappear. This is the single most common "why is my style missing" bug in a Hyva build.

Configuring the build

The tailwind.config.js content globs should cover your theme and any modules you override:

module.exports = {
  content: [
    '../*.phtml',
    '../../*/view/frontend/templates/**/*.phtml',
    '../*/*/*.phtml',
  ],
  theme: { extend: { colors: { brand: '#1d4ed8' } } },
  plugins: [],
};

Run the watcher during development:

npm install
npm run watch

This regenerates styles.css on every template change. For production you run the build step as part of deployment (or commit the compiled CSS — teams differ here; committing the output keeps the build reproducible and avoids a Node step on the web node).

Design tokens

Tailwind's theme.extend is where your brand tokens live. Rather than scattering hex values across templates, define them once:

theme: {
  extend: {
    colors: {
      brand: { DEFAULT: '#1d4ed8', dark: '#1e3a8a' },
    },
    fontFamily: {
      sans: ['Inter', 'system-ui', 'sans-serif'],
    },
  },
}

Now bg-brand and text-brand-dark are available everywhere, and a rebrand is a one-line change. Keep tokens in the config, not in the markup — that discipline is what makes a Hyva theme maintainable as it grows.

Common pitfalls

• Missing classes after deploy. A class used only in a JS string or built at runtime is not in the scanned source, so it is purged. Refactor to literal classes.
• Wrong content globs. If you override a module under view/frontend/templates and forget to include it in content, its classes vanish. Audit the globs when a new override lands.
• Two Tailwind versions. The base theme and your child must agree on the Tailwind major version. A mismatch produces silent style loss.

What's next

With the theme and pipeline in place, the next post shows how pages are assembled in Hyva — layout XML, containers, blocks, and PHTML overrides — and how that differs from the Luma workflow you may already know.

Next in this series: Layout XML and PHTML overrides in Hyva — /blog/magento2-layout-hyva