# Systems > > - **Type:** Skill - **Install:** `agentstack add skill-iamk77-skill-systems` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [IamK77](https://agentstack.voostack.com/s/iamk77) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** Apache-2.0 - **Upstream author:** [IamK77](https://github.com/IamK77) - **Source:** https://github.com/IamK77/Skill/tree/main/skills/atelier/systems - **Website:** https://www.npmjs.com/package/@iamk77/skill-checklist ## Install ```sh agentstack add skill-iamk77-skill-systems ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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: ``. 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](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. ## The reference library The depth lives in `references/`. Open each when a stage sends you there — not all upfront. - **[references/token-architecture-one-source.md](references/token-architecture-one-source.md)** — the heart: the token taxonomy (color/type/space/radius/motion), the three-layer architecture (raw → semantic → component), CSS custom property mechanics (`@layer`, `@property`, scoping, IACVT), the four CSS↔JS boundary options, and the inline-style-beats-class-rules trap. Load at the start; re-check at every gate. - [references/the-living-component-library.md](references/the-living-component-library.md) — the primitive → composition → pattern hierarchy; composition over configuration; how the system documents itself (Storybook, visual regression, auto-generated props, accessibility contracts); the stability tier contract; and the Figma↔code relationship. - [references/design-to-code-handoff.md](references/design-to-code-handoff.md) — the four things design hands to code; the audit that catches drift (literal-grep, cross-language duplication check, theme-parity check, visual regression); Style Dictionary as one-source-generates-many-outputs; the sync loop invariants; and the seam to `surface:bulwark`. > **The arc is one non-drifting system.** Three stages — token architecture · the living library · handoff and audit — turn a pile of design decisions into a structurally enforced artifact: the token source of truth is decided and the CSS↔JS boundary collapsed to one author; the component library is alive (running stories, visual regression, accessibility contracts); and design→code drift is caught by CI before it lands, not discovered in a quarterly review. `systems` runs after the other atelier lenses have produced their tokens and before `surface:bulwark` takes ownership of boundary enforcement at 1→N. > **Greenfield or retrofit? Decide the entry, not a new stage.** Most real work is not a blank canvas — it is an existing system thick with literals, two-source tokens, and components that have grown props instead of staying primitive. The three stages are the same; only the entrance differs. If starting clean, walk STAGE 0→2 in order. If a system already exists, do one pass first: **inventory the drift** — every literal in component source, every value duplicated across CSS and JS, every component without a story, every token missing from the dark theme. That inventory is not a deliverable; it is the raw material each gate consumes. The technique for finding where literals hide (the four hiding places: raw CSS/SCSS, CSS-in-JS template literals, JS/TS token objects, inline styles and Tailwind arbitrary values) is in **[references/token-architecture-one-source.md](references/token-architecture-one-source.md)** under *Audit smell list*. The taste call stays a gate: the inventory tells you what exists, never what the architecture should be. --- ## STAGE 0 — Token architecture, one source (collapse the boundary; gate the taxonomy) Open **[references/token-architecture-one-source.md](references/token-architecture-one-source.md)**. Fix the architecture *before* wiring any component. - **Pick the source; close every other author.** The token taxonomy (color / type / space / radius / motion) has exactly one home. The four options are: CSS custom properties as source (JS reads via `var()` strings and `getComputedStyle`); a JS/JSON token module as source (a build step writes CSS custom properties — Style Dictionary is the canonical tool); a CSS-in-JS theme contract (vanilla-extract / Linaria — emits real custom properties at build time, not a runtime `ThemeProvider`); or Tailwind config as source (arbitrary values banned — they re-introduce literals past the config). Pick the one that fits the stack. Whichever you pick, every other direction is read-only — never a second author. The CSS palette is never maintained alongside a JS color object; Tailwind config is never maintained alongside raw CSS vars. - **Install the three-layer architecture.** Raw/primitive names (the OKLCH scales, the spacing steps — theme-agnostic, not consumed directly by components) → semantic/alias names (role tokens: `--color-surface`, `--color-text-primary`, `--space-md` — re-pointed per theme) → optional component hooks (`--button-bg`, `--button-radius` — documented and typed via `@property`). Components consume only semantic tokens or their own declared component tokens. A component that reads `--blue-500` directly is leaking through the architecture. - **`@layer` and `@property` discipline.** Declare the layer order once: `@layer reset, base, tokens, components, utilities`. Tokens in `@layer tokens` — lowest priority, as expected; utilities in `@layer utilities` — highest normal-layer priority. Third-party CSS wrapped in a named layer. Register component API tokens and any animated token with `@property` — typed custom properties interpolate; untyped ones snap; `@property` also documents the type. - **Close the CSS↔JS boundary.** Inline styles must reference `var(--…)`, never literals. Chart/canvas palettes must read from the source (cache `getComputedStyle` on mount/theme-change; do not call per frame). A token audit CI step — a grep for hex/magic-px in component source outside the token files — runs on every PR and fails the build on new matches. ### GATE — clear before LIVING LIBRARY 1. `checklist check token-architecture one-source-of-truth-established` 2. `checklist check token-architecture layer-and-scoping-discipline` 3. `checklist verify token-architecture` --- ## STAGE 1 — The component/pattern library as a living artifact (primitives → patterns; the system documents itself) Open **[references/the-living-component-library.md](references/the-living-component-library.md)**. The library is the system made navigable. - **Establish the primitive → composition → pattern hierarchy.** Primitives own one responsibility, expose a component token API, contain no literals. Compositions assemble primitives without reimplementing them; overrides flow through the primitive's component token hooks, not new CSS rules on the same element. Patterns are complete solutions — documented with every state (empty / loading / error / populated) and an accessibility contract (keyboard, ARIA, axe-core test). Anything used in three or more places is a composition or pattern candidate. Anything with more than a handful of visual-variation props is a composition waiting to be decomposed. - **Make composition the default; configuration the exception.** Boolean explosions (``) become composition slots. Visual variation that is purely token-based becomes a subtree token override, not a prop. Semantic variation (`intent="primary|secondary|danger"`) is the legitimate case for enumerations. The primitive API stays small and stable; compositions and patterns iterate. - **The system must document itself.** Each component has Storybook (or equivalent) stories — running code, not screenshots. Visual-regression tests (Chromatic / Percy) run against stories on every PR; an unapproved appearance change fails CI. Prop tables are auto-generated from TypeScript types and JSDoc. Accessibility contracts are tested in-story. Stability tiers (`Stable / Beta / Experimental`) communicate API stability; `Stable` requires full coverage and a visual-regression baseline. Deprecated props fire a dev `console.warn` and have a one-major-version removal window. - **The Figma relationship.** Figma is an exploration tool; the component library is the source of truth. When they diverge, code wins. The Figma token plugin reads from the token source; it does not author it. "The Figma component is done" is not graduation into `Stable` — "the Storybook story has visual-regression coverage" is. ### GATE — clear before HANDOFF AND AUDIT 1. `checklist check living-library primitive-to-pattern-hierarchy-established` 2. `checklist check living-library system-documents-itself` 3. `checklist verify living-library` --- ## STAGE 2 — Design↔code handoff without drift (the contract; the audit; the sync loop) Open **[references/design-to-code-handoff.md](references/design-to-code-handoff.md)**. The system stays in sync not by heroic communication but by structure. - **Define the handoff contract.** Handoff is a structured diff: token changes as a PR to the token source; component API changes specced in the existing component token language; new patterns as a Storybook story spec with states, token usage, and accessibility contract; and explicit CI-verifiable acceptance criteria (passing story, passing axe-core, visual-regression diff below threshold, zero literals in the token audit). A Figma link with a comment "match this" is not handoff — it is a request to re-derive the system from a screenshot. - **Wire the four drift-audit channels in CI.** (1) Literal-grep: fail on any hex/magic-px in component source outside token files. (2) Cross-language duplication: fail when the same value exists in both CSS and JS (Style Dictionary or a normalization script). (3) Theme-parity: fail when a component token exists in one theme but not the other — a missing dark-theme value triggers IACVT silently. (4) Visual regression: a Storybook diff above threshold requires explicit approval. All four channels run on every PR — drift is caught before it merges, not discovered in a design review. - **The sync loop invariants.** No token change bypasses a PR review. Generated outputs (`dist/tokens.css`, `dist/tokens.js`) are build artifacts — never hand-edited; optionally not committed (regenerated in CI on every build). Figma token plugin reads; it does not write. The loop: design proposes a token change → PR to token source → CI audit → merge → generated outputs update → all consumers see the new value on next build. One direction of authority; every other direction is downstream. - **Hand off to `surface:bulwark`.** Once the token architecture is in place, the living library is generating its documentation, and the CI audit is catching literals and duplication — the boundary-enforcement contract transfers to `surface:bulwark`, which runs the PR review pass that catches drift before it merges. `systems` builds the structure; `bulwark` enforces it at 1→N. This is the handoff: a working drift-audit CI pipeline and a documented component API are the pre-conditions `bulwark` requires. ### FINAL GATE 1. `checklist check handoff-and-audit design-to-code-contract-defined` 2. `checklist check handoff-and-audit drift-audit-is-structural-not-manual` 3. `checklist verify handoff-and-audit` 4. `checklist show` — confirm all three stages passed. 5. `checklist done` — clear this run's state. --- ## The thread through all of it `systems` is the atelier's **structural conscience** — the place the suite's claim that *the design system is itself state* finally gets a gate. It runs after the other atelier lenses have produced their tokens, and its architecture is what `surface:bulwark` later enforces at 1→N. The through-line is the same the whole suite preaches — *push correctness into structure* — applied to the system itself: tokens derived from one source can't drift the way tokens maintained in two languages can; a library with visual-regression coverage can't rot the way a library with screenshots can; a drift audit in CI can't be forgotten the way a quarterly design review can. The line that keeps `systems` honest: **the references hold the encodable technique (the three-layer architecture, the CSS↔JS boundary options, how Style Dictionary works, how Storybook stories become the canonical example); the architecture decisions — which source, which layer discipline, which stability tier — stay gates the user clears.** Blur that line and the skill becomes a recipe book; hold it and it stays a lens. ## Anti-patterns (use as a pre-flight checklist) - **Two sources of the same token** — a CSS custom property … ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [IamK77](https://github.com/IamK77) - **Source:** [IamK77/Skill](https://github.com/IamK77/Skill) - **License:** Apache-2.0 - **Homepage:** https://www.npmjs.com/package/@iamk77/skill-checklist Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-iamk77-skill-systems - Seller: https://agentstack.voostack.com/s/iamk77 - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.