Design Tokens — W3C DTCG Format

This skill teaches Claude how to produce valid W3C Design Tokens Community Group (DTCG) token files from extracted brand data. All tokens follow the 2025.10 stable specification.

DTCG Token Structure

Every token has three required fields:

•$value — The token's value
•$type — The DTCG type identifier
•$description — Human-readable description (recommended, ≥50% coverage for Gate 4)

json

{
  "colour": {
    "brand": {
      "primary": {
        "$value": "#635bff",
        "$type": "color",
        "$description": "Primary brand colour used for CTAs, links, and key interactive elements"
      }
    }
  }
}

Supported DTCG Types

Type	`$type` Value	Example `$value`
Colour	`color`	`#635bff`, `oklch(0.55 0.15 270)`
Dimension	`dimension`	`16px`, `1.5rem`
Font Family	`fontFamily`	`["Inter", "system-ui", "sans-serif"]`
Font Weight	`fontWeight`	`400`, `700`
Duration	`duration`	`200ms`, `0.3s`
Cubic Bezier	`cubicBezier`	`[0.42, 0, 0.58, 1]`
Shadow	`shadow`	`{"offsetX": "0px", "offsetY": "4px", "blur": "12px", "spread": "0px", "color": "#00000014"}`
Border	`border`	`{"width": "1px", "style": "solid", "color": "#e5e7eb"}`
Gradient	`gradient`	Array of gradient stops
Typography	`typography`	Composite: fontFamily, fontSize, fontWeight, lineHeight, letterSpacing
Number	`number`	`1.25`, `0.5`

Token Group Structure

Organise tokens hierarchically with semantic naming:

json

{
  "colour": {
    "$description": "Colour tokens",
    "brand": {
      "primary": { "$value": "#635bff", "$type": "color", "$description": "..." },
      "secondary": { "$value": "#0a2540", "$type": "color", "$description": "..." }
    },
    "neutral": {
      "50": { "$value": "#f8fafc", "$type": "color", "$description": "Lightest neutral" },
      "900": { "$value": "#0f172a", "$type": "color", "$description": "Darkest neutral" }
    },
    "feedback": {
      "success": { "$value": "#22c55e", "$type": "color", "$description": "..." },
      "error": { "$value": "#ef4444", "$type": "color", "$description": "..." },
      "warning": { "$value": "#f59e0b", "$type": "color", "$description": "..." },
      "info": { "$value": "#3b82f6", "$type": "color", "$description": "..." }
    },
    "surface": {
      "default": { "$value": "#ffffff", "$type": "color", "$description": "..." },
      "elevated": { "$value": "#f8fafc", "$type": "color", "$description": "..." }
    }
  },
  "typography": {
    "fontFamily": {
      "primary": { "$value": ["Inter", "system-ui", "sans-serif"], "$type": "fontFamily" },
      "mono": { "$value": ["JetBrains Mono", "monospace"], "$type": "fontFamily" }
    },
    "scale": {
      "display": { "$value": "48px", "$type": "dimension" },
      "h1": { "$value": "36px", "$type": "dimension" },
      "h2": { "$value": "30px", "$type": "dimension" },
      "h3": { "$value": "24px", "$type": "dimension" },
      "h4": { "$value": "20px", "$type": "dimension" },
      "body": { "$value": "16px", "$type": "dimension" },
      "caption": { "$value": "14px", "$type": "dimension" },
      "label": { "$value": "12px", "$type": "dimension" }
    }
  },
  "spacing": {
    "base": { "$value": "8px", "$type": "dimension", "$description": "Base spacing unit" },
    "scale": {
      "xs": { "$value": "4px", "$type": "dimension" },
      "sm": { "$value": "8px", "$type": "dimension" },
      "md": { "$value": "16px", "$type": "dimension" },
      "lg": { "$value": "24px", "$type": "dimension" },
      "xl": { "$value": "32px", "$type": "dimension" },
      "2xl": { "$value": "48px", "$type": "dimension" },
      "3xl": { "$value": "64px", "$type": "dimension" }
    }
  },
  "borderRadius": {
    "none": { "$value": "0px", "$type": "dimension" },
    "sm": { "$value": "4px", "$type": "dimension" },
    "md": { "$value": "8px", "$type": "dimension" },
    "lg": { "$value": "12px", "$type": "dimension" },
    "full": { "$value": "9999px", "$type": "dimension" }
  },
  "shadow": {
    "sm": { "$value": {"offsetX": "0px", "offsetY": "1px", "blur": "2px", "spread": "0px", "color": "#0000000d"}, "$type": "shadow" },
    "md": { "$value": {"offsetX": "0px", "offsetY": "4px", "blur": "6px", "spread": "-1px", "color": "#0000001a"}, "$type": "shadow" },
    "lg": { "$value": {"offsetX": "0px", "offsetY": "10px", "blur": "15px", "spread": "-3px", "color": "#0000001a"}, "$type": "shadow" }
  },
  "motion": {
    "duration": {
      "fast": { "$value": "150ms", "$type": "duration" },
      "normal": { "$value": "200ms", "$type": "duration" },
      "slow": { "$value": "300ms", "$type": "duration" }
    },
    "easing": {
      "default": { "$value": [0.42, 0, 0.58, 1], "$type": "cubicBezier" },
      "in": { "$value": [0.42, 0, 1, 1], "$type": "cubicBezier" },
      "out": { "$value": [0, 0, 0.58, 1], "$type": "cubicBezier" }
    }
  }
}

CSS Custom Properties Export

Generate alongside the DTCG file:

css

:root {
  /* Brand Colours */
  --colour-brand-primary: #635bff;
  --colour-brand-secondary: #0a2540;

  /* Neutral Scale */
  --colour-neutral-50: #f8fafc;
  --colour-neutral-900: #0f172a;

  /* Typography */
  --font-family-primary: 'Inter', system-ui, sans-serif;
  --font-size-display: 48px;
  --font-size-h1: 36px;
  --font-size-body: 16px;

  /* Spacing */
  --spacing-base: 8px;
  --spacing-xs: 4px;
  --spacing-sm: 8px;
  --spacing-md: 16px;
  --spacing-lg: 24px;

  /* Border Radius */
  --radius-sm: 4px;
  --radius-md: 8px;
  --radius-lg: 12px;
  --radius-full: 9999px;
}

Validation Checklist (Gate 4 — DTCG)

•S-DTG-01: Valid JSON (must parse without error) [BLOCKING]
•S-DTG-02: DTCG schema compliance ($value + $type on every token) [BLOCKING]
•S-DTG-03: Completeness (colour, typography, spacing, radius minimum)
•S-DTG-04: Descriptions on ≥50% of tokens

Reference

For the complete DTCG specification, see dtcg-schema-reference.md.