design-tokens-basics

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

1. Reference (core): raw primitives. Never consumed by components directly.
   • color.blue.500, space.8, font.size.16, radius.8.
2. System (semantic): intent-bearing aliases. This is the layer components consume.
   • color.surface.default, color.action.primary.default, space.inset.md, text.body.md.
3. 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

• Tokens validate as DTCG ($value + $type on every leaf).
• Three layers exist as separate files/folders: reference/, system/, component/.
• Components consume only system or component tokens.
• Names are semantic, lowercase, dotted, no implementation details.
• Every token has a $description or its intent is obvious from its name.
• Deprecated tokens use $deprecated: true with a replacement hint.
• A tokens/ lint step fails the build on broken aliases or layer violations.