Design Tokens Tailwind

Design Tokens to Tailwind 4 CSS

Use this skill to turn design token JSON into Tailwind CSS v4 CSS-first configuration. The expected output is CSS containing an @theme { ... } block, usually written to a shared theme file such as src/styles/theme.css.

Tailwind v4 generates utilities from theme variables defined in @theme, so token names and namespaces matter. Favor deterministic conversion over hand-editing whenever the input is a token file.

Default Paths

Use these defaults when the project has the same shape as j70 and the user does not provide different paths:

• Token input: design-tokens.json
• Theme output: src/styles/theme.css
• Frontend entry: src/styles/globals.css
• Payload admin entry: src/styles/payloadStyles.css

For other projects, discover the paths before editing:

• Prefer a token file explicitly provided by the user.
• Otherwise look for design-tokens.json, tokens.json, src/design-tokens.json, or a similarly named JSON export.
• Prefer an existing CSS file that already contains @theme.
• Otherwise write to a sensible shared CSS file such as src/styles/theme.css, app/globals.css, or src/app/globals.css, following the project's existing Tailwind entry point.

If the project uses split CSS like frontend/admin styles, keep generated tokens in a shared imported theme file instead of duplicating them across entries.

Workflow

1. Inspect the token JSON and existing CSS before editing. Determine whether the project already uses Tailwind v4 CSS-first config.

2. If the user asks about Tailwind behavior, migration, syntax, or why a namespace is used, fetch current Tailwind CSS documentation with Context7 first.

3. Prefer the bundled converter script for normal JSON-to-@theme generation. From this skill directory, run:

   node scripts/generate-tailwind-theme.mjs design-tokens.json src/styles/theme.css
   

   From a project repository, use the absolute path to the script:

   node /path/to/design-tokens-tailwind/scripts/generate-tailwind-theme.mjs design-tokens.json src/styles/theme.css
   

4. If the user provides another token JSON path, pass it as the first argument and choose the output CSS as the second:

   node /path/to/design-tokens-tailwind/scripts/generate-tailwind-theme.mjs path/to/tokens.json src/styles/theme.css
   

5. Review the generated CSS before finalizing. Preserve intentional project-specific tokens that are not represented in the JSON only when the user or surrounding code clearly depends on them.

6. Ensure the generated theme file is imported by the project's Tailwind CSS entry point. Add or adjust an import only if the project is missing one.

7. Run a focused verification command after editing, such as npm run typecheck, npm run lint, or npm run build, choosing based on the size of the change and project norms.

Conversion Rules

Use Tailwind v4 theme namespaces so utilities are generated naturally:

• Color tokens become --color-*
• Font family tokens become --font-*
• Font size tokens become --text-*
• Line heights for font sizes become --text-*--line-height
• Font weight tokens become --font-weight-*
• Letter spacing tokens become --tracking-*
• Spacing tokens become --spacing-*
• Radius tokens become --radius-*
• Shadow tokens become --shadow-*
• Breakpoint tokens become --breakpoint-*
• Easing tokens become --ease-*
• Animation tokens become --animate-*

Normalize token names for Tailwind ergonomics:

• Strip descriptive Figma annotations after ---, so blue.500---main becomes blue-500.
• Convert spaces, underscores, slashes, and punctuation to single hyphens.
• Lowercase token names.
• Convert grey to gray unless the existing project clearly uses grey utilities.
• Preserve numeric scale names such as 100, 500, 2xl, and 4xl.
• Avoid duplicate declarations; when several typography variants share the same size and line height, emit one --text-* pair.

Convert numeric pixel values to rem where Tailwind utilities expect CSS lengths. Use a 16px root unless the project has an explicit different root scale:

• 16 or 16px becomes 1rem
• 20 or 20px becomes 1.25rem
• 0 remains 0

Keep hex colors, rgb(), oklch(), CSS variables, and other valid CSS color strings as-is. Preserve values that are already CSS expressions such as calc(...), clamp(...), and var(...).

Typography Guidance

Many design exports represent typography as composite objects:

{
  "$type": "typography",
  "fontFamily": "Figtree",
  "fontStyle": "Bold",
  "fontSize": 44,
  "lineHeight": 56
}

When the token path already has a semantic text name such as h1, body-sm, or caption, preserve that name unless the project has an established numeric text scale. For j70, map common pixel sizes to the existing compact scale:

• 12px -> xs
• 14px -> sm
• 16px -> md
• 18px -> lg
• 20px -> xl
• 24px -> 2xl
• 28px -> 3xl
• 44px -> 4xl

Emit the size and line-height pair:

--text-4xl: 2.75rem;
--text-4xl--line-height: 3.5rem;

Do not create separate text utilities for every weight variant when the size and line-height are identical. Use Tailwind font-weight utilities for weight differences instead. Emit font-weight variables only when the token JSON contains standalone font-weight tokens.

Script Options

The bundled script accepts:

node scripts/generate-tailwind-theme.mjs [tokens.json] [output.css] [--dry-run] [--font-var=var(--font-figtree)]

• --dry-run prints CSS without writing.
• --font-var=... controls the emitted --font-sans value. Use this when the project’s Next/font variable differs from var(--font-figtree).
• --no-font-sans skips the default --font-sans declaration for projects that manage fonts elsewhere.
• --preserve-existing merges generated declarations into an existing @theme block where possible instead of replacing the whole output file.

Quality Bar

A good update should:

• Leave a valid CSS @theme block.
• Match Tailwind v4 variable namespaces.
• Keep generated values deterministic and sorted by token category.
• Avoid adding a JavaScript Tailwind config to a CSS-first Tailwind 4 project.
• Avoid manually editing generated Payload or migration files.
• Avoid introducing a tailwind.config.js for Tailwind 4 CSS-first projects unless the user explicitly asks.
• Mention unsupported token categories in the final response instead of silently pretending they were converted.