What Are Design Tokens

Design tokens represent the smallest pieces of a design system. They store visual design attributes as named entities, enabling consistent application of colors, typography, spacing, and other properties across products and platforms.

What Is a Design Token

A design token is a named variable that stores a specific design decision. Rather than using raw values like #2563eb or 16px throughout code, tokens provide semantic names like color-primary or spacing-medium. This abstraction layer separates design intent from implementation details.

Tokens typically store values for colors, typography scales, spacing units, border radii, shadows, and animation timings. The token name communicates purpose while the value can change without requiring updates to every usage location.

How Design Tokens Work

Design tokens function as a translation layer between design tools and code. Designers define tokens in tools like Figma, and automated pipelines transform these definitions into platform-specific formats. A single token definition might generate CSS custom properties, Swift constants, and Kotlin values simultaneously.

The token pipeline typically follows this flow: source definition, transformation, and distribution. Source files often use JSON or YAML formats that tools like Style Dictionary can process. Transformations apply platform-specific formatting, unit conversions, and naming conventions. Distribution packages tokens for consumption by web, iOS, Android, and other platforms.

Token values reference other tokens through aliasing. A semantic token like button-background-primary might reference a primitive token like blue-600. This layering enables theme switching and brand customization without changing component code.

Key Considerations

• Token names should communicate purpose rather than appearance
• Primitive tokens hold raw values while semantic tokens reference primitives
• Token structures require planning for multi-brand and multi-theme scenarios
• Automation reduces manual synchronization errors between design and code
• Version control for token files enables tracking changes over time
• Documentation helps consumers understand available tokens and usage patterns

Common Questions

How do design tokens differ from CSS variables?

CSS custom properties are one output format for design tokens, not the tokens themselves. Design tokens exist as platform-agnostic definitions that generate CSS variables alongside Swift constants, Kotlin values, and other platform formats. Tokens provide the source of truth while CSS variables serve as one implementation.

When should teams adopt design tokens?

Teams benefit from design tokens when maintaining consistency across multiple platforms, supporting theming requirements, or scaling design systems beyond a single application. The overhead of establishing token infrastructure pays off when synchronization between design and development becomes difficult to manage manually.

Summary

Design tokens provide named abstractions for visual design values, enabling consistency across platforms and simplified maintenance. Token pipelines automate the translation from design tools to platform-specific code formats. Semantic naming and aliasing patterns support theming and brand customization without component-level changes.