Docs map

The four layers and what each can do for you, where truth lives for a component, the showcase surfaces, and where everything sits on disk.

Where to find the answer to a question about the kit or a screen built on it: which document covers what, where truth lives for a component, the surfaces the playground renders, and where each file sits on disk. Open the doc the question points at; do not read this page end to end.

The four layers#

Scripture (docs/SCRIPTURE.md): what the kit is for, the claims it makes about itself, the failure modes it acknowledges, and how success is measured.
Design language (docs/design-language/): the cross-app visual canon. Principles first, presets second, worked cases cited to file and line.
App patterns (docs/app-patterns/): how an app is built and documented on the kit: data loading, surface docs, E2E derivation, deployment, migration, the request-shaped recipes.
Kit contracts (packages/ui/docs/): one page per component, the API contract with sanctioned and banned combinations, and where each shape ships today.

docs/GUIDEBOOK.md is how an app comes onto the kit and the retrospective on the apps that did; packages/ui/USAGE.md is the door for a person or agent putting the kit into an app (what you came for in one hop, the six steps, the scope rule), and packages/ui/README.md is the install depth behind it. The live showcase of every component and pattern is the playground app, which also renders every document here in place under /docs.

Where truth lives for a component#

The import is always import { X } from "@versable-git/ui".

Existence: packages/ui/src/index.ts, the authoritative barrel. If it is not exported there, it does not exist.
Contract: packages/ui/docs/<component>.md, one file per component, kept current per release. Each carries a "Before you adopt this" checklist; the ones that retire a canon rule also carry a "What this saves you" section naming it.
Appearance and states: the playground gallery, one page per component.
Which rules a primitive retires overall: docs/app-patterns/12-primitives-and-rules.md.

Counts and inventories are read from the barrel and the registries, never restated here; a restated inventory drifts within weeks.

The two showcase surfaces (in `apps/playground`)#

/components/*, the gallery. One page per component, every state, wrapped in an AppShell chrome. This is where you check what X looks like and what props exist, visually.
/patterns/*, the patterns. Composites that shipped, each with problem, use-when and provenance rows cited to app file:line.
/demo/*, the product demo. The speedway-mock screens on real kit composition with fictional data; demo/jobs and demo/review are the canonical composition references. /shell-demo is the demo shell full-viewport.
/docs/*, this written system, rendered in place, searchable from the palette (Cmd-K), with a Copy prompt on every page that briefs an agent.
Theme: the one toggle sits in the navbar (the topbar moon); a floating page-level toggle is an anti-pattern (owner O3, 2026-08-16). The attribute lives on <html>, persisted in localStorage pg-theme.

What the docs can do for you#

Each row is a thing the docs can do for a reader and the page that does it.

#	The docs can	The page that does it
1	Tell you exactly what a component takes and forbids	the contract docs, one per component, `/docs/kit/<name>` (`packages/ui/docs/`)
2	Tell you which component to use for a need	`/components/menus-and-pickers` (the pickers), `/components/chip-compare` (three tag species), `/components/toolbar-compare` (three toolbars); the docs home cards' phrases
3	Show a composite that shipped, with the source and where it ships	the pattern pages, each with problem, use-when, and provenance rows cited to app file:line (`/patterns`)
4	Say why a surface looks the way it does, and name its presets	the canon docs, section A (principles) and B (presets), `/docs/design/*` (`docs/design-language/`)
5	Say what not to do	the banned-combination sections of the contract docs; the canon's "never" sentences; the app-patterns do-nots (AP-10, AP-11, classified in `docs/app-patterns/12-primitives-and-rules.md`); all of them in one place in the generated lens `docs/DO-NOTS.md` (`/docs/canon/do-nots`)
6	Find anything by name	the search palette (Cmd-K) over the route registry, in every section
7	Brief an agent on any page	the Copy prompt action in every showcase header (the awareness prompt)
8	Read the repo's own docs in place	the docs browser over the repo's roots (`apps/playground/src/lib/docs-registry.ts`)
9	Prime an agent to work in this repo	`CLAUDE.md` (judgment), `CONTRIBUTING.md` (the how-to as a network of edits), `AGENTS.md` (routing)
10	Say why the kit exists and how it can fail	`docs/SCRIPTURE.md`: intent, goals, non-goals, mechanism, agent behaviour, the acknowledged failure modes, success criteria
11	Walk a real page layer by layer	`docs/breakdowns/`, six docs (`/docs/breakdowns/*`): speedway jobs and review, walmart Jobs and Import, the kit shell and the kit Button gallery, each read shell to primitives to patterns to the canon rules in force, with a Lapses section
12	Migrate an app onto the kit, and learn from the apps that did	`docs/GUIDEBOOK.md` (`/docs/canon/guidebook`): the standard half (the four layers, starting fresh or bringing one over, reading order, pins, how a correction becomes law, validating a change) and the retrospective half (a 20-row timeline, 28 lapses each with what would have caught it sooner, five recurring families)
13	Pick type sizes, colour as meaning, and pairings, and avoid the type do-nots	`/components/typography` (the scale, the ink ladder, mono policy), `/patterns/typography-composites` (title sets, kicker plus title, stat phrases), `/components/kicker`, and canon doc 12 (`docs/design-language/12-typography.md`), under the rulings in `docs/plan/60-typography-structure.md`
14	Install and upgrade the kit in an app	`packages/ui/README.md` (`/docs/start/kit-readme`): prerequisites, registry and token, install and pin, theme import, bundler contract, the upgrade checklist

How to read the docs#

The canon says why and names the presets (section A and B of the canon docs); a contract doc says what the component takes and forbids; a pattern shows a composite that shipped; the do-nots lens says what to avoid. This paragraph is the owning copy of how the layers relate; the front door, the kit README and the guidebook point here rather than restating it. Start from what you were asked for (docs/design-language/00-overview.md, "Start from what you were asked for, not from a trait"), then go one layer down.

The other two repositories#

This repo is the kit. The product that consumes it and the contract it is consumed under each keep their own docs, linked here by GitHub URL and never copied. One exception for now: the foundry contract's own tree lives in this repo as a tenant under contract/ (charter, system classes, wire contracts, guides, its own do-nots and ADRs) and is served in the docs browser under "Foundry contract"; it moves to versable-foundry in the org split (row #63).

Question	Where
the workflow console built on this kit: its screens, job lifecycle, and per-screen surface docs	versable-forge-v6 `docs/README.md`, the map; `docs/surfaces/` for one doc per screen
the module contract and the runner: canon, wire contracts, the modules the console runs	versable-foundry `docs/README.md`, the map; `docs/modules/` for the module ledger and one doc per capability
how a capability's `params` schema becomes a form in the console	this repo owns the answer: `packages/ui/docs/schema-form.md`; the modules declare the schemas

Where it lives on disk#

The playground's docs browser renders these trees off the repo's filesystem, plus the repo's own root singletons; nothing is copied into the app.

versable-builder/
├── README.md                       the front door: who reads what, the map by what you came to do
├── CONTRIBUTING.md                 how to set up, run, and extend this repo
├── CLAUDE.md                       agent notes: how to work here, the doc map, the freeze, the consumer pins
├── AGENTS.md                       ground rules an agent must not break
├── docs/
│   ├── index.md                    this page
│   ├── SCRIPTURE.md                the intent layer
│   ├── GUIDEBOOK.md                bringing an app onto the kit, pins and upgrades, the retrospective
│   ├── DO-NOTS.md                  every banned combination, generated from source
│   ├── design-language/            the visual canon
│   ├── app-patterns/               the method docs and recipes
│   ├── breakdowns/                 six real pages read layer by layer
│   ├── canon/                      the curator's notebook for the canon feedback loop
│   ├── ui-categorical/             the twelve categorical bug classes a UI review checks
│   ├── adr/                        architecture decision records, not swept into the browser
│   ├── plan/                       dated planning docs, the board (TRACKING.md), the inbox (INBOX.md); not swept in
│   ├── evidence/                   research artifacts a plan doc cites, not swept in
│   └── reference/                  mockups and one-off comparisons, not swept in
├── packages/
│   ├── ui/
│   │   ├── USAGE.md                the door for anyone putting the kit in an app
│   │   ├── README.md               the install depth: registry, pin, theme, bundler contract, upgrading
│   │   ├── CHANGELOG.md            what each release adds, changes and retires
│   │   ├── docs/                   one contract doc per component, plus the derived inventory
│   │   └── method/                 verbatim copies of the canon and recipes, shipped in the package
│   ├── toolkit/                    framework-free utilities, published, no app consumer yet
│   └── qsync/                      the URL half of the table sync seam
├── apps/
│   ├── playground/                 the gallery, the docs browser, the demo
│   └── _templates/                 what you copy to start a new app, one folder per shape
├── contract/                       the foundry contract, a tenant until the org split
└── pipelines/                      the docs site template

How the docs browser groups it#

The playground's /docs rail is the same files in reading order rather than disk order: four groups of singletons, then the four swept trees, each tree's README as its first row. The file beside each row is what the row renders.

/docs
├── Start here            the front door
│   ├── README                        README.md
│   ├── Use the kit                   packages/ui/USAGE.md
│   ├── Install and upgrade the kit   packages/ui/README.md
│   └── Docs map                      docs/index.md (this page)
├── Working here          how to work on the repo
│   ├── Contributing                  CONTRIBUTING.md
│   ├── CLAUDE.md                     CLAUDE.md
│   ├── AGENTS.md                     AGENTS.md
│   └── Toolkit                       packages/toolkit/README.md
├── Canon                 why, how an app comes on, what is banned
│   ├── Scripture                     docs/SCRIPTURE.md
│   ├── Guidebook                     docs/GUIDEBOOK.md
│   └── Do-nots                       docs/DO-NOTS.md (generated)
├── Design language       docs/design-language/*.md, README first
├── App patterns          docs/app-patterns/*.md, README first
├── Layer breakdowns      docs/breakdowns/*.md, README first
├── Kit contract docs     packages/ui/docs/*.md, the contract docs only
├── Reference             looked up, not read through
│   ├── Kit changelog                 packages/ui/CHANGELOG.md
│   ├── Kit inventory                 packages/ui/docs/KIT-INVENTORY.md (generated)
│   ├── Kit patterns index            packages/ui/docs/patterns.md
│   ├── Scripts                       scripts/README.md
│   ├── Kit coverage ledger           apps/playground/COVERAGE.md
│   ├── Toolkit proposals             packages/toolkit/PROPOSALS.md
│   ├── App templates                 apps/_templates/README.md
│   └── Pipelines                     pipelines/README.md
└── Foundry contract      contract/, seven groups (index, canon, wire contracts,
                          guides, patterns, instances, ADRs), a tenant until
                          the org split

Everything under docs/design-language/, docs/app-patterns/, docs/breakdowns/, packages/ui/docs/ and contract/, plus the singletons above, gets a route in the playground, one per file. The rail is generated from apps/playground/src/lib/docs-registry.ts; when this listing and the rail disagree, the rail is right and this listing is behind. plan/, evidence/, adr/ and reference/ are real work in the repo, but no route reads them: open those straight from the repo when you need a decision's paper trail rather than its conclusion.