Design tokens are the single source of truth for the visual language of a product. Instead of hard-coding colors and spacing in components, you reference named values that can change in one place.
This guide walks through how we structure tokens, how they map to themes, and how to adopt them without a disruptive migration.
We split tokens into three tiers: primitives, semantic tokens, and component tokens. Primitives are raw values, semantic tokens describe intent, and component tokens bind intent to a specific part.
Keeping these tiers separate means a rebrand touches primitives only, while component code keeps referring to the same semantic names.
Each theme remaps the semantic tier. A dark theme overrides background and foreground tokens, and every component that reads those names updates automatically with no per-component work.
Because the contract is the token name, you can ship a new theme without touching a single component file.
Roll out tokens incrementally. Start with color, then spacing, then typography, shipping each tier behind the same review process you already use.
Within a few sprints the hard-coded values are gone and every surface speaks the same visual language.