---
name: tailwind-design-tokens
description: "Tailwind v4 design tokens, theme layers, dark mode, and the Figma → Tailwind sync — one source of truth. Builds the design-token pipeline: Figma variables → Style Dictionary → Tailwind v4 @theme — colors, type, spacing, radii all synced."
license: MIT
---

# Tailwind Design Tokens Architect

A skill for building a single-source-of-truth token pipeline that flows from Figma variables through Style Dictionary into Tailwind v4's `@theme` block. It's aimed at frontend engineers and design-systems teams who are tired of hand-copying hex codes out of Figma and want colors, type, spacing, and radii to stay in sync across design and code.

## When to use it

- You've adopted (or are migrating to) Tailwind v4's CSS-first config and need to express tokens as `@theme` custom properties instead of a `tailwind.config.js` `theme.extend` object.
- A designer ships Figma Variables (including modes for light/dark) and you want them compiled into usable Tailwind utilities.
- Your codebase has drifted: Figma says one brand blue, the CSS says another. You want one authoritative source.
- You're standing up dark mode and want it driven by token modes rather than scattered `dark:` overrides.

## How it works

The skill scaffolds and wires three stages:

1. **Figma → JSON.** Pulls Variables via the Figma REST API (`GET /v1/files/:key/variables/local`, requires an enterprise file) or ingests an exported W3C Design Tokens (DTCG) JSON file when the API isn't available.
2. **Style Dictionary transform.** Generates a `config` (e.g. `style-dictionary.config.js`) with a custom CSS format that emits `--color-*`, `--font-*`, `--spacing-*`, and `--radius-*` variables matching Tailwind v4's namespace conventions. Modes map to separate selectors.
3. **Tailwind v4 `@theme`.** The build output is imported into your main stylesheet so Tailwind auto-generates utilities (`bg-brand-500`, `text-fg`, `rounded-card`) from the variables.

Dark mode uses `@custom-variant dark` against the mode selector the token build produces.

## Example

```bash
curl -fsSL --create-dirs -o ~/.claude/skills/tailwind-design-tokens/SKILL.md https://claudeskil.com/skills/tailwind-design-tokens/SKILL.md
npx style-dictionary build --config style-dictionary.config.js
```

```css
/* app.css */
@import "tailwindcss";
@import "./tokens/theme.css";   /* generated */

@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));
```

```css
/* tokens/theme.css (generated) */
@theme {
  --color-brand-500: #2f6fed;
  --color-fg: #0b0c0e;
  --radius-card: 0.75rem;
}
[data-theme="dark"] { --color-fg: #f5f6f7; }
```

## Tips & gotchas

- Tailwind v4 only turns a custom property into a utility if it sits under a recognized namespace (`--color-`, `--spacing-`, `--font-`, `--radius-`, etc.). Tokens named outside these won't generate classes — the skill enforces the naming on export.
- Reference tokens (aliases like `{color.brand.500}`) must resolve at build time; Style Dictionary won't emit `var()` chains unless you opt into the `outputReferences` option.
- Put `@import "./tokens/theme.css"` *after* `@import "tailwindcss"` or your overrides get clobbered.

## FAQ

**Do I need a paid Figma plan?** Variable read access via the API is Enterprise-gated. Without it, export tokens as DTCG JSON and the pipeline runs identically.

**Does this replace `tailwind.config.js`?** For tokens, yes — v4 reads theme values from CSS. You can still keep a JS config for plugins.

**Can it round-trip code back to Figma?** No. The flow is one-directional: Figma is the source, code is the consumer.