| name | design-tokens-basics |
| description | DTCG token schema, naming conventions, and reference/system/component layering. Use this when introducing or auditing a token set. |
Design Tokens Basics
Instructions
Design tokens are the single source of truth for every visual and behavioral decision in the design system. Follow the W3C Design Tokens Community Group (DTCG) format and a strict three-layer model.
1. DTCG Schema Essentials
Tokens are JSON objects where every leaf has $value and $type. Groups may set a default $type that descendants inherit.
{
"color": {
"$type": "color",
"brand": {
"600": { "$value": "#4F46E5" },
"700": { "$value": "#4338CA" }
}
},
"space": {
"$type": "dimension",
"4": { "$value": "4px" },
"8": { "$value": "8px" },
"16": { "$value": "16px" }
},
"font": {
"family": {
"sans": { "$type": "fontFamily", "$value": ["Inter", "system-ui", "sans-serif"] }
}
}
}
Supported $type values used in this system: color, dimension, fontFamily, fontWeight, number, duration, cubicBezier, shadow, typography, transition, strokeStyle.
2. Three-Layer Model
- Reference (core): raw primitives. Never consumed by components directly.
color.blue.500, space.8, font.size.16, radius.8.
- System (semantic): intent-bearing aliases. This is the layer components consume.
color.surface.default, color.action.primary.default, space.inset.md, text.body.md.
- Component: component-scoped. Built by aliasing System tokens.
button.primary.bg.default, card.surface.bg, field.border.focus.
3. Aliasing
Use DTCG alias syntax {group.name} in $value. The build resolves aliases; runtime never sees references.
{
"color": {
"action": {
"primary": {
"default": { "$value": "{color.brand.600}" },
"hover": { "$value": "{color.brand.700}" },
"pressed": { "$value": "{color.brand.800}" }
}
}
}
}
Rule: a token may alias only inward (component → system → reference). Never reference → system.
4. Naming Convention
Use dotted, lowercase, noun-first names. Keep segments short and semantic.
<category>.<role>.<property>.<state>
color.action.primary.bg.default
color.action.primary.fg.default
color.feedback.danger.bg.subtle
Do not encode platform, hex value, or implementation (color-ios-blue, space-8px-v2) in the name.
5. Token Categories
Every mobile design system should minimally define tokens for:
| Category | Examples |
|---|
| color | color.surface.*, color.content.*, color.action.* |
| typography | text.display.lg, text.body.md (composite) |
| spacing | space.inset.*, space.stack.*, space.inline.* |
| radius | radius.sm, radius.md, radius.pill |
| elevation | elevation.level1, elevation.level2 (shadow composite) |
| motion | motion.duration.*, motion.easing.* |
| border | border.width.sm, border.style.default |
6. Metadata
DTCG allows $description, $deprecated, and $extensions. Use them.
{
"color": {
"action": {
"primary": {
"default": {
"$value": "{color.brand.600}",
"$description": "Default background for primary CTAs.",
"$extensions": {
"com.designsystem.contrastPair": "color.action.primary.fg.default"
}
}
}
}
}
}
7. Anti-Patterns
- Hex values inline in component code.
- Semantic layer with color-in-the-name (
color.blue-primary).
- Component tokens aliasing reference tokens directly.
- Token removal without a deprecation window.
- One monster JSON file — split per category and per layer.
Checklist
