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 two that did; packages/ui/README.md is how an app installs and upgrades 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 "What this saves you" section naming the canon rules the component retires, and a "Before you adopt this" checklist.
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 two 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.

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
├── 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
│   ├── adr/                        architecture decision records, not swept into the browser
│   ├── plan/                       dated planning and review docs, not swept in
│   ├── evidence/                   research artifacts a plan doc cites, not swept in
│   └── reference/                  mockups and one-off comparisons, not swept in
└── packages/ui/
    ├── README.md                   the kit's front door: install, bundler contract, upgrading
    ├── CHANGELOG.md                what each release adds, changes and retires
    └── docs/                       one contract doc per component

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
│   ├── 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)
├── Reference             looked up, not read through
│   ├── Kit changelog                 packages/ui/CHANGELOG.md
│   ├── Scripts                       scripts/README.md
│   └── Toolkit proposals             packages/toolkit/PROPOSALS.md
├── 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

Everything under docs/design-language/, docs/app-patterns/, docs/breakdowns/ and packages/ui/docs/, plus the singletons above, gets a route in the playground, one per file. 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.