Primitive vs Semantic Tokens
Helix organizes tokens into two layers that work together:
Primitive Tokens
Primitive tokens define the raw value palette — full tonal scales and fixed measurements that are independent of any UI context. They answer "what colors / sizes / values exist?"
- Each color family spans an 11-step scale (50–950) with a designated main stop.
- Spacing, radii, and other scales follow a similar fixed progression.
- Primitives are never referenced directly in component code.
Example — the tc-navy primitive scale:
| 50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 ★ | 800 | 900 | 950 |
|---|---|---|---|---|---|---|---|---|---|---|
#F2F7FD | #E4EEFA | #C3DBF4 | #8EBFEB | #529DDE | #2C81CB | #1D65AC | #19518B | #184674 | #18385B | #112640 |
Semantic Tokens
Semantic tokens map UI roles to specific primitive values. They answer "what does this value mean in context?" and are the tokens components actually consume.
- Each semantic token resolves to a different primitive value in light and dark mode.
Example — primary semantic token:
| Mode | Resolved Value | Aliases From |
|---|---|---|
| Light | #19518B | tc-navy/700-main |
| Dark | #529DDE | tc-navy/400 |
Why This Matters
Primitives stay fixed across modes. Semantic tokens define the single Helix brand expression in both light and dark. Components only reference semantic tokens — never raw primitive values.
Token Categories
Browse each category for complete values, usage guidelines, and live previews:
- Color Tokens — Primitive palettes and semantic color mappings for both light and dark modes.
- Typography — Font families, size scale, weight, line-height, and letter-spacing tokens.
- Spacing — The spacing scale from
0to384px, used for padding, margin, and gap. - Border Radius — Radius tokens from sharp corners to fully rounded.
- Shadows — Elevation levels and shadow tokens for depth and layering.
- Motion — Duration, easing, and animation tokens for transitions.
- Breakpoints — Responsive breakpoint tokens and container query guidelines.