systems

systems

!checklist init ${CLAUDE_SKILL_DIR} --force

An atelier is a craftsman's studio — the place where the individual lenses (color, type, form, motion) are forged. systems is the workbench that holds them together: the skill that turns a set of well-chosen tokens into one coherent, non-drifting system by establishing the architecture that makes drift structurally impossible. Where the other lenses decide what the values are, systems decides where they live, how they cross every language boundary, and how they stay in sync — permanently. It runs across gated stages and will not advance past a GATE until the checklist tool clears it — order enforced, substance yours.

The governing fact: the design system is itself state, so it gets one source of truth. A CSS token file and a JS color object that both list the same palette are not two views of the same truth — they are two sources of truth, and the moment one is updated without the other, the surface is subtly two-toned, and no one knows why. The same law that surface:wellspring applies to application data (the design system is itself state, one source of truth) applies here to the design artifact: one source authors the tokens; every language reads from it. This is not a "keep things in sync" convention — it is the only architecture that does not rot under normal development velocity.

This is where the agent era bites:

• The agent re-types tokens per file and feels no wrongness. It will write '#2563eb' in an inline style object, oklch(0.62 0.18 250) in a CSS file, and color.primary = '#2563eb' in a tokens.ts — each plausible alone, the set a three-source system that will drift in three different directions within a sprint. It has no sense of the system degrading; the architecture must make the wrong thing impossible.
• The agent treats a Figma file as the source of truth. It will generate code "to match the design" by reading screenshots and re-deriving values — reinventing, not consuming. Reinventing is the first step of drift. The token source is code; Figma is a downstream consumer.
• The agent reaches for prop explosion. Every component variation becomes a boolean flag: <Button variant="..." size="..." iconLeft="..." ghost pill loading>. The combinations multiply; the component is unmaintainable. Composition over configuration is a structural decision, not a style preference — the agent will not make it without instruction.
• The agent skips living documentation. It generates components without stories, without accessibility contracts, without a stability tier. The library appears to grow, but no one can consume it correctly, and no CI catches visual regressions. A library with no living documentation is a library that has already started to rot.

Read references/token-architecture-one-source.md first — the taxonomy, the three-layer architecture, the CSS↔JS boundary mechanics, and the IACVT footgun. For systems, the axis that is load-bearing: the single source of truth is an architectural decision, not a convention. The CSS↔JS boundary mechanics (the four options, the inline-style-beats-class-rules trap) are the encodable technique; deciding which source architecture fits the stack is the taste call that belongs to each gate. Load at the start; re-check at every gate.

This skill consumes the output of the other atelier lenses. Color, type, form, and motion each produce tokens as their delivered artifact. systems takes those tokens, places them in the three-layer architecture (raw → semantic → component), closes the CSS↔JS boundary, and makes the living library the single point of contact for everything downstream. Cross-reference surface:wellspring's law "the design system is itself state, one source of truth" — this skill is that law applied to the design artifact itself. Cross-reference surface:bulwark — it enforces the system at 1→N (the PR review pass that catches drift before it merges); its gate is only meaningful when systems has built the structure bulwark will protect.