Design Systems 101: Design Tokens and Variables

Part one of this series covered component libraries and the building blocks of a design system. This post goes one level deeper: the named values that make those components consistent across every tool, every screen, and every contractor who touches your site.

What design tokens are (and why the name matters)

Design tokens are named values that store visual design decisions. Instead of writing #0D99FF every time you need your brand blue, you write color-primary. Instead of typing 16px for body text throughout a stylesheet, you reference font-size-base.

Google’s Material Design 3 defines design tokens as “small, reusable design decisions that make up a design system’s visual style.” Every color, spacing value, typographic setting, shadow, and border-radius decision your brand makes can be a token.

Hard-coded values vs. tokens: the practical difference

Without tokens, a site’s visual values live in many places: a Figma file, a CSS stylesheet, a React component, and the instructions you emailed to the developer you hired six months ago. When a color changes, every one of those places needs an update. Some get updated. Some do not. The result is visual drift.

With tokens, the value lives in one place with one name. Every downstream system references that name. When the value changes, the update propagates everywhere the token is used.

A single source of truth across design and code

The U.S. Web Design System (USWDS) implements its entire visual language through tokens for this reason. A federal agency working with multiple contractors on multiple products needs every team building from the same palette of approved values. The token layer makes that coordination possible without a weekly meeting.

For a Houston small business working with a designer and a developer at the same time, the problem is identical at a smaller scale.

The three layers of tokens

Most mature token systems organize values into three tiers. Understanding the tiers separates a token system that scales from a flat list of variables that gets messy fast.

Global tokens: raw values

Global tokens (also called primitive tokens) hold raw values with no context attached.

--blue-500: #0d99ff;
--spacing-4: 16px;
--font-weight-bold: 700;

These names describe what the value is, not where it is used. You should never reference global tokens directly in component styles.

Semantic tokens: contextual meaning

Semantic tokens (alias tokens) map a global value to a meaning.

--color-primary: var(--blue-500);
--spacing-base: var(--spacing-4);

These names describe the role, not the raw value. A component references --color-primary, not --blue-500. That distinction matters when you add dark mode: you update what --color-primary points to, and nothing else changes.

Component tokens: scoped to a single element

Component tokens tie a semantic token to one specific UI element.

--button-background: var(--color-primary);
--button-font-size: var(--font-size-base);

This level is where granular overrides live without breaking the broader system. You can adjust a card’s internal spacing without touching anything outside it.

Design tokens in Figma

Figma launched Variables at Config 2023, describing the feature as “connecting design to the language of code.” Variables store color, number, text, and boolean values and support the same alias structure as a token hierarchy.

Variables replaced the older Styles system for token work. Styles store visual properties but do not support aliasing or theming. Variables support both, plus modes (light/dark, brand A/brand B). Styles remain useful for typography settings until Figma expands Variables to cover more type properties.

Connecting Figma to CSS

A Figma Variable named color/primary maps to a CSS custom property named --color-primary. That naming pattern, enforced consistently in both tools, is what makes the handoff work without a manual conversion step. A token name should encode category (color, spacing, font), role or scale position (primary, base, 500), and optionally state (hover, disabled).

CSS custom properties: the implementation layer

CSS custom properties are the browser-native home for design tokens. You define them on :root and reference them anywhere in your stylesheet.

:root {
  --color-primary: #0d99ff;
  --spacing-base: 16px;
}

.button {
  background: var(--color-primary);
  padding: var(--spacing-base);
}

Tailwind v4’s CSS-first configuration uses exactly this pattern: design decisions are defined as CSS custom properties in a @theme block, and utility classes consume them with no build-time transformation.

Pre-built token systems: Style Dictionary

Style Dictionary is an open-source build system Amazon released in 2017 that transforms a JSON token definition into platform-specific outputs: CSS custom properties, iOS Swift variables, Android XML, and others. It is the right tool when tokens need to reach native mobile platforms in addition to the web.

For web-only projects, defining tokens directly as CSS custom properties is simpler and requires no build step. The W3C Design Tokens Community Group (DTCG) published its Final Community Group Report in October 2025, specifying an interoperable JSON format for exchanging tokens between tools.

How tokens support dark mode and theming

Dark mode is the clearest demonstration of why the three-tier system pays off. Global tokens never change: --blue-500 is always #0d99ff in both themes. Semantic tokens change their reference.

:root {
  --color-background: #ffffff;
  --color-text: #111111;
}

.dark {
  --color-background: #111111;
  --color-text: #f5f5f5;
}

Every component using --color-background and --color-text gets the correct values in both modes without a single component-level change. The theming logic lives entirely in the alias layer. Brand theming works the same way: switch one semantic token file and the entire visual identity updates.

The minimum viable token system for a small business site

Not every project needs all three tiers from day one. Four categories cover most sites immediately.

Color: Brand primary, secondary, neutral scale (gray-100 through gray-900), and semantic aliases (background, text, border, interactive). For the strategy behind color decisions, the psychology of color in web design covers the fundamentals.

Typography scale: Body size, a heading scale (h1 through h4), and line-height values. Six to eight tokens covers most sites.

Spacing scale: A base unit (4px or 8px) with multipliers: spacing-1 through spacing-8. Consistent spacing is the single change that most improves the visual polish of a self-built site.

Border-radius: One or two values: radius-sm for interactive elements, radius-md for cards and containers.

Skip motion, elevation, and grid tokens until you have a component library that needs them. A flat token file with 30 well-named values does more work than a sophisticated architecture with 300 poorly named ones.

Our work on Applied Matter shows what this looks like in practice: a structured token architecture that kept a multi-channel brand system coherent across both design files and production code. The Detail Exchange rebuild used the same approach to lock down visual consistency after years of drift.

If your design and development workflow feels like two teams speaking different languages, a token system is how you give them shared vocabulary. Let’s talk about your project and see what a structured handoff looks like for your site.

Up next in this series: how to document and govern a design system so it stays useful as your team grows. Our brand design services include design token architecture as part of every visual identity engagement.

---

Frequently asked questions

What is an example of a design token?

A design token pairs a name with a value. A global token might be blue-500 = #0D99FF. A semantic token built on top of it might be color-primary = blue-500. A component token goes one level further: button-background = color-primary. That chain means you only change the hex code in one place to update every button across your site.

What are design tokens in Figma?

Figma launched Variables at Config 2023 as its native design-token implementation. Variables store reusable color, number, text, and boolean values that map directly to CSS custom properties in your codebase. A designer sets color-primary in Figma Variables; a developer references --color-primary in CSS. When the brand color changes, both update from the same source.

What is the difference between a design system and design tokens?

A design system is the full collection of guidelines, components, patterns, and documentation that governs how a product looks and behaves. Design tokens are one layer within that system: the named values for color, spacing, typography, and other visual properties. Think of the design system as the rulebook and tokens as the vocabulary those rules are written in.