7.1 The Size Collection
Figma collection: {Component} / Size — Modes: sm, md, lg
Every token whose value changes when the component size changes lives here. This includes dimensions, padding, gaps, and typography tokens.
Button / Size Example
| Token | sm | md | lg |
|---|---|---|---|
button-height | 32px | 40px | 48px |
button-padding-x | 8px | 16px | 16px |
button-padding-y | 4px | 8px | 12px |
button-font-size | 14px | 14px | 16px |
button-font-weight | 500 | 500 | 500 |
button-icon-size | 16px | 20px | 20px |
button-gap | 4px | 8px | 8px |
button-radius | {radius-md} | {radius-md} | {radius-md} |
Naming Rule
Token names never include the mode name.
button-height is correct. button-height-md is wrong — md is a mode, not part of the token's identity.
7.2 The Structure Collection
Figma collection: {Component} / Structure — Mode: Default (single mode)
Fixed token values that never change regardless of color family or size. These are structural — they belong to the component's visual recipe, not its theming layer.
Examples
| Token | Value | References |
|---|---|---|
| Button / Structure | ||
button-disabled-bg | fixed | {disabled-surface} |
button-disabled-text | fixed | {disabled-on-surface} |
button-disabled-border | fixed | {disabled-border} |
| Toggle / Structure | ||
toggle-thumb | always white | {white} |
toggle-thumb-border | always medium gray | {border-default} |
toggle-track-off | always gray | {border-default} |
toggle-track-disabled | fixed | {disabled-surface} |
| Checkbox / Structure | ||
checkbox-bg-off | unchecked bg | {surface-default} |
checkbox-border-off | unchecked border | {border-default} |
checkbox-checkmark | always white | {white} |
7.3 The Shared Color Collection — The Key Innovation
Figma collection: Color / Active — Modes: neutral, brand, info, success, warning, danger, contrast
Instead of duplicating color definitions inside every component, one shared collection bridges Semantic Colors to Component Types.
Only 6 tokens. All 15+ components. Every color family. Zero duplication.
| Token | Meaning | Mode: brand | Mode: danger |
|---|---|---|---|
color | Primary accent swatch | {brand-color} → purple | {danger-color} → red |
on-color | Content on color | {brand-on-color} → white | {danger-on-color} → white |
container | Soft/subtle background | {brand-container} → light purple | {danger-container} → light red |
on-container | Content on container | {brand-on-container} → dark purple | {danger-on-container} → dark red |
outline | Borders and outlines | {brand-outline} → purple | {danger-outline} → red |
focus | Focus rings / highlights | {brand-focus} → purple alpha | {danger-focus} → red alpha |
Why Only 6?
We audited every component in the system:
| Component | Tokens Used | Which Ones |
|---|---|---|
| Button (primary) | 4 | color, on-color, focus, outline |
| Button (outline) | 3 | on-container, outline, focus |
| Button (light) | 3 | container, on-container, focus |
| Button (basic) | 2 | on-container, focus |
| Toggle | 1–2 | color, (focus) |
| Checkbox | 2 | color, focus |
| Radio Button | 1 | color |
| Badge | 2 | color, on-color |
| Tab | 3–4 | color, on-color, outline, focus |
| Icon | 1 | color |
No component needs more than 6. Most need 1–3. The 6 roles cover every case.
7.4 Component Typography Tokens & Styles
Typography tokens that change with size belong in the Size collection alongside dimensional tokens.
Full Typography Chain
// Tier 1 — Primitive
font-size-sm: 14px
font-size-md: 16px
↓
// Tier 3 — Button / Size (size collection)
button-font-size: {font-size-sm} ← sm mode
{font-size-sm} ← md mode
{font-size-md} ← lg mode
↓
// Figma Text Style "Button / Label"
font-size → $button-font-size (bound to Size token)
font-weight → $button-font-weight
font-family → Inter (static)
↓
// Label text node inside Button component
style = "Button / Label" (no direct variable needed)
Figma Constraint: Variables vs Styles
In Figma, applying a Text Style and binding a font-size variable to the same text node are mutually exclusive — the style wins. The solution: bind the variable inside the style definition, not on the text node itself.
7.5 Token Naming Rules
Token names follow a flat, hyphenated, lowercase pattern: {component}-{element}-{property}
| Segment | Rule | Example |
|---|---|---|
{component} | Component name, lowercase, hyphenated | button, form-field, toggle |
{element} | Child element name (omit for root) | thumb, track, label, icon |
{property} | CSS property or abstract property name | size, color, radius, padding-x |
Token name examples
button-height ← root property, no element
button-font-size ← root-level typography
button-icon-size ← child element (icon) + property
toggle-thumb-size ← child element (thumb) + property
toggle-track-off ← child (track) + state (off)
checkbox-border-off ← root border in unchecked state
form-field-label-font-size ← child element (label) + property
✗ WRONG: button-height-md ← mode in token name
✗ WRONG: btn-pad ← abbreviation
✗ WRONG: primary-button-h ← type in token name