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. The same closure can also sit two floors below the convention. In the CSS: Tailwind v4 lets you wipe a whole family of defaults (`--color-*: initial`, or `--*: initial` for the entire theme), so only your values generate a class. In the types: StyleX, the styling library from Meta, lets a component declare the properties and values it accepts (a `marginTop` limited to 0, 4, 8 or 16), and the editor flags the deviation instead of letting it through. Neither is watertight: the StyleX docs themselves warn that TypeScript may let extra properties slip by, hence the linter as the last net.
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