design-token-orchestrator

name	design-token-orchestrator
description	Unified design token automation for Northcote Curio. Build, validate, and sync design tokens across CSS, Tailwind, and theme systems. Ensures compliance with Northcote palette and Victorian aesthetic principles.

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" 
     
     
  

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.