Skip to content
← Back to Blog
Updated Kersten Lorenz 5 min read

Design tokens: the API between design and code

ui engineering opinion

Every team I’ve worked with eventually builds a design system. Sometimes it starts as a Figma file called “Components v4 FINAL (use this one).” Sometimes it’s a Storybook that nobody updates past the first sprint. Sometimes it lives entirely inside one senior designer’s head, and everyone else reverse-engineers decisions from screenshots.

These all fail the same way. Design drifts from code. Code drifts from design. Six months in, the button in production has a border-radius that matches nothing in the spec, the primary colour exists in four slightly different hex values across three repositories, and nobody can say which one is canonical. The design system didn’t fail because people stopped caring. It failed because nothing enforced the contract between what was designed and what was built.

After twenty-five years of building interfaces, I’ve come to see this as an API problem. Designers and engineers are two systems that need to communicate. When the interface between them is a PDF spec, a Slack message, or tribal knowledge, the integration breaks. Design tokens are the API that holds it together.

What design tokens actually are

A design token is a named value that represents a design decision. Not a CSS variable, though it can become one. Not a Sass constant. A platform-agnostic, semantic unit of design that can be consumed by any target: web, iOS, Android, PDF, email templates.

{
  "color": {
    "primary": {
      "$type": "color",
      "$value": { "colorSpace": "srgb", "components": [0.267, 0.757, 0.71], "hex": "#44c1b5" }
    },
    "surface": {
      "$type": "color",
      "$value": { "colorSpace": "srgb", "components": [0.949, 0.949, 0.949], "hex": "#f2f2f2" }
    }
  },
  "spacing": {
    "md": { "$type": "dimension", "$value": { "value": 16, "unit": "px" } }
  }
}

That’s the W3C Design Tokens Community Group format, stable since version 2025.10. It looks simple because the format is the easy part. The hard part is the decision architecture underneath it.

A design token isn’t a variable. It’s a decision with a name, a value, and a reason to exist.

Material Design 3 structures tokens in three tiers: reference tokens (the full palette), system tokens (role-based mappings like color.primary), and component tokens (the specific values a button or card consumes). This hierarchy is what makes the system powerful. You can swap an entire colour scheme by changing one layer without touching component code. The tiers absorb change at the right level of abstraction. It is the same principle that makes good software architecture resilient.

Atomic design needs a vocabulary

Brad Frost’s atomic design gave us the structural language for component systems: atoms, molecules, organisms, templates, pages. It’s a brilliant framework for organising what you build. But it’s silent on the values those components consume. Where does the colour come from? The spacing? The radius? Atomic design describes the grammar of a design system. Design tokens provide the vocabulary.

A button atom doesn’t hardcode #44C1B5. It references color.primary. A card molecule doesn’t set padding: 16px. It reads spacing.md. When the brand evolves, you swap the token set. The same goes for a dark mode, a high-contrast accessibility theme, or a white-label variant for a client. The components don’t change. The contract holds.

Imagine an orchestra where every musician brings their own tuning fork. They’re all playing the same notes, but nothing sounds right. Design tokens are the shared tuning — one reference pitch that every instrument agrees on.

This separation is what makes design systems actually scale. Without it, every theme is a fork. Every brand variant is a parallel codebase. Every accessibility mode is a guilt-ridden TODO that never ships.

The toolchain that closes the loop

The idea of design tokens has been around for a decade. What’s changed is the toolchain. The gap between “good idea” and “working pipeline” has finally closed.

Style Dictionary is the build system. Define tokens once in JSON or YAML, and Style Dictionary transforms them into CSS custom properties, iOS Swift constants, Android XML resources, Tailwind configuration, whatever your platforms need. One source, many outputs. It’s open source and extensible enough that most teams never outgrow it. Amazon started it; Tokens Studio now co-maintains it.

Tokens Studio connects Figma to Git. Figma itself has imported and exported tokens in the W3C format since November 2025. Tokens Studio adds the sync: designers manage tokens inside Figma and push them to a Git repository. Engineers pull the same tokens through Style Dictionary. Designers stop being upstream of a handoff and start being co-authors of the same source of truth. Changes flow through version control, not screenshots in Slack.

Penpot takes a different path entirely. It’s an open-source design tool that treats tokens as first-class citizens in its core data model. Where Figma bolted on variables after years of requests, Penpot made design tokens a native feature in 2025 (version 2.6), built with the Tokens Studio team. For teams that want full control over their design infrastructure (especially those running self-hosted or open-source stacks), Penpot removes the vendor lock-in that makes token workflows fragile.

The best design system is the one both designers and engineers can change without filing a ticket.

Tokens as the interface for AI

Here’s the connection I keep coming back to. Design tokens aren’t just a bridge between designers and engineers. They’re a bridge between humans and agents.

An AI agent generating a UI component doesn’t need to guess the spacing scale or approximate the brand colour from a screenshot. If the token set lives in the repository, the agent reads spacing.lg and color.surface the same way a human engineer would. Semantic naming does double duty: it communicates intent to people and constrains output for machines. The more explicit your design decisions are, the more reliably agents can respect them.

This works in the other direction too. Agents can extract implicit decisions scattered across stylesheets and surface them as an auditable token set: the magic numbers, the one-off colours, the spacing values that almost-but-don’t-quite follow a scale. I’ve seen what would have been a two-week design-system audit collapse into an afternoon.

Design tokens are structured decisions that both humans and agents can read, both can write, and neither has to guess about. That’s not a nice-to-have. It’s the foundation of any AI-native design workflow.

The cost of not having them

Teams without design tokens don’t notice the cost at first. The inconsistencies are small: 14px here, 16px there. A colour that’s #44C1B5 in the header and #43C0B4 in the footer because someone eyedropped a compressed JPEG.

Then the rebrand hits. Or the accessibility audit. Or the second product that needs to share the design language. Suddenly every component is a snowflake, every change is a grep-and-pray across twelve files, and the “design system” is a Notion page with screenshots from six months ago.

I’ve been through enough of those rebrands to know: the cost of establishing tokens on day one is a fraction of extracting them later. Like most architectural decisions, the right time to make it is before you need it.

Design tokens don’t prevent design drift. They make it visible, measurable, and fixable — before it becomes technical debt with a colour palette.

Building a design system that scales, or bringing structure to one that’s already drifted? Interlusion builds token-driven design infrastructure that keeps design and code in sync from the first commit. Let’s talk.

Share: