Architecture

1The build loop, and the loop that is missing

One loop runs today. A change starts from the written contracts, produces a component together with its story, its documentation and its registry entry, passes the gates locally and in CI, and ends at a person.

The missing loop matters. Gates run when something changes. Nothing re-checks the main branch on a schedule and nothing compares production with it, and because deploys are manual the two have drifted apart before. Closing that gap is planned work.

2What the system is made of

3What is generated from what

Several files in this repository are outputs. Nobody edits them. A command writes each one from its source, and a test or a gate compares the two on every run, so a stale output fails and cannot go on describing an older tree.

• What shadcn add downloads. Built fresh in CI and never committed.

  Source

  apps/docs/registry/super-ai

  Output

  apps/docs/public/r

  Not committed.

  Written by

  pnpm build:registry

  Held by

  apps/docs/scripts/consumer-test.sh

• The contracts layer. One guidance module per component is the source for all of it.

  Source

  apps/docs/content/components

  Output

  apps/docs/registry/super-ai/<name>.meta.json

  apps/docs/index/components.toon

  apps/docs/public/llms.txt

  apps/docs/public/llms-full.txt

  apps/docs/public/llms

  Written by

  cd apps/docs && pnpm contract:emit

  Held by

  apps/docs/scripts/lib/contract-emit.test.ts

• The rule records as JSON, which is what the detector reads.

  Source

  packages/ds-rules/src

  Output

  packages/ds-rules/rules/core.json

  packages/ds-rules/rules/local.json

  Written by

  pnpm --filter ds-rules rules:emit

  Held by

  packages/ds-rules/src/emit.test.ts

• The wiring from each catalog item to its demo and its documentation.

  Source

  apps/docs/lib/catalog.manifest.ts

  Output

  apps/docs/lib/demos.generated.ts

  apps/docs/lib/docs.generated.ts

  Written by

  cd apps/docs && pnpm gen:wiring

  Held by

  apps/docs/scripts/check-contract.mts

• The numbers on these pages, counted from the tree.

  Source

  apps/docs/scripts/lib/system-facts.ts

  Output

  apps/docs/content/system/facts.json

  Written by

  cd apps/docs && pnpm facts:emit

  Held by

  apps/docs/scripts/lib/system-facts.test.ts

The numbers on this page work the same way. They live in apps/docs/content/system/facts.json, and they are as of the last time that file was written. A test fails when the tree has moved past it.

4The gates

Each step below runs in CI and, in the same order, in the local script at .claude/skills/gate-run/run-gates.sh. The order is a list in one place, and a test fails when the workflow, the script and this page disagree.

1. 1Install from the lockfile

   pnpm install --frozen-lockfile

   Every gate below runs against the dependency versions the lockfile records, so nothing passes on a newer package than the one that ships.

   • pnpm-lock.yaml The resolved version of every dependency.

2. 2Lint

   pnpm lint

   Catches unescaped quotes in JSX prose and unused code before a reviewer has to.

   • apps/docs/eslint.config.mjs Rules for the docs app and the registry sources.
   • apps/storybook/eslint.config.mjs Rules for the stories.

3. 3Formatting

   pnpm format:check

   Keeps a diff about the change. A generated file that must match its generator byte for byte is listed as ignored and is never reformatted.

   • .prettierrc.json The one formatting configuration.
   • .prettierignore The generated files whose emitters own their shape.

4. 4Types

   pnpm typecheck

   A prop a component does not declare is an error here, in the registry sources, the stories and the rule records alike.

   • apps/docs/tsconfig.json The docs app, the registry and the scripts.
   • apps/storybook/tsconfig.json The stories, against the real component types.
   • packages/ds-rules/tsconfig.json The rule records.

5. 5Token contract

   pnpm check:tokens

   No raw colour, palette class, gradient or banned motion utility reaches a registry component, so a consumer's theme restyles everything they install.

   • packages/ds-rules/rulecheck.mjs The detector.
   • packages/ds-rules/rules/core.json The bans shared with the sibling design system.
   • packages/ds-rules/rules/local.json The bans specific to this repository.

   Does not see: It reads one class string at a time. Muted text in a child whose ancestor paints the muted surface passes here, and every contrast bug that shipped had that shape. The accessibility step below is the backstop.

6. 6Manifest, story and docs contract

   pnpm check:contract

   Every catalog item has the story exports its declared states promise, documentation whose citations resolve, and dependencies reconciled from real imports.

   • apps/docs/scripts/check-contract.mts Manifest, story and docs agreement, and the generated wiring files byte for byte.
   • apps/docs/scripts/check-citations.mts Every backticked citation in the component docs.
   • apps/docs/scripts/reconcile-deps.mts Declared dependencies against what the source really imports.

7. 7Unit tests and ratchets

   pnpm test

   The ledgers below may shrink and never grow, derived files must match their sources, and the numbers on this page must match the tree.

   • apps/docs/lib/catalog.manifest.test.ts The catalog is complete and the cut families stay cut.
   • apps/docs/scripts/new-component.test.ts The scaffolder never emits a state named default.
   • apps/docs/scripts/lib/a11y-ratchet.test.ts The accessibility exclusion list only shrinks.
   • apps/docs/scripts/lib/story-coverage.test.ts Unmet story obligations only shrink.
   • apps/docs/scripts/lib/contract-coverage.test.ts Unwritten contract fields only shrink.
   • apps/docs/scripts/lib/cssvars-liveness.test.ts Every CSS variable a component reads resolves, and none is declared unread.
   • apps/docs/scripts/lib/contract-emit.test.ts Installed contracts, the routing table and the llms.txt corpus match the guidance modules.
   • apps/docs/scripts/lib/claude-md.test.ts The instructions file stays under its byte ceiling, and each rule in it names a gate.
   • packages/ds-rules/src/emit.test.ts The emitted rule JSON matches the typed records.
   • apps/docs/scripts/lib/system-facts.test.ts The numbers on these pages match the tree.
   • apps/docs/content/system/gates.test.ts This roster matches the workflow and the local gate script.
   • apps/docs/content/system/claims.test.ts Counts typed into prose elsewhere match the tree.
   • apps/docs/content/system/pages.test.ts These pages cite real files, type no numbers and keep the writing rules.

   Ratchets: apps/docs/cssvars-liveness.baseline.json, apps/docs/scripts/lib/contract-coverage.baseline.json, apps/docs/scripts/lib/story-coverage.baseline.json, apps/storybook/a11y-exclusions.baseline.json

8. 8Registry build

   pnpm build:registry

   Regenerates what consumers install. A stale registry is invisible locally and broken for them.

   • apps/docs/scripts/gen-wiring.mts The generated wiring between manifest, demos and docs.
   • apps/docs/scripts/gen-registry.mts The registry index that shadcn build reads.

9. 9Full build

   pnpm build

   The docs app and Storybook both compile from the same sources the registry ships.

   • apps/docs/next.config.ts The docs app build.
   • apps/storybook/.storybook/main.ts The Storybook build.

10. 10Smoke test of every page

    Playwright smoke

    Every component page renders in a real browser without a console error.

    • apps/docs/e2e/smoke.spec.ts One test per catalog item, plus the system pages.
    • apps/docs/playwright.config.ts Serves the built app on its own port.

    Does not see: It serves the prebuilt app. Edit a source file without rebuilding and a green run proves nothing.

11. 11Accessibility and interaction

    Storybook a11y + interaction

    Every story passes axe and its own interaction assertions in Chromium. This is the step that catches the contrast shape the token gate cannot see.

    • apps/storybook/vitest.config.ts Runs every story in a browser, with the exclusion list the ratchet guards.

12. 12Consumer install

    Consumer install test

    Installs every item into a fresh app with shadcn add and builds it. A component that looks right here and breaks there has failed.

    • apps/docs/scripts/consumer-test.sh The install and the build, end to end.

Two properties are deliberate. 4 ledgers are ratchets: the accessibility exclusions, the unmet story obligations, the unwritten contract fields and the CSS variable debts may shrink and may never grow. And a scanner earns trust by failing first: every rule record ships a fixture that must trip it, because a scan that finds nothing and a scan that looked at nothing print the same result.

5Usage contracts

Every item has a guidance module, and its contract is derived from that module. These are the fields an agent reads before placing a component.

A field nobody has written yet is recorded as unwritten. It is never filled with an empty value, and the count of unwritten fields is one of the ratchets.

6Stories and coverage

A story file holds two kinds of story. Declared-state stories restate the types: one export per state the manifest declares, and a gate fails when one is missing. Case stories are the only place a component's real situations are written down: long content, an empty list, a narrow screen.

Every story runs in Chromium with axe. That step is the backstop for the contrast shape the token gate cannot see, and its exclusion list is a ratchet.

7A change, end to end

1. Read the map in CLAUDE.md, then the build brief, then the routing table, so nothing gets built twice.
2. Scaffold the component with pnpm new:component. The files it writes move together.
3. Write the judgment into the guidance module: when to use it and what to avoid, each with a reason.
4. Run the anti-slop audit before building and again before calling it done.
5. Run every gate locally, in the workflow's order, from the repository root.
6. Open a pull request from a branch. Nothing is committed to the main branch directly.
7. A person reviews. Merging does not deploy. Production ships by hand.

8The principles underneath

The registry is the product. A component that looks right in Storybook and breaks on install has failed.

A list of gates mirrors the workflow, in the workflow's order. CI stops at the first failure, so one red gate hides every gate behind it.

A green run can prove nothing. A test that serves a prebuilt app says nothing about source edited since the build.

An exclusion list may only shrink. Adding a file to silence a failure defeats the gate.

Blocks compose. When a composed component does not fit, the gap gets reported, and the component does not get reimplemented.

A number typed into prose goes stale. Count it from the tree or leave it out.

• Harness: what this system is, and how to say so
• The component catalog