Design Tokens in Practice: The Workflow That Bridges Design and Code

Design tokens sound simple: reference "primary" instead of hardcoding #3B82F6. Change the token, everything updates. In practice, most teams maintain tokens in two places -- Figma and code -- and they inevitably drift. Three months later, seventeen shades of blue in production.

Our fix: code is the single source of truth, not Figma. Figma is a design tool, not a database. Tokens in Figma are hard to version control, impossible to validate with tests, and painful to review in PRs.

The workflow has four steps. Step one: define tokens in a TypeScript file. Colors as semantic names mapping to HSL values, spacing scale, typography, radii, shadows. Typically 80 to 120 lines.

Step two: generate Tailwind config from the token file. A build script restricts available utility classes to token-defined values only. Developers cannot use off-system values because they do not exist in the config.

Step three: generate CSS custom properties from the same file. This enables dynamic theming -- dark mode is different custom property values, not different Tailwind classes.

Step four: sync tokens back to Figma. We export the token file as JSON and import via Tokens Studio. The designer works with the same names and values. Sync is manual, at most weekly.

The critical decision: code is upstream, Figma is downstream. When the designer wants to change a color, we update the token file first, regenerate all outputs, then sync to Figma.

For dark mode, we define two token sets in the same file using the same semantic names with different values. Adding dark mode to a properly tokenized project takes about two hours. Adding it to a project with hardcoded colors takes days.

We also include component-level tokens for repeated patterns. For example, "input-border" resolves to "border" by default but to "destructive" in error states. These sit between global tokens and component code, allowing targeted adjustments without touching either the palette or the implementation.

Investment: three hours for initial setup, thirty minutes per design update. The payoff is consistency enforced at the tooling level. No more "which shade of gray is this" conversations. The tokens are the answer, and they live in one place.