From design tokens to a Tailwind v4 theme
Tailwind v4 moved the theme out of tailwind.config.js and into CSS: an @theme block of variables, where the name decides the utility. --color-surface gives bg-surface and text-surface, --radius-md gives rounded-md, --text-body gives text-body with its own line height. That makes design tokens and Tailwind a natural fit, as long as every token lands in the right namespace.
This tool does the mapping. Colours go to --color-, spacing and sizes to --spacing-, radii to --radius-, font families to --font-, weights to --font-weight-, type sizes and typography styles to --text- with their line height, letter spacing and weight, shadows to --shadow-, easing curves to --ease- and breakpoints to --breakpoint-*. Tokens Tailwind has no namespace for, like durations or z-index, are written as plain variables beside the theme.
Which token files it reads
- The W3C design tokens format (DTCG): tokens with $value and $type, a group's $type passed down to its tokens, $description written as a comment. Figma's variables export and most plugins write this format.
- Tokens Studio: tokens with value and type, token sets like global, light and dark, with $themes and $metadata ignored.
- Plain nested JSON: any object of values, with each type worked out from the value and its name.
Composite tokens are written out in full: typography as its size, family, weight, line height and letter spacing; shadows, borders, gradients and transitions as their CSS.
Light and dark modes
Modes come in two ways. Drop one file per mode, such as light.json and dark.json, and each file becomes a mode named after it. Or keep one file with top-level sets named light and dark beside your primitives, the way Tokens Studio and many Figma exports do.
The first mode becomes :root; every other mode is written only with the tokens that change, under [data-theme="dark"], .dark, or the system setting. For Tailwind v4 the tool also writes the matching @custom-variant, so dark: utilities follow the same switch.
Aliases, and the problems worth fixing
An alias like {color.gray.900} points one token at another. With Keep aliases as var() on, it stays a reference in the CSS, var(--color-gray-900), so a dark mode only has to change the semantic tokens and the primitives stay put. Turn it off to get every value resolved.
Aliases are where token files break. The problems list names each one by its path: an alias pointing at a token that doesn't exist, a loop of aliases that point at each other, a token that exists in dark but not in light, and two tokens that would write the same CSS name.
Private, and checked against the real compiler
Your token files never leave your browser. The Tailwind output is written for Tailwind v4's own rules, and I check it against the Tailwind compiler so each utility resolves to its token. Building a whole design system? See how I work as a design engineer, or try the fluid typography calculator for a type scale.