Design Token Usage Guidelines

Quick Start

These guidelines help you select the right design tokens while maintaining system consistency and enabling optimal user experiences.

What Are Semantic and Cross-Semantic Tokens?

Semantic Example

Badge: Uses space-small for padding. Badges are small, so they use small space.

Cross-Semantic Example

Button: Is usually small, but uses space-200 (medium space) for padding. This makes it easier to tap, even though it is bigger than normal for a small button.

Semantic tokens are the sizes or colors you are supposed to use for each part, like the right padding for a badge.

Cross-semantic token usage means using a size or color in a different way than usual, because you have a special reason (like making something easier to use).

In short:

Semantic = use the size or color as the system says.

Cross-semantic = use a different size or color for a good reason.

Token Selection Hierarchy

Follow this hierarchy when selecting tokens for your components. Each level provides a fallback when the previous approach doesn't meet your functional requirements.

Refer to Existing Component & Template Patterns

When semantic tokens don't meet functional requirements, follow documented component family templates with pre-approved cross-semantic patterns.

Use Semantic Tokens if it's a New Component

Always start with tokens that match your component's semantic size classification.

Component Size Classifications:

Size	Description	Token Range
Small	Compact components for dense layouts	`space-25 to space-150`
Medium	Standard components for typical interfaces	`space-200 to space-400`
Large	Prominent components for emphasis	`space-500 to space-1000`

Component Spacing Visualization

Component Container

padding

Element 1

↕ gap spacing

Element 2

↔ inline spacing

Button 1

Button 2

Use Cross-Semantic Tokens if Visually Requires

Use tokens from different semantic categories when documented patterns support functional needs. Requires proper justification.

Escalation

For new patterns not covered by existing templates, document reasoning and escalate to the design system team.

When is Cross-Semantic Usage Okay?

Sometimes you need to use a different size or color than what the system says. That's totally fine if you have a good reason—like making something easier to use, more readable, or more accessible.

Is it okay?	Why?	Examples
Yes	Accessibility or usability	Making buttons easier to tap, improving readability, helping screen readers, etc.
Yes	Functional needs	Grouping things, making layouts clearer, making forms easier to use, etc.
Yes, if...	Aesthetic preference, but...	You have a clear reason, it doesn't break consistency, and it won't cause more design problems later.
No	Just because "it looks better" (with no reason)	Changing things for style only, if it makes the system messy or inconsistent, or if it creates more work down the line.
No	Breaks consistency or creates design debt	One-off changes that don't fit with the rest, or that force other parts to change too.

When to Ask for Help

Sometimes you'll run into something that doesn't fit any of our existing patterns. Here's when you should reach out to the design system team and what to include.

These Things Definitely Need Review

Situation	How Urgent	Why We Need to Know
You Need This Pattern Everywhere	high	If you're going to use this spacing in lots of places, we should probably make it official
Nothing We Have Works	high	You've tried all our templates and none of them solve your problem
Accessibility Issues	critical	You can't make something accessible with our current tokens
Rules Don't Make Sense	medium	Following our guidelines would make the user experience worse

What to Tell Us

What We Need	How Important	Why This Helps
What component and where you're using it	must have	We need to understand the context to give good advice
What you're trying to accomplish	must have	Tell us what user need you're trying to solve
What tokens you want to use and why	must have	Show us your thinking so we can build on it
How this might affect other things	must have	Help us spot any unintended consequences
Any user research or testing	nice to have	Evidence that users actually need this change
Accessibility testing results	nice to have	Results from accessibility testing that justify the approach
Comparative analysis with similar patterns	supporting	How similar components or patterns handle comparable requirements
Implementation feasibility assessment	supporting	Technical evaluation of the proposed implementation approach

PLUS Spacing Tokens