Design Tokens and Theming

To build a digital product that feels cohesive and polished, every button, font, and spacing must be consistent across every screen and platform. This is incredibly difficult without a systematic approach. Design tokens are the foundational solution, transforming subjective design choices into structured, reusable data that powers entire design systems and enables dynamic theming with precision.

What Are Design Tokens?

At their core, design tokens are platform-agnostic variables that store visual design attributes. Think of them as the single source of truth for your design system’s visual DNA. Instead of a developer hard-coding a hex value like #007AFF directly into a button component, they reference a token named color-action-primary. The token itself holds the value #007AFF. This abstraction is powerful because if the brand blue changes to #0066CC, you update the token’s value in one place, and it propagates everywhere the token is used—across web, iOS, Android, and other platforms.

Tokens are used to define nearly every visual property:

• Colors: Brand colors, neutrals, semantic colors (success, error, warning).
• Typography: Font families, sizes, weights, and line heights.
• Spacing: A scale of units for margins, padding, and gaps (e.g., 4px, 8px, 16px).
• Sizing: Dimensions for icons, avatars, and containers.
• Border Radius: Values for rounding corners.
• Elevation: Shadows and opacities to create depth.
• Opacity: Standardized transparency levels.

The Semantic Layer: From Primitive to Contextual

A robust token system is organized in layers, moving from raw values to meaningful context. This structure is key to enabling theming.

1. Primitive Tokens: These are the raw, foundational values. They are named for their literal value, not their purpose (e.g., color-blue-500, spacing-8, font-size-16). They are the building blocks.
2. Semantic Tokens (or Alias Tokens): These tokens apply meaning and context. They reference primitive tokens (or other semantic tokens) to define how a value should be used. Examples include color-background-primary, color-text-interactive, spacing-card-padding, or font-heading-large.

Here’s the crucial relationship: A semantic token color-background-primary might point to the primitive token color-gray-50 in a light theme. For a dark theme, that same semantic token would point to color-gray-900. The component code only ever uses the semantic token, so switching the theme only requires reassigning which primitives the semantic tokens alias to.

Building a Theming System

Theming is the practical application of a layered token architecture. It allows you to change the entire appearance of an interface—from light mode to dark mode, or from Brand A to Brand B—by swapping out a set of token values. A theme is essentially a collection of token assignments.

To build a theming system, you follow a clear process:

• Define Primitives: Establish the palette of raw values for each theme (Light Theme Primitives, Dark Theme Primitives, Brand B Primitives).
• Define Semantic Tokens: Create the full set of semantic names that describe the UI's parts (background, text, border, primary, etc.).
• Map Semantics to Primitives: For each theme, create a mapping layer that connects every semantic token to a primitive token from that theme's set. This mapping is the theme itself.
• Implement with a Context Provider: In code, a theme provider component (like React's Context or CSS custom properties scoped to a data attribute) wraps the application and supplies the current set of token values. Components consume these tokens.

For example, your CSS might use variables:

/* Theme Definition */
[data-theme="light"] {
  --color-background-primary: var(--color-gray-50);
  --color-text-primary: var(--color-gray-900);
}
[data-theme="dark"] {
  --color-background-primary: var(--color-gray-900);
  --color-text-primary: var(--color-gray-50);
}

/* Component Usage */
.card {
  background-color: var(--color-background-primary);
  color: var(--color-text-primary);
}

Scaling for Multi-Platform and Multi-Brand Systems

The true power of tokens is realized in complex environments. A well-structured token system scales to support multiple platforms (Web, iOS, Android) and multiple brands or product lines within an organization.

• Platform-Agnostic Format: Tokens are first defined in a neutral format like JSON or YAML. This becomes the single source of truth.
• Transformation and Delivery: Tools or pipelines then transform this core token file into platform-specific outputs: CSS variables for the web, Sass variables, Swift code for iOS, XML for Android, and even JSON for design tools like Figma. This ensures visual parity everywhere.
• Multi-Brand Scalability: By leveraging the primitive/semantic layer, you can create entirely new brand themes. The semantic structure (the "slots" like primary, secondary) remains constant, but you populate them with a different brand's primitive values. This allows a single codebase to power multiple branded products while maintaining consistency within each.

Common Pitfalls

1. Naming Tokens by Value Instead of Role: Creating a token called color-blue-500 is a primitive. Stopping there is a mistake. You must also create semantic tokens like color-action-primary that reference it. If you only use primitives directly in components, changing a theme requires finding and replacing every instance of blue-500, which is error-prone and defeats the purpose.

• Correction: Always drive component styling through semantic or alias tokens. Primitives should only be referenced by other tokens, not directly by UI components.

1. Creating an Incomplete Token Set: Starting with colors but neglecting spacing, typography, or radius leads to inconsistency. Developers will fill the gaps with arbitrary values, breaking system harmony.

• Correction: Audit your core visual styles upfront. Define a foundational scale for spacing, type, and radius early, and document them as tokens. It’s better to start with a small but complete foundational set than a large, partial one.

1. Ignoring Theming from the Start: Building a system with only a light theme in mind makes retrofitting dark mode or another brand theme a painful, breaking change.

• Correction: Adopt a semantic naming structure from day one, even if you initially only have one theme. The extra upfront thought makes future theming a simple data swap, not a system rewrite.

1. Letting Tokens and Design Tools Diverge: When designers update styles in Figma but the token repository isn't synchronized, the code and design immediately fall out of sync.

• Correction: Establish a workflow where token changes are made in the central source (the code repository or a dedicated token management tool) and then automatically synced to the design tool via plugins, or vice-versa with strict governance.

Summary

• Design tokens are the cornerstone of modern design systems, acting as the single source of truth for visual style data stored as named variables.
• A layered structure—separating raw primitive tokens from meaning-driven semantic tokens—is essential for enabling flexible theming and maintaining consistency.
• Theming systems work by remapping semantic tokens to different sets of primitive values, allowing for mode switches (light/dark) and multi-brand support without altering core component logic.
• A scalable token system is platform-agnostic, transformed from a central format into the specific code needed for web, native, and design tools.
• Effective token management requires foresight in naming, completeness in foundational scales, and processes to keep design and development tools in sync.