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

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.

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. Across 73 owner corrections mined from the two shipped apps, there were zero retrieval failures. Every gap was law that had never been written down, not law someone failed to find. So the value of this repo is accumulation rather than lookup, 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    ┌───────────────────────┐
│  pins ^0.0.24        │────────────▶│  packages/ui          │
├──────────────────────┤             │  every component      │
│  speedway            │  declares   │  @versable-git/ui     │
│  ^0.0.14, flagship   │────────────▶└───────────┬───────────┘
└──────────────────────┘                         │ 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 it

The 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.git
cd versable-builder
pnpm install

This is a pnpm workspace. Run pnpm, not npm, inside it.

Using the kit in an app (not this repo): packages/ui/README.md, the prerequisites, 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 root

Everything else:

pnpm typecheck           # every package, in parallel
pnpm test                # every package
pnpm build               # every package
pnpm lint:tokens         # the design-token lint

Who 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.

By what you came to do#

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#

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
│   ├── 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
│
├── pipelines/         → shipping pipelines, docs-pages today
├── scripts/           · repo tooling, six scripts, each explained in scripts/README.md
└── user_docs/         · owner-authored, never agent-committed