aibot88 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:
- ✅ Palette Compliance: Colors must be from Northcote botanical palette
- ❌ Forbidden Colors: Electric blue (#0080FF), neon purple (#9D4EDD), cyan
- ✅ Contrast Requirements: Text/background pairs must meet WCAG AA (4.5:1)
- ✅ 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:
- "Build tokens from the updated JSON"
- "Validate the new tokens against Northcote compliance"
- If validation passes → tokens are ready to use
- 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:
- "Validate existing design tokens"
- Review compliance report
- Identify violations (e.g., forbidden blue detected)
- Fix violations in source JSON
- 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.