Variable Contract Quick Reference

Cheat sheet for common Variable Contract tasks.

Naming convention

Format: {category}.{system}.{role}.{state}.{scale}

Rules:

Lowercase
Dot-separated segments
No platform names
Semantic aliases for UI usage

Examples:

color.gray.900 (base)
color.text.primary (alias)
component.button.color.background.default (component)

Variable structure

{
  "variable": {
    "$type": "color",
    "$value": "#0066cc",
    "$description": "Primary brand color",
    "$extensions": {},
    "$deprecated": false
  }
}

Required: $type, $value
Optional: $description, $extensions, $deprecated

Reference syntax

Canonical: {path.to.variable}
DTCG required: #/path/to/variable

Example:

{
  "$value": "{color.primary}"
}

Modes

{
  "$value": {
    "light": "#ffffff",
    "dark": "#000000"
  }
}

Validation checklist

Names follow naming convention
Every variable has $type and $value
References resolve (no broken references)
No circular references
Mode keys match within collections (enforced by validation)
Breaking changes versioned

Common workflows

Create new variable

Designer creates in Figma
Export from Figma
Design Engineer normalizes with adapter
Commit to version control
Review and merge
CI generates outputs

Rename variable

Mark old variable as deprecated
Create new variable with new name
Update all references
Bump MAJOR version
Document migration path
Remove deprecated variable in next major version

Add mode

Add mode key to $value object
Update all variables in collection to use same mode keys (validation checks this)
Update all variables in collection
Bump MINOR version
Document mode addition

Role responsibilities

Designer:

Create variables in Figma
Follow naming convention
Use variables in components

Design Engineer:

Review variable changes
Maintain contract
Run adapters
Publish releases

Frontend Developer:

Consume variables in code
Maintain build pipelines
Test consumption

File organization

tokens/
  ├── base/
  │   ├── color.json
  │   ├── spacing.json
  │   └── typography.json
  ├── semantic/
  │   ├── color.json
  │   └── spacing.json
  └── component/
      └── button.json

Versioning

MAJOR: breaking changes (renames, removals, type changes)
MINOR: new variables, new modes, additions
PATCH: bug fixes, documentation

Quick Reference