# Design Tokens Tailwind

> Generate or update Tailwind CSS v4 CSS-first theme variables from design token JSON files. Use this skill whenever the user asks to sync, convert, regenerate, import, or update styles, Tailwind config, @theme CSS, colors, typography, spacing, breakpoints, shadows, radii, or other design tokens from design-tokens.json or another token JSON file, especially in Tailwind 4 projects that use CSS-first configuration instead of tailwind.config.js. This skill is reusable across projects and should be used even when the user only says "update styles from tokens" or provides a token export path.

- Skill: `ilya-valasiuk/design-tokens-tailwind` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add ilya-valasiuk/design-tokens-tailwind`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ilya-valasiuk/design-tokens-tailwind/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: ilya-valasiuk (https://skillmd.com/u/ilya-valasiuk)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ilya-valasiuk/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:

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

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

   ```bash
   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:

   ```bash
   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:

```json
{
  "$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:

```css
--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:

```bash
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.