Tailwind in Hyvä: design tokens and the build pipeline

Luma themes are styled with LESS files, variables and a long chain of overrides. Hyvä replaces that with Tailwind CSS, a utility-first framework where the styling sits directly in the template markup as classes.

That change confuses some teams at first. If every element carries its own classes, where does the brand live? The answer is design tokens, and a build pipeline that turns them into a small stylesheet. This post explains both, based on how we set up our own Hyvä stores.

What a design token is

A design token is a named value that the whole theme shares. Instead of writing a hex colour into twenty templates, you define primary once and use classes such as bg-primary and text-primary everywhere.

Typical token groups in a Hyvä theme are:

• Colours: primary, secondary, background, text, borders, sale and stock states.
• Typography: font families, sizes and weights for headings and body text.
• Spacing and sizing: the scale used for padding, margins and container widths.
• Breakpoints: the screen widths where the layout changes.
• Radii and shadows: the small details that make a design feel consistent.

When a brand colour changes, you change one token and rebuild. Every button, link and badge follows.

Where tokens live in Hyvä

Hyvä’s default theme already defines a set of tokens in its Tailwind configuration. Your child theme copies the web/tailwind folder and extends those values, as described in our Hyvä child theme guide.

A simple extension of the colour tokens looks like this:

theme: {
    extend: {
        colors: {
            primary: {
                lighter: 'var(--color-primary-lighter)',
                DEFAULT: 'var(--color-primary)',
                darker: 'var(--color-primary-darker)'
            }
        }
    }
}

Pointing a token at a CSS custom property, as above, is a useful pattern. The class name stays the same, but the actual colour can be set elsewhere, for example per store view or from the admin.

The exact file layout depends on your Hyvä version, because newer Tailwind versions move more of the configuration into CSS. The principle stays the same: define tokens once, use them everywhere.

Letting the team change colours without code

On our stores we expose header and brand colours in Stores > Configuration. A marketing team can change a colour in the admin without opening a ticket.

Behind that setting, the Tailwind tokens are rebuilt from the configuration and theme files at deploy. The admin holds the values, the tokens hold the names, and the build connects them.

We limit this to a handful of values on purpose. A colour picker for every element quickly turns a clean design into a patchwork, so the admin offers the brand decisions and the theme keeps everything else consistent. We go into more detail in our post on changing Hyvä theme colours from the admin.

How the build pipeline works

Tailwind does not ship every possible utility class to the browser. During the build it scans your templates, finds the classes you use, and writes only those into the final stylesheet.

For a Hyvä store, the build has to see every place a class can come from:

1. Templates in your child theme.
2. Templates still served from the Hyvä default theme in the vendor folder.
3. Templates and Tailwind sources from Hyvä-compatible modules.
4. Any classes set from PHP, CMS content or the admin.

Hyvä handles the third point with the command bin/magento hyva:config:generate. It writes a list of the installed Hyvä-compatible modules and their paths, and the Tailwind build reads that list.

The fourth point needs care. Tailwind cannot see a class name that only exists in the database. If editors type class names into CMS blocks, you must list those classes explicitly in the configuration so the build keeps them, or they will look fine in development and break in production.

Our deploy order

We treat the compiled stylesheet as a build artefact, never as a file someone edits or commits. Our stack runs Magento 2.4.9 in production mode with static content deploy, and the deploy runs in a fixed order.

bin/magento hyva:config:generate
npm --prefix app/design/frontend/Vendor/default/web/tailwind ci
npm --prefix app/design/frontend/Vendor/default/web/tailwind run build-prod
bin/magento setup:static-content:deploy -f en_GB de_DE
bin/magento cache:flush

Check the build script name in your theme’s package.json, because it differs between Hyvä versions. Using npm ci instead of npm install gives you the exact package versions from the lock file on every deploy.

After the deploy we purge the CDN cache for the stylesheet, so visitors do not get new HTML with old CSS.

Why this keeps pages light

In our benchmark on the same server and catalogue, clean Hyvä pages weighed 195 to 226 KB, against 756 to 962 KB for the same pages on Luma. A large part of the difference is JavaScript, but CSS plays a role too.

A Luma stylesheet contains styles for every widget the theme might show. A Tailwind build contains the classes your templates use and very little else. Full numbers are in our Hyvä vs Luma benchmark.

The build only stays lean if you keep it disciplined. A few habits help:

• Use tokens instead of arbitrary values such as one-off pixel widths.
• Avoid building class names from strings in PHP or JavaScript, because Tailwind cannot detect them.
• Remove old components when you replace them, so their classes leave the build too.
• Keep custom CSS files small, and only for things Tailwind cannot express well.

Common problems and their causes

FAQ

Do designers need to learn Tailwind?

Not in depth. Designers should deliver a clear set of colours, type sizes and spacing values, and developers turn those into tokens. That shared list is often the most useful outcome of the whole design phase.

Can we still write normal CSS in Hyvä?

Yes. Hyvä themes can include custom CSS, and Tailwind supports component classes for repeated patterns. We keep custom CSS to a minimum, so most styling stays visible in the templates.

Does rebuilding CSS at every deploy slow deploys down?

The Tailwind build is a small step compared with static content deployment. It adds a short, predictable stage to the pipeline, and it removes a whole class of out-of-sync bugs.

Want a Hyvä theme your team can adjust safely? Read about our approach on the Hyvä theme development page, or ask for a Magento audit of your current frontend.