Design Tokens

Writing bg-blue-600 says what a button looks like. Writing bg-primary says what it is for, and that small change is what lets one codebase carry a light theme, a dark theme and several brand colours without a single dark: class in the markup. This chapter builds that system: tokens with meaning, the one Tailwind feature (@theme inline) that makes it work, themes switched by an HTML attribute, modern colour (oklch, color-mix(), wide gamut) and the scales for spacing, type and radius. It builds on Tailwind CSS Fundamentals 9 (@theme basics) and Tailwind CSS Fundamentals 8 (dark mode with dark:).

Palette Tokens and Semantic Tokens

Tailwind ships a palette: --color-blue-600, --color-gray-100, and so on. Those names describe a colour. A design system adds a second layer of names that describe a role. The two layers answer different questions:

The plan for the rest of the chapter: palette tokens stay as they are, and a small set of semantic tokens points at them, with the pointing changed per theme. For the pointing to work in Tailwind v4 you need one detail that looks like a stylistic choice and is not.

Why @theme inline Exists

The obvious way to make a semantic token is to write it in @theme and point it at a variable, then change that variable in a themed section of the page. I built exactly that and put the same bg-primary element in two places, one inside data-theme="ocean":

A custom property that contains var() is resolved where it is declared. With plain @theme, Tailwind declares --color-primary on :root, where --brand is blue, and every element below simply inherits that finished colour; redefining --brand in the ocean section changes a variable that nothing re-reads. With inline, Tailwind does not create --color-primary at all; it copies your var(--brand) straight into the utility, so it is read on the element, at the nearest --brand.

A Complete Multi-Theme System

Here is the whole system in one file: six semantic tokens, a light default, a dark mode, and a second brand ("sunset"). Two attributes pick the theme, and they are independent of each other, so a page can be light or dark in either brand without writing the four combinations by hand:

The markup uses only meaning, never a colour name or a dark::

I put that block in four contexts (every mode and brand combination) and had the page measure the result. The contrast column is the WCAG ratio, computed in the page from the rendered colours; 4.5 is the AA minimum for normal text.

Every pair is above 4.5. Notice the rule [data-mode="dark"][data-brand="sunset"] in the CSS: it exists because the orange that is readable on a pale page (lightness 0.55) would be too dark on a dark one, so the dark version is lighter (0.75). The numbers are the proof, and they are the reason to keep a contrast check next to the tokens. Because the attribute decides which variables apply, changing it in JavaScript changes the theme with no rebuild: I set data-brand="sunset" on the root element from a script and read the new --primary straight back (#0559d2 became #c73800).

Derived Colours with color-mix()

Hover and active colours should not be separate hand-picked tokens that you must remember to update in every theme. Derive them:

The hover colour is recomputed from whichever --primary applies, so adding a brand never means adding a hover colour.

Following the Operating System: light-dark()

Tailwind CSS Fundamentals 8 showed how to follow prefers-color-scheme with the dark: variant. The token system has a tidier option: the CSS function light-dark(a, b), which picks its first argument when the element's color-scheme is light and its second when dark. Define each token once, and let an attribute override the system choice:

With no attribute the page follows the system; an explicit data-mode wins either way, which is what a theme toggle needs (three states: system, light, dark). The light-dark() function needs color-scheme to be set on an ancestor, which is why :root declares light dark. Compared with duplicating a dark block inside @media (prefers-color-scheme: dark), each token is written once with both values side by side. One of my own runs went wrong at this point and is in the "Mistakes" box. Setting color-scheme is also what tells the browser to draw its built-in controls and scrollbars in the matching scheme (documented behaviour; I did not look at the controls).

Colour That Scales: oklch

oklch(L C H) describes a colour by lightness (0 to 1), chroma (how vivid) and hue (an angle in degrees). Tailwind v4's own palette is written in it, which is why you saw values such as oklch(58.8% 0.158 241.966) in the generated file. For a theme system its great advantage is practical: to make a new brand you keep lightness and chroma and change the hue. I built a three-step scale on one variable, --hue:

This only works with @theme inline, for the reason in the previous section (the hue must be read on the element). Two details in the output matter. First, the opacity modifier (/20) works on a variable-based colour, and the browser resolves it to an oklab value with 0.2 alpha. Second, here is the rule Tailwind generated for it:

The first declaration is the fallback for a browser without color-mix(), and it is the full-strength colour, not a 20% one. In a modern browser you will never see it (Chrome 154 reported support for oklch, color-mix and light-dark), but if you support older browsers, a translucent overlay can turn opaque there. Check your support target before relying on /20 for anything that must stay see-through.

Wide-Gamut Colour and Its Fallbacks

oklch can describe colours that an ordinary sRGB screen cannot show; "wide gamut" screens (Display P3) can show more. I asked the browser what happens to an out-of-range colour on my (sRGB) setup by drawing it and reading the pixel back:

So out-of-range colours do not break; the browser maps them to the nearest displayable colour. Two practical rules follow:

• Keep your base tokens inside sRGB so every user sees the colour you chose. Test it the way I did: draw the colour and read it back; a channel stuck at exactly 0 or 255 (like the 0 and 0 above) means it was clipped.
• Upgrade for wide-gamut screens on purpose: put the vivid value in @media (color-gamut: p3) { :root { --accent: oklch(0.7 0.3 150); } }, so only displays that can show it receive it. I confirmed that the query becomes true under the P3 flag; I could not check how it looks, because I have no wide-gamut display and the canvas reads back sRGB only.

The build tool helps with one case. With --optimize, a color(display-p3 …) value gets an sRGB fallback line above it (color: #00f942; then color: color(display-p3 0 1 0);), but an oklch() value is left alone, and values inside custom properties are never rewritten. So the safety net is your own design rule, not the compiler.

Spacing, Type and Radius as Tokens

The same @theme mechanism that holds colour holds every scale. Each namespace creates utilities, and one line can move a whole family:

Look at the second row of results: text-white stopped working after I wrote --color-*: initial, because white is part of the colour namespace. If you reset the palette, define white, black and transparent yourself if you still use them. Resetting is the right move for a strict design system (no one can reach for bg-red-500), and the wrong move for a project that mixes semantic and palette colours.

Documenting the System

A token set that nobody can see is a token set that people bypass. Two cheap checks keep the documentation honest. The first is a report built from Tailwind's own output, grouped by namespace; the one I wrote (about 15 lines of Node, in the exercise) printed this for the file above:

Two honest limits. The report shows only tokens that the page uses (that is the rule from chapter 1), and it cannot list @theme inline tokens at all, since they are not written to the output. For those, read your source file. The second check is the contrast table from the multi-theme section: a small page that renders every theme and measures every text/background pair, run before you ship a new brand colour. I ran it by hand; wiring it into continuous integration is up to you and is not run here.

Hands-On Exercises