design-tokens

name: design-tokens description: Generate W3C DTCG (Design Tokens Community Group) compliant design token files from extracted brand data. Covers colour, typography, spacing, border-radius, shadow, and motion tokens in the 2025.10 stable specification format. Use when converting extracted CSS values into structured design tokens, exporting tokens for Style Dictionary or Tokens Studio, or validating DTCG schema compliance.

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

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.