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

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

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

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

/* 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.