Hyvä Theme Customization: Tailwind, Overrides & the Build Pipeline

The four places a customization can live

Before you touch anything, decide where the change belongs. Hyvä gives you four layers, and the right answer is almost always “the highest layer that does the job,” because higher layers are less code, easier to read, and survive upgrades cleanly.

Layer 1 — design tokens in tailwind.config.js

A Hyvä child theme lives where every Magento theme lives — app/design/frontend/Panth/default/ — and the Tailwind project sits inside it at web/tailwind/:

app/design/frontend/Panth/default/
├─ theme.xml
├─ registration.php
└─ web/
   └─ tailwind/
      ├─ tailwind.config.js     ← your tokens live here
      ├─ package.json
      └─ css/
         └─ styles.css          ← @tailwind + a few @layer rules

Brand changes — colors, fonts, the spacing scale, custom breakpoints — belong in theme.extend. Extend rather than replace, so you keep Tailwind's defaults and Hyvä's base styling:

// web/tailwind/tailwind.config.js
module.exports = {
    theme: {
        extend: {
            colors: {
                primary: {
                    DEFAULT: '#f97316',   // brand orange
                    dark:    '#ea580c',
                    soft:    '#fff4ed',
                },
            },
            fontFamily: {
                // Hyva preloads the font; the class just references it
                sans: ['"DM Sans"', 'ui-sans-serif', 'system-ui'],
            },
        },
    },
};

Now bg-primary, text-primary-dark, and font-sans exist as real utilities everywhere — templates, modules, even CMS blocks. One token, applied site-wide, zero markup forks. This is the layer most “theme customization” tickets should actually resolve to.

Layer 2 — the build pipeline (and the purge that eats your CSS)

Tailwind doesn't ship a giant stylesheet with every possible class. It scans your files, finds the classes you actually used, and generates only those. That is what keeps the CSS small — and it's also the source of the single most common Hyvä support ticket. Day to day you run two commands from the theme's web/tailwind/ folder:

cd app/design/frontend/Panth/default/web/tailwind
npm ci              # once, installs Tailwind + the Hyva preset

npm run watch       # dev: rebuilds in < 100ms on every save
npm run build-prod  # prod: one minified, purged styles.css

In watch mode Tailwind keeps a generous, unpurged stylesheet, so everything looks right on your laptop. build-prod is different — it purges every class it cannot find in a scanned file. If a class only appears somewhere Tailwind isn't looking, it's deleted from the production CSS, and the element renders unstyled only in production. Here is the typical “works on my machine” trace:

# dev: looks perfect
$ npm run watch
rebuilding... done in 84ms      <- full class set present

# prod: the button is suddenly naked
$ npm run build-prod
Done in 11.2s                   <- purged: bg-primary never seen in a scanned file
$ bin/magento setup:static-content:deploy -f en_US

The cause is always the content array — the list of globs Tailwind scans. The default covers the theme and core modules, but not your custom module's templates unless you register them (Layer 4). And no glob can catch a class you build at runtime, because the string never appears in source:

<!-- PURGED: 'bg-' + color is assembled at render time, never seen as a literal -->
<div class="bg-<?= $status ?>-100">…</div>

<!-- SAFE: full class names appear as literal strings Tailwind can scan -->
<div class="<?= $status === 'ok' ? 'bg-green-100' : 'bg-red-100' ?>">…</div>

When a dynamic class is genuinely unavoidable, add it to the safelist so the prod build keeps it:

// tailwind.config.js
module.exports = {
    safelist: ['bg-green-100', 'bg-red-100', 'bg-yellow-100'],
    // ...
};

Layer 3 — overriding a Hyvä template the right way

When you truly need different markup — not just different styling — override the template through Magento's theme fallback. You copy the vendor file into your child theme at the same module-relative path and edit your copy. The original is never touched, so the override survives composer update (see our Hyvä compatibility guide for the inverse problem — making a Luma module render at all).

# vendor original (NEVER edit this):
vendor/hyva-themes/magento2-default-theme/Magento_Catalog/templates/product/price/final_price.phtml

# your override (edit this, same path under your theme):
app/design/frontend/Panth/default/Magento_Catalog/templates/product/price/final_price.phtml

Theme fallback resolves your file first, falls back to the vendor file for everything you didn't override. Two rules keep this clean:

1. Copy the WHOLE template, then edit. A partial copy renders a partial block.
2. Override the SMALLEST template that contains your change. Overriding a big
   container to tweak one child means you now own (and must maintain) the whole
   container forever. Find the leaf .phtml that actually renders the markup.

For interactive behavior inside that markup, reach for Alpine before anything else — the patterns are covered in 10 Alpine.js patterns every Hyvä developer needs. Resist the urge to bolt jQuery back on; it defeats the entire point of the theme.

Layer 4 — modules and the hyva-modules registry

A reusable feature belongs in its own module with its own .phtml templates and layout XML — standard Magento. The Hyvä-specific step is making Tailwind scan those module templates so their classes aren't purged. You don't hand-edit the theme's content array for every module; instead each module ships a small Tailwind config fragment, and Hyvä's hyva-modules helper aggregates them into the theme build:

# from the theme's web/tailwind directory: regenerate the merged module list
# after installing or scaffolding a module that ships frontend templates
npx hyva-modules

# it writes/updates tailwind.config.js's module imports so your module's
# templates are part of the content globs Tailwind scans on build-prod

Skip this step and your module looks perfect in watch (unpurged) and unstyled in production (purged) — the exact Layer-2 symptom, now caused by an unregistered module rather than a runtime class. It's the same disease; this is just where it comes from when the markup lives in app/code/Panth/….

The deploy sequence, in order

On production the Tailwind build is a step you own — setup:static-content:deploy copies whatever CSS is on disk; it does not run Tailwind for you. Forget the build and you deploy stale (or empty) styles. The correct order:

cd app/design/frontend/Panth/default/web/tailwind
npm ci
npm run build-prod                                   # generate the purged CSS

cd -    # back to Magento root
bin/magento setup:static-content:deploy -f en_US     # publish it
bin/magento cache:flush

If a CSS change deploys but the old styling still serves, it's almost always a stale static cache or a CDN holding the old styles.css — bump the file or purge the edge, don't re-debug Tailwind. Need this done properly on your store? That's exactly what our Hyvä theme development service ships.