Design Tokens Explained: Primitive, Semantic and Component Tokens

What are design tokens?

Design tokens are named values that store design decisions, such as a brand color, a font size, a spacing step or a corner radius, in a form both designers and developers use. Instead of a button using the hex value for a particular blue, it uses a token called color-action. Change the token once, and every place that uses it updates.

Tokens are the foundation of any design system, including the lean kind most startups need. Our guide to design systems for startups explains where tokens fit among components, patterns and documentation. This article goes deeper on how to structure and name them, and shows one token in Figma, CSS and Tailwind CSS v4 so designers and developers can see they're the same thing.

What are primitive, semantic and component tokens?

Primitive, semantic and component tokens are the three layers most token systems use. Primitives are the raw palette, semantic tokens give each value a purpose, and component tokens apply purposes to a specific component. Each layer refers to the one below it, which is what makes theming and rebrands cheap.

• Primitive tokens describe what a value is: blue-600, gray-100. They're the full palette and scale, and nothing in the UI should use them directly.
• Semantic tokens describe what a value is for: color-background, color-text, color-border, color-action, color-danger. These are the tokens components use.
• Component tokens describe where a value is used: button-primary-bg. They're optional, and most startups can skip them until a component needs to differ from the semantic default.

How should you name design tokens?

Name design tokens with a consistent pattern that reads from general to specific: category, then purpose, then variant or state. A name like color-text-muted tells you it's a color, used for text, in its muted variant. Good token naming means people can guess the right token without looking it up.

• Use one pattern everywhere. Category, property, variant, state: color-border-subtle, color-action-hover.
• Name semantic tokens by purpose, not appearance. color-danger survives a change from red to orange; color-red does not.
• Keep primitives descriptive. blue-600 or gray-100 are fine, because primitives are meant to describe the raw value.
• Match names across tools. The Figma variable, the CSS variable and the Tailwind utility should share the same name, allowing for each tool's syntax.
• Avoid one-off tokens. If only one element uses a value, it may not need a token yet.

How does one design token look in Figma, CSS and Tailwind v4?

One design token looks almost identical in Figma variables, CSS custom properties and Tailwind v4, which is the point: the name stays the same and only the syntax changes. Here is the semantic token color-action traced from design to a utility class.

Two Tailwind v4 details matter here. First, Tailwind v4 configures the theme in CSS with the @theme directive instead of a JavaScript config file, so your token file and your Tailwind theme can be the same CSS. Second, when a theme token refers to another variable, as the semantic token does here, it goes in an @theme inline block so the utility uses the variable's live value and dark mode works.

Setting up the Figma side is covered in our guide to Figma variables, and keeping the two in sync over time, manually or with an export step, is covered in syncing Figma variables to Tailwind.

Which design token structure should a startup use?

A startup should use a two-layer design token structure, primitives and semantic tokens, with a small, fixed set of semantic names. That's enough for theming, dark mode and a future rebrand, and simple enough that everyone on the team can learn it in an afternoon.

1. Primitives: your color palette in steps, a spacing scale, a type scale, a few radii and shadows.
2. Semantic colors: background, surface, text, text-muted, border, action, action-hover, danger, warning, success and focus.
3. Semantic type: a handful of text styles such as display, heading, body, small and label. See our guide to type and spacing scales.
4. Spacing and radius: usually used directly from the scale, since spacing rarely needs a semantic layer at this stage.

If you're building on shadcn/ui, much of this structure already exists: its components read semantic CSS variables for background, foreground, primary, muted, border and so on. Mapping your own tokens onto those names is one of the quickest ways to make a themed base look like your product. Our comparison of shadcn/ui vs a custom design system covers when that base is enough.

How do brand colors and typography become design tokens?

Brand colors and typography become design tokens by turning the brand guidelines into primitives, then mapping them to semantic roles in the product. The brand blue becomes a primitive scale, the primary role points to one step of it, and the brand typefaces become font tokens used by a small set of text styles.

The tricky part is that brand palettes are usually built for marketing, not for interfaces. A product needs more neutral steps, accessible contrast for text and states for hover, focus and disabled. Plan for a few extra primitives beyond the brand guide. Our guide to brand colors and typography as tokens goes into the details.

Where do design tokens go next?

Design tokens are moving toward a shared, tool-neutral format, so the same file can feed design tools, CSS and native platforms. The W3C's Design Tokens Community Group works on a common specification for this. For most startups today, CSS variables in a Tailwind v4 theme plus mirrored Figma variables are already a practical single source.

Once tokens are in place, the next steps are components built on them and short documentation on which token to use when. Our guides to component libraries in Figma and design system documentation cover both.