| name | design-token-guard |
| description | Enforce the design token layer — block raw hex values, hardcoded font sizes, and magic spacing numbers in component files. All visual values must reference semantic tokens. |
| version | 0.1.0 |
| level | 2 |
| triggers | ["design token guard","token guard","check tokens","enforce tokens","/design-token-guard"] |
| context_files | ["context/project.md"] |
| steps | [{"name":"Token Inventory","description":"Locate the token definitions — CSS custom properties, Tailwind config, design-system MASTER.md. Establish what tokens exist."},{"name":"Violation Scan","description":"Search component files for raw values that should be token references — hex colors, px font sizes, magic spacing numbers."},{"name":"Classify","description":"For each violation, identify whether a token exists for this value (TOKEN_VIOLATION) or the token is missing entirely (TOKEN_GAP)."},{"name":"Remediate","description":"TOKEN_VIOLATION — replace raw value with token reference. TOKEN_GAP — add token to the token file, then reference it."},{"name":"Verify","description":"Re-scan after remediation. No raw visual values in component files."}] |
Design Token Guard Skill
Enforce the rule: no raw visual values in component files. Every color, font size, spacing value, border radius, and shadow must reference a token. This is how design systems stay coherent when components multiply.
What Claude Gets Wrong Without This Skill
Claude scatters raw values through component files. color: #2563EB here, font-size: 16px there, padding: 12px 24px everywhere. Each value is correct in isolation. As a system, they are a maintenance liability — changing the brand primary color requires hunting 40 files instead of editing one token.
The second failure: Claude creates tokens but does not use them. A design-system/MASTER.md or tokens.css file gets generated and then immediately ignored. Components are written against raw values because they compile and Claude does not check. This skill closes that gap.
The Three-Layer Token Architecture
Visual values must flow through three layers before reaching a component:
Layer 1 — Primitive tokens (raw values, never used in components)
--color-blue-600: #2563EB;
--size-4: 16px;
--radius-md: 6px;
Layer 2 — Semantic tokens (intent-named, reference primitives)
--color-primary: var(--color-blue-600);
--text-base: var(--size-4);
--radius-button: var(--radius-md);
Layer 3 — Component tokens (component-scoped, reference semantic)
--button-bg: var(--color-primary);
--button-font-size: var(--text-base);
--button-radius: var(--radius-button);
Components reference Layer 3 (or Layer 2 directly for simple cases). They never reference Layer 1. They never use raw values.
Phase Gates
Token Inventory — hard gate
Locate where tokens are defined in the project. Common locations:
| Stack | Token Location |
|---|
| CSS/vanilla | tokens.css, design-system/tokens.css, :root in global.css |
| Tailwind | tailwind.config.js → theme.extend |
| CSS Modules | variables.module.css |
| Styled Components | theme.ts, ThemeProvider |
| Design system MASTER.md | .claude/skills/ui/design-system/ |
If no token file exists: create one before running the violation scan. Do not remediate violations by hardcoding — create the missing token layer first.
