Choosing design tokens

Choose tokens by the role an element plays, not by the raw value that happens to look right today. This keeps design and code resilient to theming and system-wide changes.

Selection order

1. Use a component token when the component provides one for the property.
2. Use a semantic token for a role such as foreground text, background, border, action, or status.
3. Use a primitive token only when defining a semantic or component token, not when composing product UI.

For example, choose the semantic foreground token for a muted label rather than a gray primitive, and choose the component’s defined action token rather than a generic blue value.

Match the token family to the decision

• Need color, status, contrast, or surface layering? Start with Color.
• Need padding, gap, alignment, or a layout dimension? Start with Spacing.
• Need hierarchy, readability, or an interactive label? Start with Typography.
• Need depth or a layered surface? Start with Elevation.
• Need a transition or interaction timing value? Start with Motion.

Before introducing a token

First check whether a semantic or component token already expresses the role. Create a new token only when the role will be reused across the system and can be named independently of one component or one screen. Keep Figma variables and code token names aligned. Avoid hard-coding visual values in product UI; use the documented semantic or component token instead.

See the Design Tokens reference for the complete catalog and usage guidance.