Design Tokens in Practice: Structuring Color for Scalable Systems

Design tokens are named, role-defined variables that represent design decisions — color, typography, spacing, and other visual properties — in a form that can be consumed by both design tools and production code. For color, tokens are the mechanism that connects a palette definition to the components and surfaces that use it. A token-based color architecture makes the system auditable, maintainable, and adaptable in ways that direct hex-value assignment does not. The standard architecture for color tokens uses three tiers. The primitive tier contains raw color values without semantic meaning — cobalt-500: #3b82f6, amber-300: #fcd34d. These are just color definitions with no context about how they should be used. The semantic tier maps primitives to roles — text-primary, surface-default, border-subtle, action-primary. Semantic tokens have meaning independent of specific color values; they describe the design intention. The component tier maps semantic tokens to specific UI elements — button-background, card-border, input-placeholder. Components know only about their component tokens, not about primitives or color values. This three-tier architecture enables several workflows that flat token systems cannot support. Brand refresh: replace the primitive values and the semantic and component tiers update automatically, assuming the semantic mapping remains valid. Multi-theme support: define different semantic-to-primitive mappings for each theme, and the entire system switches at the semantic layer. Accessibility audit: the semantic tier provides a complete map of every color role in the system, making systematic contrast checking tractable. Debug: when a component has the wrong color, the three-tier trace (component → semantic → primitive) makes the source of the error unambiguous. Token naming is underestimated as a design decision. Names that encode value (gray-100, blue-500) are easy to populate but create ambiguity about intent — is blue-500 an action color, an informational color, or a brand accent? Names that encode role (action-primary, interactive-default) communicate intent but can become verbose and rigid. Hybrid systems — short semantic names with optional primitive reference — balance readability with precision. The key rule is that token names should communicate the design intention (what is this color for?) rather than the color value (what color is this?). Figma Variables and Tokens Studio are the primary tools for managing token systems in design files. Both support multi-mode token sets (light/dark, brand variants) and can export token JSON for consumption by code-side build tools. The critical workflow is bidirectional sync: token values should flow from design to code through an automated pipeline, not manual copy-paste. Any color change in Figma should propagate to production through the pipeline without human intermediary, eliminating the class of bugs created by designer-to-developer translation errors.