The shared UI system every Versable app is built from
A component kit, a written design language, and the recipes that say what a request for a screen actually brings along.
packages/ui ·
docs/design-language ·
docs/app-patterns ·
apps/playground ·
docs/SCRIPTURE.md ·
CONTRIBUTING.md
Riddle answer
The design canon: most gaps caught in shipped apps were law that had never been written down, now recorded as 13 traits in docs/design-language.
What is this?#
Not an app. This repo holds the things more than one Versable app needs, so a second app does not re-decide them and a third gets cheaper still. Three published packages, and three layers of writing that govern how they are used.
| What it is | Where | |
|---|---|---|
| The kit | every component in the gallery with a contract doc each, table feature hooks, decision-carrying hooks; the counts live on the playground's landing, read from the registry | packages/ui |
| The toolkit | framework-free utilities, zero React by design; published, no consumer yet | packages/toolkit |
| qsync | URL-state sync for tables and filters; the playground consumes it | packages/qsync |
| The canon | the visual law: 13 traits, principles, presets, worked cases | docs/design-language |
| The patterns | how an app is built and documented, plus request-shaped recipes | docs/app-patterns |
| The playground | every component in isolation, and the only home of some primitives | apps/playground |
| The templates | what you copy to start a new app, one per app shape | apps/_templates |
| The contract | a tenant: the foundry contract for everything below the screen (identity, jobs, workers, storage), moving to its own repo in the org split | contract/ |
| Consumed by | walmart-mvp, speedway, and the forge console (versable-forge-v6); their pins are stated once, in CLAUDE.md | sibling repos |
Versable builds a small number of customer apps (Speedway and a Walmart MVP
today) and every screen in them is drawn from the one shared kit. When a
correction is made on a shipping screen it flows back here and becomes law for
everyone; nothing flows the other way. The reason for all of it is that a fix
should be made once and stop being a thing that gets forgotten; that is the
first claim the scripture makes about itself (docs/SCRIPTURE.md, section 1).
One finding worth knowing before you use any of it. Most gaps caught in the
shipped apps were law that had never been written down, rather than law someone
failed to find. Not all: the corrections ledger names a real cluster that cited
a rule which already existed and was simply not applied, the token-layer split
and the amber systems among them
(docs/evidence/20260812-ui-knowledge-plan/L0-ledger-walmart-A.md:31-37). So
this repo is mostly accumulation and partly retrieval, and the next app gets
cheaper only if what it learns comes back here.
Architecture#
Code flows down, law flows sideways, and nothing flows up.
sibling repos this repo┌──────────────────────┐│ walmart-mvp │ imports ┌───────────────────────┐│ speedway │────────────▶│ packages/ui ││ the forge console │ │ every component ││ │ (pins: │ @versable-git/ui ││ three apps │ CLAUDE.md) └───────────┬───────────┘└──────────────────────┘ │ may import ▲ ▼ │ corrections ┌───────────────────────┐ │ flow back │ packages/toolkit │ │ as law │ pure functions │ │ └───────────────────────┘ │┌─────────┴────────────────────────────────────────────────┐│ docs/design-language 13 traits · the visual law ││ docs/app-patterns methods · recipes · primitives ││ packages/ui/docs one contract per component │└──────────────────────────────────────────────────────────┘ governs the kit without the kit depending on itThe upward arrow is the one that matters. A correction caught in a shipped app becomes a canon rule here, which is why this repo grows from the apps rather than the other way round.
Quick Start#
git clone https://github.com/versable-git/versable-builder.gitcd versable-builderpnpm installThis is a pnpm workspace. Run pnpm, not npm, inside it.
Using the kit in an app (not this repo): packages/ui/USAGE.md,
what you came for in one hop and the six steps to adopt the kit; then
packages/ui/README.md for the depth: the registry
line and token, the install and pin, the theme import, the bundler contract,
and the upgrade checklist.
Working on this repo (adding a component, a pattern, a doc):
CONTRIBUTING.md.
Playground (port 5104, and live at https://versable-builder-playground.vercel.app/), the fastest way to see a component render:
pnpm dev # from the repo rootEverything else:
pnpm typecheck # every package, in parallelpnpm test # every packagepnpm build # every packagepnpm lint:tokens # the design-token lintWho reads what#
Two audiences share this repo and they read different files. If a document reads like it was written for a machine, it probably was.
| You are | Start with | Why |
|---|---|---|
| a person who wants to understand the project | this page, then the playground | the pitch, the architecture picture, every piece running |
| a person who will work in the repo | CONTRIBUTING.md | how to set up, run, and add a component, a pattern, or a doc |
| a person or agent putting the kit in an app | packages/ui/USAGE.md, then packages/ui/README.md | what you came for in one hop, the six steps, the scope rule; then the install depth |
| an agent working here | AGENTS.md, then CLAUDE.md | the ground rules and the doc map; not written for people |
| anyone deciding whether to trust a rule | docs/SCRIPTURE.md | why the project exists and an honest list of where it has failed its own goals |
By what you came to do#
| I want to | Go to | What you will find |
|---|---|---|
| see it | the playground, pnpm dev then http://localhost:5104 | every component and pattern rendered live, both themes, and every document below readable in place under /docs |
| put the kit in my app | packages/ui/USAGE.md | what you came for, one hop each; the six steps to adopt the kit; the install depth is in the kit README it points at |
| file a defect, a proposal or a question from an app | docs/plan/INBOX.md | one entry, the shape is in the file; read at the next review run |
| know why any of this exists | docs/SCRIPTURE.md | intent, goals, non-goals, and the failure modes the project admits to |
| know what a screen should look like | docs/design-language/ | thirteen traits, each with principles, presets, and cases cited to the line of code that ships them |
| know how a screen gets built and written up | docs/app-patterns/ and docs/GUIDEBOOK.md | data loading, the surface-doc template, how an app comes onto the kit, and what went wrong in the apps that did it first |
| know what a component takes | packages/ui/docs/ | one contract per component: props, banned combinations, where each shape ships today |
| know what was decided and why | docs/adr/ | the architecture decision records: framework, auth, design tokens, schema codegen, docs publishing |
| know what is banned | docs/DO-NOTS.md | every banned combination and canon do-not in one place, regenerated from source |
| find my way around the written system | docs/index.md | the docs map: what each layer can do for you, where truth lives for a component, the showcase surfaces |
| see how the repo is run | scripts/README.md | the scripts, what each is for, and what each must never do |
| dig through the archive | docs/plan/, docs/evidence/, docs/reference/ | plans, research artifacts, mockups; useful, dated, not swept into the playground on purpose |
The owning statement of how the layers relate (canon is law, component docs
are contract, recipes are what a request brings along) is docs/index.md;
this table routes, the map governs.
Releasing the kit#
The owning copy of the release procedure is the Releasing section of
packages/ui/README.md (bump, scripts/ship-kit.sh,
never a laptop publish, [skip kit] to hold). Consumers pin independently and
upgrade on their own customer-facing work, never because the kit moved;
docs/GUIDEBOOK.md section 4 carries that ruling.
Documentation#
| Where | What it covers |
|---|---|
docs/design-language/ | the visual canon, 13 trait docs, each with principles, presets and worked cases |
docs/app-patterns/ | methods and recipes: data loading, surface docs, E2E derivation, deploying, migration, the two recipes |
packages/ui/docs/ | one contract per component, every component covered |
docs/adr/ | architecture decision records |
docs/plan/ | build plans, the board (TRACKING.md), and the inbox for incoming feedback (INBOX.md) |
docs/reference/ | reference material that is neither law nor method |
docs/index.md | the docs map: what the docs can do, where truth lives for a component, the showcase surfaces |
docs/GUIDEBOOK.md | bringing an app onto the kit, and the retrospective on the apps that did |
contract/ | the foundry contract, a tenant here until the org split: what a module must do to be one, and what every production app needs around it |
docs/SCRIPTURE.md | why the kit exists, its goals, and the failure modes it admits |
pipelines/ | shipping pipelines, currently the docs site template |
user_docs/ | the owner's files; agents read these and never commit them |
How work happens here#
The owner looks at the playground and writes down what is wrong, in their own
words, with a stable ID per item (docs/plan/63-showcase-feedback-5.md is one
such round). Agents group those IDs into a batch of work, build it, verify each
item live in both themes at desktop and phone width, and put the result on the
board, docs/plan/TRACKING.md, under "To be reviewed" for the owner to cross
off. The kit ships when the owner bumps its version and pushes; a workflow
publishes it. Consumer apps stay on their pinned kit version until they upgrade
on purpose; an upgrade rides the next customer-facing piece of work in an app,
because an upgrade for its own sake buys the business nothing. Product
behaviour in Speedway is frozen at the moment; UI and kit work go on.
The source is private, so every GitHub link on the site returns 404 unless you
are signed in with access. The board carries a queue of agent-complete work the
owner has not reviewed yet; the scripture grades that its one MISSING failure
mode (docs/SCRIPTURE.md, section 6, F3).
Where to start. If you have ten minutes: run the playground and click
around. If you have an hour: read docs/SCRIPTURE.md, then one
design-language doc, then the contract doc for the component it talks about,
in that order. That is the whole system in miniature: why, what it should be,
what it promises.
Repo Structure#
versable-builder/├── packages/│ ├── ui/ → @versable-git/ui · React 19 · published│ │ ├── src/ · components, table hooks, the sync seam│ │ ├── theme/ · theme files, imported by subpath│ │ └── docs/ · one contract per component│ ├── ui/USAGE.md · the door for anyone putting the kit in an app│ ├── toolkit/ → @versable-git/toolkit · zero React · published, no consumer yet│ └── qsync/ → @versable-git/qsync · URL-state sync│├── apps/│ ├── playground/ → Next 16 · port 5104 · every component in isolation│ └── _templates/ → what you copy to start a new app: next, react-router-ssr, vite-spa│├── docs/│ ├── design-language/ · the visual law, 13 traits│ ├── app-patterns/ · methods and request-shaped recipes│ ├── adr/ · decision records│ └── plan/ · build plans, TRACKING.md is live│├── contract/ → the foundry contract, a tenant until the org split├── pipelines/ → shipping pipelines, docs-pages today├── scripts/ · repo tooling, each script explained in scripts/README.md└── user_docs/ · owner-authored, never agent-committed