Design Token Orchestrator Skill

Design Token Orchestrator Skill

Overview

One-stop automation for the complete design token lifecycle: generation → validation → synchronization. Eliminates manual script execution and ensures Northcote Curio color palette compliance.

This skill integrates three previously standalone scripts into a cohesive workflow that maintains design system integrity.

When to Use This Skill

Use this skill when you need to:

• Build design tokens from a source JSON into CSS variables and Tailwind config
• Validate token compliance against Northcote Curio palette rules
• Sync theme files to keep tokens aligned across systems
• Audit color usage to detect forbidden colors (blues, purples, neons)
• Generate token reports showing coverage and compliance scores

How It Works

The orchestrator provides three core operations:

1. Build Tokens (build)

Input: design-system/​tokens.json Output:

• frontend/​src/​styles/​design-tokens.css (CSS variables)
• design-system/​tailwind-token-patch.js (Tailwind config)

What it does:

• Parses token JSON
• Generates CSS custom properties (--sys-color-*, --sys-shape-*, etc.)
• Creates Tailwind theme extensions
• Validates structure

Usage:

python .claude/​skills/​design-token-orchestrator/​scripts/​build_tokens.py

---

2. Validate Tokens (validate)

Input: design-system/​tokens.json Output: Compliance report (JSON)

What it does:

• Checks required token categories (color, typography, spacing, elevation, shape)
• Validates WCAG AA contrast ratios
• Detects forbidden colors (blues, purples, neons)
• Compares against Northcote reference palette
• Scores compliance 0-100

Usage:

python .claude/​skills/​design-token-orchestrator/​scripts/​validate_tokens.py

Validation Rules:

1. ✅ Palette Compliance: Colors must be from Northcote botanical palette
2. ❌ Forbidden Colors: Electric blue (#0080FF), neon purple (#9D4EDD), cyan
3. ✅ Contrast Requirements: Text/​background pairs must meet WCAG AA (4.5:1)
4. ✅ Token Structure: Must include color, typography, spacing, elevation, shape

---

3. Sync Tokens (sync)

Input: Current theme files Output: Synchronized token definitions

What it does:

• Reads theme configuration
• Extracts design values
• Writes to canonical token JSON
• Ensures single source of truth

Usage:

python .claude/​skills/​design-token-orchestrator/​scripts/​sync_tokens.py

---

Skill Workflow Examples

Example 1: Fresh Token Build

Scenario: You've updated design-system/​tokens.json with new colors.

Steps:

1. "Build tokens from the updated JSON"
2. "Validate the new tokens against Northcote compliance"
3. If validation passes → tokens are ready to use
4. If validation fails → review flagged colors and fix

Expected Output:

✅ Generated 78 color tokens
✅ Generated 7 shape tokens
✅ Tailwind config patched
✅ Validation: 94/​100 (1 contrast warning)

---

Example 2: Audit Existing Tokens

Scenario: You want to verify current tokens are Northcote-compliant.

Steps:

1. "Validate existing design tokens"
2. Review compliance report
3. Identify violations (e.g., forbidden blue detected)
4. Fix violations in source JSON
5. Rebuild tokens

Expected Output:

{
  "compliance_score": 87,
  "violations": [
    {
      "category": "forbidden_color",
      "token": "color.accent.blue",
      "value": "#0080FF",
      "rule": "Electric blue forbidden in Northcote palette"
    }
  ]
}

---

Example 3: Full Token Lifecycle

Scenario: Complete token system update.

Workflow:

1. Sync theme → tokens.json
2. Validate compliance
3. Fix violations
4. Build CSS + Tailwind
5. Verify output

Commands:

# Step 1: Sync
python scripts/​sync_tokens.py

# Step 2: Validate
python scripts/​validate_tokens.py

# Step 3: Build (if validation passes)
python scripts/​build_tokens.py

---

Integration with Other Skills

With northcote-visual-audit

Visual audit validates rendered components. Token orchestrator validates source tokens. Together, they ensure design → implementation fidelity.

With northcote-typography-strategy

Typography strategy defines font choices. Token orchestrator ensures those fonts are correctly defined as CSS variables.

With brand-brief-optimizer

Brief optimizer establishes design direction. Token orchestrator implements that direction as executable tokens.

---

Technical Specifications

Required Token Structure

{
  "color": {
    "primary": "#C45C4B",
    "secondary": "#D4A84B",
    "tertiary": "#8A9A7A"
  },
  "typography": {
    "fontFamilyBase": "'Crimson Text', serif",
    "fontFamilyHeading": "'Lora', serif"
  },
  "spacing": {
    "scale": {
      "space1": "4px",
      "space2": "8px"
    }
  },
  "shape": {
    "corner_small": "8px",
    "corner_medium": "12px"
  },
  "elevation": {
    "level_0": "none",
    "level_1": "0 1px 2px rgba(0,0,0,0.05)"
  }
}

Generated CSS Variables

:root {
  --sys-color-primary: #c45c4b;
  --sys-color-secondary: #d4a84b;
  --sys-font-base: "Crimson Text", serif;
  --sys-shape-corner-small: 8px;
  --sys-elevation-level-1: 0 1px 2px rgba(0, 0, 0, 0.05);
}

---

Northcote Palette Reference

The skill includes a reference palette at resources/​northcote-palette.json:

{
  "waratahCrimson": "#C45C4B",
  "wattleGold": "#D4A84B",
  "eucalyptusSage": "#8A9A7A",
  "ochreEarth": "#CC8B4A",
  "coralRed": "#D05D5D",
  "specimenNight": "#1A1714",
  "parchmentCream": "#F5F1E8"
}

Forbidden Colors:

• Electric blue (#0080FF)
• Neon purple (#9D4EDD)
• Cyan (#00FFFF)

---

Dependencies

# Python dependencies
pip install wcag-contrast-ratio

# All scripts are Python 3.8+ compatible

---

Error Handling

All scripts return:

• Exit code 0: Success
• Exit code 1: Validation failure or build error
• Logs: Written to console (redirect to file if needed)

---

Limitations

This skill:

✅ Automates token generation and validation ✅ Ensures Northcote palette compliance ✅ Detects forbidden colors ✅ Validates WCAG contrast ratios

❌ Does not modify component code (use other skills for that) ❌ Does not generate tokens from scratch (requires source JSON) ❌ Does not handle runtime theme switching

---

Key Principle

Design tokens are the single source of truth. Everything else—CSS, Tailwind, component styles—derives from tokens. This skill ensures that source of truth remains pure, compliant, and synchronized.

---

Unified token automation. Northcote compliance guaranteed. Victorian precision in every variable.