A Tailwind theme from design tokens, in one command
tailwind-dictionary turns JSON tokens from Figma, Tokens Studio or Style Dictionary into a Tailwind CSS 4 or 3 theme — with light, dark and any other themes. One config.json instead of a build script.
Try it yourself
Paste your tokens into the playground — the theme builds right in the browser, nothing to install. Or install the package and run one command.
What you get
A palette and the light and dark theme colors in DTCG format — and the theme the package builds from them. This is real build output: switch the Tailwind version to compare.
Tokens
{
"color": {
"$type": "color",
"white": { "$value": "#ffffff" },
"gray": { "900": { "$value": "#111827" } },
"blue": {
"400": { "$value": "#60a5fa" },
"600": { "$value": "#2563eb" }
}
},
"radius": {
"$type": "dimension",
"12": { "$value": { "value": 12, "unit": "px" } }
}
}Theme
:root {
--theme-color-background: #ffffff;
--theme-color-primary: #2563eb;
}
@media (prefers-color-scheme: dark) {
:root:not([data-theme='light']) {
--theme-color-background: #111827;
--theme-color-primary: #60a5fa;
}
}
[data-theme='dark'] {
--theme-color-background: #111827;
--theme-color-primary: #60a5fa;
}
[data-theme='light'] {
--theme-color-background: #ffffff;
--theme-color-primary: #2563eb;
}
@theme {
--*: initial;
--color-*: initial;
--color-white: #ffffff;
--color-gray-900: #111827;
--color-blue-400: #60a5fa;
--color-blue-600: #2563eb;
--radius-12: 12px;
}
@theme inline {
--color-background: var(--theme-color-background);
--color-primary: var(--theme-color-primary);
}Why a separate package
A Tailwind theme edited by hand drifts away from the design over time. If colors and sizes already live in tokens, build the theme from them.
Always in sync with the design
The designer updated a color in Figma, you exported the variables and ran one command. No hunting for where that color is written in CSS and no checking that nothing got lost.
Why not Style Dictionary?
Style Dictionary is a powerful tool, but you would have to describe the Tailwind theme format, @theme, semantic variables and theme switching yourself, in a JS script you also have to maintain. Here it is already done, covered by tests and configured with JSON.
A JSON config, no code
Token paths and their mapping to Tailwind theme keys live in one config.json. The JSON Schema suggests fields right in the editor.
Figma export as is
Export modes in Figma gives one file per mode — plug them in without conversion. Unitless numbers get px or rem.
DTCG and the legacy format
The W3C Design Tokens 2025.10 format with composite typography and shadow. Style Dictionary tokens with a value field work too.
Any number of themes
Light, dark, high-contrast or brand themes. They switch with a data-theme attribute on any element; light and dark follow the system setting.
Tailwind 4 and 3
For v4 — theme.css with @theme, for v3 — an object for tailwind.config.js. The tokens are the same for both versions.
Clear errors and watch mode
A broken token reference is one line with the token path and file name. In watch mode the theme rebuilds on every token change.
Themes on any element
The block below is built on the pbstyles theme that tailwind-dictionary generates. The switch changes only the data-theme attribute on the container — the classes stay the same.
Weekly report
Background, text, border and button colors come from the semantic tokens of the current theme.
<section data-theme="dark">
<div className='bg-basic-0 rounded-16'>
<h3 className='text-basic-400'>…</h3>
<Button color='primary'>…</Button>
</div>
</section>From Figma to code in four steps
An example for Tailwind 4 and the native Figma variables export. For Tokens Studio and Style Dictionary, only the file paths change.
- 01
Export the variables
In Figma: Variables → right-click the collection → Export modes. You get a file with primitives and one file per mode.
tokens/ Primitives.tokens.json Light.tokens.json Dark.tokens.json - 02
Describe the config
Primitives go to source, modes go to themes. In themeAliases, specify which token groups map to which Tailwind theme keys.
config.json { "version": 4, "source": ["tokens/Primitives.tokens.json"], "themes": { "light": ["tokens/Light.tokens.json"], "dark": ["tokens/Dark.tokens.json"] }, "output": "./styles", "themeAliases": { "color": "color", "radius": "radius", "spacing": "1px" } } - 03
Build the theme
Run npx tailwind-dictionary and import the result after Tailwind. The default Tailwind theme is replaced with your tokens.
globals.css @import 'tailwindcss'; @import './styles/tailwind/theme.css'; - 04
Write regular classes
Classes are built from your tokens: bg-primary, rounded-12. In the dark theme, bg-primary becomes a different color on its own — no markup changes needed.
page.tsx <button className='bg-primary rounded-12 px-16 py-8'> Save </button>
In a real project
The pbstyles theme is built with tailwind-dictionary — it is the foundation of the design system behind this site and its docs. The pbstyles config is public, so you can use it as a template.
- Tailwind CSS versions
- 4 and 3
- DTCG format version
- 2025.10
- license
- MIT
Who it is for
A good fit if
- your tokens already live in Figma, Tokens Studio or Style Dictionary
- the project uses Tailwind CSS 4 or 3
- you need light, dark or brand themes
- the theme should be built from tokens, not edited by hand
Not a fit if
- there are no tokens and won't be — a few variables are easier to write in @theme by hand
- the project doesn't use Tailwind — for CSS variables, LESS and SCSS there is mixin-dictionary
- you need custom Style Dictionary transforms and formats — then your own build script is more convenient
Need help?
I can help set up the Figma export, themes and style builds in your project.