Closed Token Layer
3-layer CSS variables token architecture designed to prevent LLMs from fabricating hardcoded values. Layer 1 (foundation) = primitives (raw colors, spacing scales). Layer 2 (semantic) = contextual tokens (color-bg-primary, spacing-md). Layer 3 (component) = component-scoped tokens (button-padding-x). AI agents only read the semantic layer, layers 1 and 3 are closed to direct consumption. Atlaskit case (Atlassian): 418 hardcoded values → 0 after migration to closed token layer.
Strengths
- Measurable: count hardcoded values before/after, clear win number for stakeholders
- Backward-compatible: migrate component by component without blocking teams
- Also reduces human drift, beneficial beyond AI agents
Limitations
- Costly initial refactor for a mature DS: 2-4 weeks of token-by-token migration
- Component layer (layer 3) adds verbosity: `--button-padding-x` instead of `--spacing-md`
Best for
- Mature design system (50+ components) seeing its tokens fabricated by AI agents or humans
- Team scaling Claude Code / Cursor and wanting an architectural, not behavioral, guardrail