Use the kit

You are here because you want to build something with the kit and do not yet know your way around. This page gets you to the one thing you need in one hop and no further. The repo's README is the visitor's door (what this is and why); this is the door for someone who is about to use it, human or agent.

The whole page is fetchable at one URL, so an agent can be pointed at it before it writes a line:

https://raw.githubusercontent.com/versable-git/versable-builder/main/packages/ui/USAGE.md

Paths below are relative to the installed package (node_modules/@versable-git/ui/). Reading this in the repo or the docs browser, the same files sit at packages/ui/ and the canon at docs/.

What did you come for?#

The scope rule, before anything else#

Do the task you were given, at the size you were given it. What that means depends on what you are touching.

An existing screen, a small change. Stay inside it. If the product hand-rolls what the kit provides, leave it and add one dated line to CANON-NOTES.md (step 5) saying what you saw. Do not propose moving every list page onto DataTable because you were asked for one filter chip.

A new screen, a new app, or a screen you were asked to build or rebuild. The kit is the default, not an option. Use the kit's component, pattern or recipe for every part it covers, and hand-roll only what kit-inventory --find shows it lacks. Hand-rolling a part the kit has, because the task did not mention the kit, is the failure this page exists to prevent. Record each gap in CANON-NOTES.md.

Questions. Do not ask the user which canon doc to read. The table above answers it.

Building a new app or a new screen: do this first#

This applies to a whole app, or to a screen with no sibling to copy. For one change on one screen, step 4 below is enough.

1. Before any code, list each screen in CANON-NOTES.md with its archetype (reading page or work surface, method/design-language/09-page-composition.md), its recipe and its zones. If no recipe fits, write that down and compose from docs/patterns.md.
2. Run npx kit-inventory --find for every noun on every screen, and check docs/common-requests.md for the owner's own phrasing.
3. Read whole: canon 02 buttons, 03 status language, 05 cards, 07 toolbars, 09 page composition and 13 forms. Then the contract and Banned list of each component you import, then method/DO-NOTS.md.
4. Apply the house rulings in method/app-patterns/05-starting-a-new-app.md even where a doc is silent. They are the owner's.
5. Write the page frame once (one constant used by the pages and every skeleton) and one page-meta table that feeds nav, titles and document.title.
6. Build outward in: shell, frame, states, then each screen from its recipe, never from the component list.
7. After the first screen renders, stop and run npm run check:render on it (step 6 below). Fix what it finds now, before the second screen.
8. Anything the kit could not give you is a dated CANON-NOTES.md line. A workaround with no line is a defect.
9. When something looks or behaves wrong, name it before you fix it, using method/app-patterns/18-defect-vocabulary.md (law, kind, root, severity). The root says whether the fix belongs in your app or in the kit.

The six steps to adopt the kit#

Skip the ones you have done. An app that already runs the kit needs only steps 3, 4 and 6 for a change; step 6 is never skipped for UI work.

1. Point your agent at the method#

The package carries its own method, not only its exports. Paste this into the task or the app's AGENTS.md:

Read node_modules/@versable-git/ui/USAGE.md, then method/README.md in the
same package, before building UI. The contract doc for each component is
docs/<component>.md there; the banned combinations are method/DO-NOTS.md.
Do the task at the size it was given; file what the kit lacks in CANON-NOTES.md.

2. Install#

npm install @versable-git/ui

What arrives: src/ and theme/ (the kit ships raw TypeScript, compiled by your app's build), docs/ (a contract doc per component plus KIT-INVENTORY.md and llms.txt), method/ (the design canon and the screen recipes), bin/ (the two checks below), prompts/ (a brief for your own agent). The registry line, the token, the theme import and the bundler contract for Next and Vite are in this package's README.md, Install.

3. Ask before you build#

The kit probably already has it. One command answers across components, patterns, contract docs and banned rules, stamped with the version your tree actually resolves:

npx kit-inventory --find "side panel"

4. Read for the task, not the shelf#

For one change on one screen: the contract doc of the component you touch (docs/button.md), the recipe for the screen shape (method/app-patterns/10-recipe-browsable-list.md for a list, 11-recipe-record-detail.md for a record), and method/DO-NOTS.md before you ship. The canon doc for the surface sits in method/design-language/ (06-tables.md, 10-overlays.md, 13-forms-and-fields.md). For a new app or screen, read what the brief above lists instead.

5. Wire the canon check#

"scripts": {
  "canon-check": "canon-check"
}

A change that touches UI paths leaves a dated line in CANON-NOTES.md saying what the kit could not give you and what you did instead; that note is read by a curator and may land in the kit, which is what it buys you. Findings are graded fix or note, and the author demotes any finding in one line with // canon: <reason> on the deviating line. It runs on demand and in review. It is not a build gate in your CI; it is a hand-back gate, below.

6. Verify before you hand back#

Do not report UI work done until two things have happened. First, npm run check exits 0 (typecheck and canon-check). Second, the render check has run on every route and tab: start the app, then npm run check:render (the kit-standard bin over the routes in kit.routes.txt, both themes, 1280 and 390), with every fix-severity row cleared or marked // canon: <reason> on the deviating line. A route list shorter than the nav is a defect. The three app templates wire both scripts. An app that did not start from a template adds them: check runs your typecheck and canon-check, and check:render runs kit-standard --base <url> --routes-file <path>, which needs Playwright (npm i -D playwright, npx playwright install chromium) and a kit of 0.3.0 or later.

Also run your app's own tests, and look at the screen in both themes. For a claims pass over your whole app (copy promising what is not wired, flags gating nothing, offers to dead routes), point your agent at node_modules/@versable-git/ui/prompts/claims.md; it is advisory by construction and reads only your tree and this package.