design-tokens

Design Tokens — W3C DTCG Format

Overview

The W3C Design Tokens Community Group (DTCG) specification defines a vendor-neutral JSON format for exchanging design tokens across tools and platforms. The first stable version (2025.10) provides a production-ready standard adopted by Style Dictionary, Tokens Studio, Figma, and others.

File Conventions

• MIME type: application/design-tokens+json (or application/json)
• Extensions: .tokens or .tokens.json
• Encoding: UTF-8 JSON

Token Structure

Every token is a JSON object with a $value property. The key becomes the token name:

{
  "color-primary": {
    "$value": "#3b82f6",
    "$type": "color",
    "$description": "Primary brand color"
  }
}

Token Properties

Property	Required	Description
$value	Yes	The token's value
$type	No	Token type (inherited from parent group if omitted)
$description	No	Human-readable purpose
$deprecated	No	true or a string explaining why
$extensions	No	Vendor metadata (reverse domain notation)

Token Types

Primitive Types

{
  "brand-blue": {
    "$value": "#3b82f6",
    "$type": "color"
  },
  "space-md": {
    "$value": { "value": 16, "unit": "px" },
    "$type": "dimension"
  },
  "font-sans": {
    "$value": ["Inter", "system-ui", "sans-serif"],
    "$type": "fontFamily"
  },
  "weight-bold": {
    "$value": 700,
    "$type": "fontWeight"
  },
  "duration-fast": {
    "$value": { "value": 150, "unit": "ms" },
    "$type": "duration"
  },
  "ease-out": {
    "$value": [0, 0, 0.2, 1],
    "$type": "cubicBezier"
  },
  "line-height-normal": {
    "$value": 1.5,
    "$type": "number"
  }
}

Composite Types

{
  "shadow-md": {
    "$value": {
      "color": "#00000026",
      "offsetX": { "value": 0, "unit": "px" },
      "offsetY": { "value": 4, "unit": "px" },
      "blur": { "value": 8, "unit": "px" },
      "spread": { "value": 0, "unit": "px" }
    },
    "$type": "shadow"
  },
  "border-default": {
    "$value": {
      "color": "#d1d5db",
      "width": { "value": 1, "unit": "px" },
      "style": "solid"
    },
    "$type": "border"
  },
  "heading-lg": {
    "$value": {
      "fontFamily": "{font-sans}",
      "fontSize": { "value": 24, "unit": "px" },
      "fontWeight": 700,
      "lineHeight": 1.25
    },
    "$type": "typography"
  },
  "transition-default": {
    "$value": {
      "duration": { "value": 200, "unit": "ms" },
      "delay": { "value": 0, "unit": "ms" },
      "timingFunction": [0.4, 0, 0.2, 1]
    },
    "$type": "transition"
  },
  "gradient-brand": {
    "$value": [
      { "color": "#3b82f6", "position": 0 },
      { "color": "#8b5cf6", "position": 1 }
    ],
    "$type": "gradient"
  }
}