Design Token Critic Skill

JTBD (Jobs To Be Done)

Primary Job

When my design token system has grown organically and I'm not sure if it's consistent, well-named, or complete, I want an evidence-backed audit of token architecture, math relationships, and coverage, so I can fix structural token problems before they propagate across components and platforms.

Secondary Jobs

When I need to verify that CSS custom properties, Figma variables, and Tailwind config are aligned, I want a cross-platform parity check, so I can catch drift before it causes visual inconsistencies.
When I suspect my color system has contrast problems, I want every color pairing audited against WCAG AA/AAA, so I can fix compliance gaps systematically rather than one-off.
When a web-design-executor or infographic-executor generates code with design tokens, I want the token system reviewed before more surfaces consume it, so token debt doesn't compound.

This Skill Is For

Teams with existing token files (CSS custom properties, Tailwind config, Figma variables) needing audit
Projects where token drift is suspected (raw values appearing where tokens should be)
Design system handoffs where token quality must be verified
Post-executor review of token systems extracted by stitch-planner's design-md phase

This Skill Is NOT For

Creating tokens from scratch — future token-planner
Reviewing UI implementations — use web-design-critic
Reviewing brand identity — use graphic-design-critic
Reviewing accessibility of implementations — use a11y-critic

Paired With

design-partner (upstream): Sets color and typography strategy that tokens should formalize
web-design-planner (upstream): Maps tokens to surfaces and components
web-design-executor, infographic-executor, graphic-design-executor (downstream): Generate code using tokens this critic reviews
stitch-planner (parallel): design-md extraction produces token documentation this critic can audit

Shared Research Reference

Apply the shared research-backed workflow while reviewing: design-skills/shared-design-core/.claude/skills/shared-design-core/references/research-backed-design-workflow.md

Research-Backed Evidence Gate

Before assigning a final verdict, check whether the token system includes:

Reference Inventory: source token files, component libraries, Figma/Pencil variables, user references, public research-only inspiration, and missing evidence.
Design Memory Notes: DESIGN.md/DESIGN_MEMORY.md continuity, semantic names, source authority decisions, rejected directions, and intentional departures.
State Matrix: token support for focus, hover, active, disabled, error, success, loading, dark mode, reduced motion, high contrast, and platform-specific states where relevant.
Source Mapping: every token source, extraction tier, and conflict-resolution rule.
Source/Provenance Notes: where token roles, palette decisions, type scale, spacing scale, and generated documentation came from.

Missing evidence is not automatically a defect, but it must be reported in Coverage Analysis or Self-Audit and can support REVISE when it hides material token, accessibility, or cross-platform risk.

Investigation Protocol

Phase 1: Pre-Commitment Predictions

Before examining tokens, predict what problems are likely:

Small project → likely missing tokens for edge cases (shadows, transitions)
Large design system → likely naming inconsistency across tiers
Multi-platform → likely drift between CSS and native token definitions
Organic growth → likely raw values mixed with token references

Phase 2: Token Architecture Review

Naming tiers: Are tokens organized in tiers (raw/primitive → semantic → component)?
Naming convention: kebab-case? camelCase? BEM-like? Consistent across all files?
Aliasing strategy: Do semantic tokens reference primitives, or are values duplicated?
File organization: Single file or split by domain (color, typography, spacing)?
Documentation: Are tokens documented with purpose/usage context?
Memory continuity: Do semantic names, token roles, and rejected directions align with DESIGN.md and DESIGN_MEMORY.md, or is the departure intentional and documented?
Provenance: Are source files, extracted values, and conflict-resolution decisions traceable?

Phase 3: Color System Audit

Contrast ratios: Check every foreground/background pairing against WCAG AA (4.5:1 normal, 3:1 large) and AAA (7:1)
Lightness scale: Is there a consistent lightness progression (50-900)?
Semantic mapping: Do semantic colors (success, warning, error, info) have clear, distinguishable hues?
Dark mode parity: If dark mode tokens exist, do they maintain contrast ratios and semantic meaning?
Color math: Are color scales generated from a systematic formula or hand-picked?

Phase 4: Typography Scale Review

Scale logic: Is the type scale ratio-based (1.2, 1.25, 1.333)? Or arbitrary?
Responsive scaling: Do type sizes adapt across breakpoints? How?
Line height relationships: Are line heights paired correctly with font sizes?
Font loading: Are font tokens referencing fonts that are actually loaded?
Weight coverage: Are all used font weights defined as tokens?

Phase 5: Spacing & Layout Tokens

Base unit: Is there a consistent base unit (4px, 8px)?
Progression: Linear (4, 8, 12, 16) or geometric (4, 8, 16, 32)?
Breakpoint tokens: Are breakpoints defined as tokens or hardcoded in media queries?
Consistency: Are spacing values used consistently or do arbitrary values appear?

Phase 6: Coverage Analysis

Raw value scan: Search for hardcoded hex, rgb, px values that should use tokens
Orphaned tokens: Tokens defined but never referenced
Missing tokens: Common patterns (focus ring, border width, z-index, transition) without tokens
Component-level gaps: Components using one-off values instead of system tokens
Reference/memory gaps: Missing Reference Inventory, Design Memory Notes, Source Mapping, or source authority decisions when DESIGN.md was generated or updated

Phase 6.5: State Matrix Token Support

Interactive states: Are focus, hover, active, disabled, selected, and pressed states tokenized where the UI uses them?
Feedback states: Are error, warning, success, info, loading, empty, and offline states mapped to semantic tokens rather than raw values?
Accessibility states: Are high contrast, reduced motion, focus ring, text scaling, and color-independence needs supported by tokens?
Theme states: Do dark mode or platform variants preserve semantic meaning, contrast, and state hierarchy?
Agentic states: If the product has assistant/tool-running UI, are thinking, streaming, tool-running, waiting-for-user, partial success, error, cancelled, and handoff states token-supported?

Phase 7: Cross-Platform Parity

CSS ↔ Figma: Do CSS custom property names match Figma variable names?
CSS ↔ Tailwind: If Tailwind is used, do custom theme values align with CSS tokens?
CSS ↔ Native: If React Native/SwiftUI tokens exist, do they match web values?
Token format: Are tokens in a shared format (Style Dictionary, Tokens Studio) or duplicated per platform?

Phase 8: Self-Audit + Realist Check

Am I flagging real structural problems or manufacturing violations?
Would a senior design systems engineer agree with my severity ratings?
Am I auditing the token system or accidentally auditing the UI?
Did I actually check contrast ratios or just assume they're fine?
Is my verdict proportionate to the actual quality of the system?

Phase 9: Synthesis

Severity-rated findings table (CRITICAL / MAJOR / MINOR / ENHANCEMENT)
Verdict: REJECT / REVISE / ACCEPT-WITH-RESERVATIONS / ACCEPT
Recommended next steps

Calibration

A token system with no naming convention → REVISE minimum
A system with proper tiers, consistent math, and good coverage → ACCEPT or ACCEPT-WITH-RESERVATIONS even if minor naming nits exist
Token count is not a quality signal — more tokens isn't bad; poor organization is
Don't manufacture violations in well-organized systems
Don't rubber-stamp disorganized ones
WCAG contrast failures are always CRITICAL — non-negotiable compliance requirement

Hard Gates

No verdict without examining actual token files (not just documentation)
No verdict without Reference Inventory, Design Memory Notes, State Matrix token support, Source Mapping, and Source/Provenance review when those artifacts exist or should have been generated
CRITICAL and MAJOR findings require file:line evidence
No rubber-stamping: a token system with no naming convention gets REVISE minimum
Must check contrast ratios if color tokens are present
Must check at least one cross-platform target if multiple platforms exist
No acceptance of copied public reference token systems without project-local transformation and provenance

Required Output Contract

Use these top-level headings exactly:

## Pre-Commitment Predictions
## Reference/Memory/Provenance Check
## Token Architecture Review
## Color System Audit
## Typography Scale Review
## Spacing & Layout Tokens
## Coverage Analysis
## State Matrix Token Support
## Cross-Platform Parity
## Self-Audit
## Synthesis

Inside ## Synthesis, include:

### Findings Table
### Verdict
### Recommended Next Steps

design-token-critic

SKILL.md.claude/skills/design-token-critic/SKILL.md