tailwind-dictionary

A Tailwind CSS 3 or 4 theme from design tokens in the DTCG or Style Dictionary format, with light, dark and other themes.

tailwind-dictionary builds a Tailwind theme from design tokens: theme.css for Tailwind 4 or theme.js for Tailwind 3. It is based on Style Dictionary and is used to build pbstyles.

Resources: npm · GitHub · Changelog · Playground.

Why this package

JSON config, no code. One config.json with token paths and theme aliases. No JS/TS build script to maintain.
DTCG and the legacy format. Reads W3C Design Tokens (DTCG 2025.10) ($value, $type, composite typography and shadow) as exported by Figma, Tokens Studio and Terrazzo. The legacy Style Dictionary format (value) is supported too and gives the same output.
Themes on any DOM level. Light, dark and any other themes (high-contrast, brands) switch with the data-theme attribute on <html> or on a nested container. Light and dark also follow prefers-color-scheme. Works with a Tailwind utility prefix.

Quick start

npm install --save-dev tailwind-dictionary

Create config.json. The $schema field enables autocompletion and validation of the config in VS Code.

{
  "$schema": "./node_modules/tailwind-dictionary/schema/config.schema.json",
  "version": 4,
  "source": ["tokens/**/*.json"],
  "output": "./styles",
  "themeAliases": { "color": "color", "spacing": "1px", "radius": "rounded" }
}

Build the theme and import it after Tailwind:

npx tailwind-dictionary

@import 'tailwindcss';
@import './styles/tailwind/theme.css';

Sections

Config and CLI

config.json fields, theme aliases for Tailwind 3 and 4, command-line flags.

DTCG tokens

The new format: $value, $type, typography, shadow, breakpoints and animations without the mixin field.

Legacy format

Style Dictionary tokens with the value field and mixins via the mixin field.

Themes

Light, dark and other themes, data-theme on any element, variable prefix.

API and watch mode

build() and generate() from code, TypeScript types, rebuild on token changes.

Playground

Build the result from your own tokens right in the browser, with nothing to install.

What's new in 2.5

DTCG 2025.10 input and composite typography and shadow tokens.
Breakpoints and animations are built from the token structure, the mixin field is no longer required.
Any number of themes and themes.default.
Programmatic API, TypeScript types, JSON Schema of the config and --watch.
Clear one-line errors with the token path and the file name.

Configs and tokens of version 2.3 work without changes. In theme.css only whitespace changed, and the output differs only where there used to be a bug: for example, tokens with the value 0 are no longer dropped from the v4 theme. The full list of changes and fixes is in the CHANGELOG.