Tokens in Tailwind, CSS Variables, and CSS-in-JS

Style Dictionary's CSS platform output generates a file of CSS custom properties: --color-primary-500: #3b82f6; --spacing-4: 16px; and so on. These variables are defined on :root, making them available globally. This is the foundation for all token consumption in the application.

Import the generated CSS token file in your global stylesheet or in the root layout component: @import './tokens/tokens.css'. In Next.js, import it in app/layout.tsx or styles/globals.css. Once imported, every CSS rule and component in the application can reference the custom properties.

Reference CSS variables in component stylesheets or CSS Modules: background-color: var(--color-primary-500); and padding: var(--spacing-4);. If the token value changes in the JSON source, rebuilding Style Dictionary updates the CSS file, and all components using that variable reflect the new value automatically.

CSS custom properties enable runtime theme switching. For dark mode, override token values under a theme selector: [data-theme="dark"] { --color-background: #1a1a2a; --color-text: #f0f0f0; }. Setting document.documentElement.setAttribute('data-theme', 'dark') switches all token values instantly without reloading or rebuilding.

Extend Tailwind's theme in tailwind.config.js to use token values: theme: { extend: { colors: { primary: { 500: tokenOutput.color.primary[500] } } } }. Import the JS output from Style Dictionary into the Tailwind config to ensure Tailwind classes (bg-primary-500) always use the authoritative token values.

For runtime-switchable themes in Tailwind, configure the color to reference a CSS variable: 'primary': 'rgb(var(--color-primary-rgb) / <alpha-value>)'. This requires your CSS variable to store the RGB components without the rgb() wrapper (--color-primary-rgb: 59 130 246). Tailwind then handles opacity utilities automatically.

CSS-in-JS libraries use a JavaScript theme object. Pass the Style Dictionary JS output as the theme provider value: <ThemeProvider theme={tokens}>. Components access tokens via const theme = useTheme() and theme.color.primary[500]. Style Dictionary generates the typed token object; the theme provider distributes it.

The stylelint-no-hardcoded-colors plugin and custom ESLint rules can enforce that no hardcoded hex values appear in stylesheets or component files. If a developer writes color: #3b82f6 instead of color: var(--color-primary-500), the linter flags it. This keeps the token system as the only color source.

When Tailwind class names are constructed dynamically from token names at runtime, Tailwind's purge may remove those classes because they don't appear as static strings in the source. Add dynamic class patterns to the safelist in tailwind.config.js: safelist: [{ pattern: /bg-primary-/ }].

The Figma Tokens plugin exports Figma token values directly to the Style Dictionary JSON format. The workflow: designers update colors in Figma Variables, export via the plugin, commit the updated JSON, the prebuild script runs Style Dictionary, and the updated CSS and JS outputs are used in the React app. Design and code stay synchronized.

CSS custom properties are scoped to the element they are defined on and their descendants. This enables component-level theme overrides: a card component can set --color-background: var(--color-surface-elevated) on its root element, and all descendants use the elevated surface color without any prop drilling.

What is the key advantage of using CSS custom properties (variables) for design tokens over static Tailwind values?

Style Dictionary outputs CSS custom properties for global import and JS objects for Tailwind and CSS-in-JS integration. CSS variables enable runtime theme switching via [data-theme] overrides. Tailwind extends its config with token values from the JS output; for opacity-aware theming, configure Tailwind to reference RGB CSS variables. Lint rules enforce token-only color usage, keeping hardcoded values out of the codebase.