Tailwind CSS & Figma Design Token Workflow: Variables, Themes, CSS

1. The problem: Figma and Tailwind speak different languages

In almost every web project that works with Figma and Tailwind CSS, the same scenario eventually plays out: the designer changes the primary color from #0369a1 to #0284c7, and the developer has to manually update the Tailwind CSS configuration. This manual step is error prone, slow, and does not scale, at the latest not once several designers and several developers are working simultaneously on a growing design system.

The real problem is not the color itself, but the missing mechanism that ensures design decisions are automatically and consistently carried over into code. Design tokens solve exactly this problem. They are the shared language between Figma and Tailwind CSS, a machine readable layer of named design values that both sides can read and process. Once this workflow is set up, an entire class of synchronization errors is eliminated from the development process.

2. What design tokens really are, and what they are not

Design tokens are named abstractions over design decisions: colors, spacing, font sizes, radii, shadows, and animation durations. The decisive difference from a plain variable is that a design token carries semantic meaning. Instead of #0369a1, it is called color.action.primary.default. The value can change without all references in the code needing to be updated, only the token value changes, and the new value propagates automatically through the entire system.

Design tokens are not Tailwind CSS classes and not Figma styles alone. They exist as a technology neutral format, typically JSON or YAML, that serves as the source for several output formats: CSS custom properties for the browser, Swift constants for iOS, XML resources for Android. In a Tailwind CSS environment, this format is used to generate CSS custom properties that are then referenced directly in the Tailwind CSS configuration. The tokens are the single source of truth; Figma and Tailwind CSS are merely consumers.

The W3C Design Tokens Community Group adopted a formal standard for the token format in 2024. Figma aligned its Variables API with it, and Style Dictionary supports the format natively. Anyone adopting this standard now is well positioned for the future of the design system toolchain.

3. Setting up Figma Variables as a token source

Figma Variables, introduced with Figma 2023, are the native implementation of design tokens in Figma. They support four types: Color, Number, String, and Boolean. For a design token workflow with Tailwind CSS, the first two are the most important. The recommended structure follows a two tier architecture: primitive tokens define raw values without semantics (blue-600, space-4), while semantic tokens reference primitive tokens and carry meaning (action-primary references blue-600).

In Figma, you set up collections for these tiers: a collection named "Primitives" with all raw values, and a collection "Semantic" with all meaning bearing aliases. Within each collection, modes can be defined, Light and Dark for the color scheme, or Brand A and Brand B for multi brand setups. These modes later correspond to the Tailwind CSS themes. Each variable gets a hierarchical name with a slash separator: color/action/primary/default, which later becomes color-action-primary-default as a CSS custom property.

/* Figma Variables → exported as W3C Design Token JSON */
/* tokens/primitives.json: raw values without semantic meaning */
{
  "color": {
    "blue": {
      "100": { "$value": "#e0f2fe", "$type": "color" },
      "600": { "$value": "#0284c7", "$type": "color" },
      "900": { "$value": "#0c4a6e", "$type": "color" }
    },
    "neutral": {
      "0":   { "$value": "#ffffff", "$type": "color" },
      "100": { "$value": "#f8fafc", "$type": "color" },
      "900": { "$value": "#0f172a", "$type": "color" }
    }
  },
  "space": {
    "1": { "$value": "4px",  "$type": "dimension" },
    "4": { "$value": "16px", "$type": "dimension" },
    "8": { "$value": "32px", "$type": "dimension" }
  }
}

4. Token export from Figma: plugins and formats

Figma does not offer a native export function for Variables in the W3C token format. Several plugins exist for this: "Variables to JSON" and "Tokens Studio for Figma" (formerly Figma Tokens) are the most widely used. Tokens Studio additionally offers bidirectional synchronization with GitHub, GitLab, or a dedicated token repository. This means designers push token changes directly from Figma into a Git repository, and the CI pipeline automatically processes them into CSS.

For teams without Tokens Studio, a simple plugin that exports the Variables as JSON is sufficient. The resulting JSON should then be versioned in the project repository, ideally under tokens/. Important during export: the references between semantic and primitive tokens must be preserved so that Style Dictionary can resolve the aliases correctly. Do not export as a flat list of values, but as hierarchical JSON with references ({ "$value": "{color.blue.600}" }).

5. Style Dictionary: transforming and outputting tokens

Style Dictionary from Amazon is the standard tool for transforming design tokens into platform specific outputs. It reads the token JSON, resolves references, applies configurable transforms, and writes output files. For a Tailwind CSS workflow, the relevant output is a CSS file with custom properties. Style Dictionary v4 supports the W3C token format natively and offers a modern, configuration based API.

The Style Dictionary configuration defines which token files are read, which transforms are applied (for example converting colors to hex format, converting dimensions to rem), and which output files are generated. For Tailwind CSS v4, the ideal output is a CSS file that is included in the @layer theme block. Every CSS custom property corresponds to a design token and can be referenced directly in Tailwind CSS utilities.

// style-dictionary.config.mjs: Token transformation pipeline for Tailwind CSS
import StyleDictionary from 'style-dictionary';

const sd = new StyleDictionary({
  source: ['tokens/**/*.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      prefix: 'ds',
      buildPath: 'src/styles/tokens/',
      files: [
        {
          // Output: CSS custom properties for Tailwind CSS integration
          destination: 'primitives.css',
          format: 'css/variables',
          filter: token => token.filePath.includes('primitives'),
          options: {
            selector: ':root',
            outputReferences: false,
          }
        },
        {
          destination: 'semantic.css',
          format: 'css/variables',
          filter: token => token.filePath.includes('semantic'),
          options: {
            // Preserve references so output reflects token hierarchy
            selector: ':root',
            outputReferences: true,
          }
        }
      ]
    }
  }
});

await sd.buildAllPlatforms();
// Result: --ds-color-action-primary-default: var(--ds-color-blue-600);

6. Registering CSS custom properties in Tailwind CSS v4

Tailwind CSS v4 has undergone a fundamental paradigm shift: configuration no longer happens in tailwind.config.js, but directly in CSS via @theme. This makes integrating design tokens as CSS custom properties substantially more elegant than in v3. You import the CSS files generated by Style Dictionary and register the custom properties as Tailwind theme values using the --color-*, --spacing-*, or --radius-* pattern.

The mechanism: Tailwind CSS v4 scans the @theme block and automatically generates utility classes for all defined variables. A variable --color-action-primary: var(--ds-color-action-primary-default) in the @theme block generates the classes bg-action-primary, text-action-primary, border-action-primary, and every other color related utility. This means the designer changes a color in Figma, the token pipeline runs, and updated Tailwind CSS classes are immediately available, without changing a single line of configuration manually.

/* src/styles/main.css: Tailwind CSS v4 entry with Design Token integration */
@import "tailwindcss";

/* Import Style Dictionary output, auto-generated from Figma Variables */
@import "./tokens/primitives.css";
@import "./tokens/semantic.css";

/* Register tokens as Tailwind CSS theme values */
@theme {
  /* Map semantic tokens → Tailwind CSS utility names */
  --color-primary:       var(--ds-color-action-primary-default);
  --color-primary-hover: var(--ds-color-action-primary-hover);
  --color-secondary:     var(--ds-color-action-secondary-default);
  --color-surface:       var(--ds-color-surface-default);
  --color-on-surface:    var(--ds-color-on-surface-primary);

  /* Spacing tokens → Tailwind spacing scale */
  --spacing-xs:  var(--ds-space-1);
  --spacing-sm:  var(--ds-space-2);
  --spacing-md:  var(--ds-space-4);
  --spacing-lg:  var(--ds-space-8);
  --spacing-xl:  var(--ds-space-16);

  /* Border radius tokens */
  --radius-sm:   var(--ds-radius-small);
  --radius-md:   var(--ds-radius-medium);
  --radius-lg:   var(--ds-radius-large);
  --radius-full: var(--ds-radius-full);
}

/* Usage in HTML: class="bg-primary text-on-surface rounded-md p-md" */

7. Multi-theme support with Tailwind CSS and CSS layers

One of the biggest advantages of a clean design token workflow with Tailwind CSS is elegant support for multiple themes. Dark mode is the simplest example, but the mechanism scales to any number of themes: Brand A and Brand B, white label setups, seasonal themes, or accessibility modes with increased contrast. The prerequisite is that all theme dependent values are defined as CSS custom properties, which is automatically the case thanks to the design token workflow.

Style Dictionary exports Figma Variable Modes as separate output files. Light mode defines the custom properties on :root, dark mode overrides them on [data-theme="dark"] or .dark. Tailwind CSS v4 offers the @variant dark directive for this, which reacts to the strategy chosen by the theme. Switching the theme at runtime only requires changing an attribute or a class on the root element, all Tailwind CSS utilities immediately pick up the new token values.

8. Automating the pipeline: CI/CD and watch mode

The full benefit of the design token workflow only unfolds through automation. In local development, a watch process monitors the token JSON files and automatically runs Style Dictionary on changes. The script npm run tokens:watch combines Style Dictionary in watch mode with the Tailwind CSS build, so a token change becomes visible in the browser as an updated CSS file within seconds.

In the CI/CD pipeline, npm run tokens:build is run as the first step before the CSS build. This ensures that every build is always generated from the current token values. If Tokens Studio is synced with GitHub, a PR from the designer that changes token values automatically triggers the build pipeline. The developer sees the visual impact of the token change in the PR preview, without manual intervention. This complete automation is the goal of the entire design token workflow.

9. Direct comparison: manual maintenance vs. token workflow

The difference between manual color maintenance and an automated design token workflow with Tailwind CSS becomes especially clear once design changes need to be carried through to production.

The investment in the design token workflow pays off from the second theming project onward. Once the token pipeline is set up, every new project can start with it, saving time on every design change that previously went into manual synchronization. Teams that combine Tokens Studio and Tailwind CSS v4 report up to 80% less effort when implementing design system changes.

10. Summary

The Tailwind CSS Figma design token workflow eliminates manual synchronization between design and code. Figma Variables are exported as W3C compliant tokens, transformed by Style Dictionary into CSS custom properties, and registered directly in Tailwind CSS v4 as theme values. The result: every change in Figma propagates automatically through the entire frontend codebase, without a developer ever having to touch a configuration file.

The key components are: Figma Variables with a primitive/semantic structure, a token export plugin, Style Dictionary for the transformation, Tailwind CSS v4 with @theme integration, and an automated build pipeline. Multi-theme support, from dark mode to multi brand, is not a special case in this workflow but a natural consequence of the CSS custom properties architecture. Teams that adopt this workflow report significantly reduced friction between design and development.

11. FAQ: Tailwind CSS & Figma Design Token Workflow