Setting Up an Automated Figma-to-Tailwind Token Pipeline
A step-by-step tutorial on extracting design variables from Figma and generating zero-runtime, type-safe Tailwind tokens.
1. Token Contract & Schema Design
Structuring primitives vs semantic alias tokens.
Before writing transformation scripts, designers and developers must agree on a predictable naming taxonomy: - **Tier 1 — Global Primitives:** Pure values devoid of semantic context (e.g., `slate.900 = #0f172a`). - **Tier 2 — Semantic System Tokens:** Purpose-driven abstractions (e.g., `surface.primary = slate.900`). - **Tier 3 — Component Scoped Overrides:** Optional component-specific variants (e.g., `button.primary.hover`).
This hierarchy ensures that changes to the global brand color propagate downstream without breaking semantic contrast ratios.
2. Fetching Variables via the Figma REST API
Using Figma's Variables API to extract collection data.
With a Figma Personal Access Token or OAuth application, you query the `/v1/files/{file_key}/variables/local` endpoint to retrieve all published variable collections, modes (e.g., Light vs Dark), and resolved values.
// Fetch Figma Variables Script
async function fetchFigmaTokens(fileKey: string, token: string) {
const res = await fetch(`https://api.figma.com/v1/files/${fileKey}/variables/local`, {
headers: { 'X-Figma-Token': token },
});
if (!res.ok) throw new Error(`Failed to fetch Figma variables: ${res.statusText}`);
const data = await res.json();
return data.meta.variables;
}3. Transforming JSON to CSS Custom Properties
Emitting zero-runtime CSS files for light and dark modes.
The raw Figma JSON output is normalized into clean CSS custom property declarations: - RGB values are mapped to modern `rgb(r g b / alpha)` formats to support Tailwind's opacity modifier syntax (e.g. `bg-primary/50`). - Spacing numbers are converted to explicit `rem` units based on a standard 16px root baseline.
4. Integrating with Tailwind CSS Configuration
Configuring theme colors to reference semantic CSS variables.
In your `tailwind.config.ts`, map color scales to the generated CSS variables: ```ts // tailwind.config.ts snippet export default { theme: { extend: { colors: { surface: { base: 'var(--surface-base)', elevated: 'var(--surface-elevated)', }, brand: { cyan: 'var(--brand-cyan)', }, }, }, }, }; ``` This gives your engineering team full autocomplete in VS Code and guaranteed synchronization with Figma.
5. Automated Pull Request Workflows
Triggering token rebuilds on design updates.
A Figma webhook triggers a GitHub Actions workflow whenever design system variables are published. The action generates the updated CSS, runs TypeScript validation and test suites, and opens an automated pull request with a visual diff preview.