Three things live here: the kit (packages/ui, published as @versable-git/ui), the playground that shows every export, pattern, and doc (apps/playground, pm2 playground-dev on :5104), and the cross-app design canon (docs/). Three apps consume the kit: the sibling checkouts ../walmart-mvp and ../speedway, both pinning ^0.2.2, and ../versable-forge-v6 (the console), which pins an exact version through its own scripts/kit-registry.sh. They stay unchanged until their own deliberate kit upgrade. CONTRIBUTING.md is the how-to (setup, run, add a component, a pattern, a doc); README.md is the repo's front door for humans; docs/SCRIPTURE.md says why the kit is shaped the way it is.

How to work here (2026-08-16)#

• The bar for done. A UI change is done when it has been exercised in the running playground on :5104 in BOTH themes (dark is the literal theme name versable-dark; the toggle writes pg-theme to localStorage and the root layout applies it before paint), not when it typechecks. Kit gate: pnpm typecheck and pnpm vitest run in packages/ui (through fnm, AGENTS.md rule 1), then the browser. Playground gate: pnpm exec tsc --noEmit in apps/playground, then the browser. Before a commit that touches docs or Banned sections: node scripts/ci-citations.mjs (governing layers 0, counts at baseline) and node scripts/build-do-nots.mjs; CI runs both and fails on either, plus pnpm lint:tokens and pnpm -r test (.github/workflows/ci.yml:18-26). A change that meets this bar cannot redden main.
• One registry. apps/playground/src/app/showcase-registry.ts is the route registry: sidebar groups, index cards, breadcrumbs, the header's See also and contract-doc link, the awareness prompt, and search all derive from it. A new page is a registry entry first. apps/playground/src/lib/docs-registry.ts is the same thing for the docs browser (its ROOTS list is an exact allowlist of doc trees and singleton files).
• One frame, one header. Every UI page sits in PageFrame (apps/playground/src/app/page-frame.tsx, the /patterns width) and opens with ShowcaseTitle (or DocTitle for docs, PatternShell for patterns). Header actions are icon-only with a rich two-line tooltip: the label the icon replaced as the tip's title, one line of help as its body (packages/ui/docs/tooltip.md, "The rich preset").
• Prose rules, enforced by hooks. Zero em dashes anywhere (rendered UI, docs, commit messages); mono only for identifiers; a component doc keeps the contract shape in packages/ui/docs/ (contract, sanctioned and banned combinations, a "Before you adopt this" checklist, travels with, snippet; Banned sections feed the generated docs/DO-NOTS.md, so regenerate it with node scripts/build-do-nots.mjs after editing one). Frontmatter keys are shared with mkdocs, so the playground's icon key is kit_icon: (mkdocs claims icon:).
• Kit changes ride the owner's next bump. Never bump packages/ui/package.json as a ride-along; the workflow publishes on push to main. Note unpublished kit surface in the apps' CLAUDE.md files, never auto-upgrade them.
• Canon edits stay one pen. docs/design-language/, docs/app-patterns/, and docs/SCRIPTURE.md are edited by one agent at a time and every change re-runs node scripts/check-citations.mjs docs.
• Owner review rounds. The owner's feedback is recorded verbatim with stable IDs (docs/plan/48-, 53-, 55-showcase-feedback-*.md) and planned in the sibling execution doc (56-review-round-1-plan.md: buckets by how much owner time an item needs, waves, one decision page per sitting). Tasks cite the IDs. docs/plan/TRACKING.md is the board and is never a mirror of a session's task list.
• Sub-agent seats get a territory (exact files), no commit, no kit edits unless named, no browser (the parent verifies live), no nesting, an absolute report path, and stop when done. Every git add is path-scoped; never stage user_docs/speedway-todo.md or speedway/docs/user-notes.md.

The canon (2026-08-09)#

This repo owns the cross-app design canon, and walmart-mvp is its second consumer. Extend in place rather than opening a third home for conventions.

• docs/design-language/: 13 docs, the cross-app visual canon. Section A is principles, B is presets, C is worked use cases cited to file:line.
• docs/app-patterns/: how an app is built and documented rather than how it looks. Data loading, the surface-doc template, the E2E derivation method.
• packages/ui/docs/: per-component API reference. Contract, not law.
• A canon doc's section C renames from "through Speedway" to "through the apps" in the same commit that adds its first non-speedway case. Owner-ruled lazy migration, no sweep.

Overlay canon section A1 is the default decision tree for peek versus modal versus page. A surface may deviate only when the deviation buys better and more consistent UX, with the reasoning stated in that surface's own doc.

Releasing the kit#

Never bump as a ride-along, never publish from a laptop; [skip kit] holds a push. The owning copy of the procedure (bump, scripts/ship-kit.sh, pins, the upgrade checklist) is the Releasing section of packages/ui/README.md.

Speedway is frozen for product work#

Owner ruling 2026-08-09. UI, component and code-pattern work is fine; anything that changes product behaviour needs a fresh ask. See speedway/CLAUDE.md.