Frontend
    October 2, 2026•5 min read

    A two-tier design token system with Tailwind v4

    Primitive colour ramps for reference, semantic tokens for components. How splitting tokens into two tiers keeps dark mode and rebrands to a single file.

    Anonymous
    A two-tier design token system with Tailwind v4

    Most colour bugs come from components reaching for raw palette values like bg-blue-500. A two-tier token system makes that impossible: primitives describe colours, semantic tokens describe roles, and components only ever see the roles.

    Defining the tiers

    Tailwind v4 is configured in CSS, so both tiers live in one stylesheet. Only the semantic tier is exposed to utilities:

    CSS
    1:root {
    2  --blue-500: oklch(0.62 0.19 260);
    3  --primary: var(--blue-500);
    4}
    5
    6.dark {
    7  --primary: oklch(0.7 0.16 260);
    8}
    9
    10@theme inline {
    11  --color-*: initial;
    12  --color-primary: var(--primary);
    13}

    Because --color-*: initial clears the default palette, bg-blue-500 no longer exists. Components write bg-primary, and dark mode is handled entirely by the .dark block.

    Why it pays off

    • Dark mode is one block of overrides, not a dark: variant on every element.
    • A rebrand changes which primitive a role points at, in one place.
    • Code review gets easier: any raw colour in a component is a bug by definition.
    #Tailwind CSS
    Share: