design-tokens

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)

{
  "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:

{
  "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:

: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.