Design System Integration

When to Use

Connecting a design tool (Figma) or token management system to Tailwind configuration — maintaining consistency between design and implementation.

Decision

Tool/Need	Approach
Figma Variables → Tailwind tokens	Tailwind Tokens Figma plugin or manual export
Token JSON → multiple outputs (CSS, JS, SCSS)	Style Dictionary
Manual sync (small team)	Export Figma Variables as CSV, maintain @theme manually
Monorepo token sharing	CSS @import of shared theme.css
Token validation in CI	npx style-dictionary build in pipeline

Pattern — Style Dictionary Integration

// tokens/colors.json (Figma export or hand-authored)
{
  "color": {
    "brand": {
      "500": { "value": "oklch(0.65 0.18 260)", "type": "color" },
      "600": { "value": "oklch(0.55 0.20 260)", "type": "color" }
    }
  }
}

// style-dictionary.config.js
module.exports = {
  source: ['tokens/**/*.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      prefix: 'color',
      buildPath: 'src/styles/',
      files: [{ destination: '_tokens.css', format: 'css/variables' }],
    },
  },
};

/* Generated _tokens.css — import into your Tailwind CSS file */
:root {
  --color-brand-500: oklch(0.65 0.18 260);
  --color-brand-600: oklch(0.55 0.20 260);
}

/* styles.css — reference generated tokens inside @theme */
@import "tailwindcss";
@import "./_tokens.css";

@theme inline {
  /* Alias CSS vars as Tailwind theme tokens */
  --color-brand-500: var(--color-brand-500);
}

Naming Conventions for Cross-Tool Consistency

Design tool naming	Tailwind token naming	Generated utility
color/brand/500	--color-brand-500	bg-brand-500
spacing/4	--spacing-4 (or default scale)	p-4, m-4, gap-4
radius/md	--radius-md	rounded-md
shadow/card	--shadow-card	shadow-card
font/display	--font-display	font-display

Rule: Use Tailwind's namespace pattern in your design tool. Tokens named with / separators in Figma map cleanly to --namespace-* patterns with forward slashes converted to hyphens.

Common Mistakes

• Naming tokens by component (--button-background) instead of role (--color-primary) — component-named tokens don't reuse across components; semantic/role tokens do
• Skipping a token management pipeline and hand-translating hex values — drift starts immediately; automate the sync
• Not locking token names to a versioned contract — a designer renaming brand-blue to cobalt in Figma breaks all downstream consumers without a versioning strategy

See Also

• Performance & Optimization
• Component Patterns
• Design System Recognition Guide (separate guide — identify tokens first)
• Reference: https://styledictionary.com/
• Reference: https://www.figma.com/community/plugin/1513618945140968492