Start here
The front door: what this is, how to install and upgrade the kit, and the map of everything written.
README
The repo's front door. What each layer is, who reads what, the map by what you came to do, and how work happens here.
Install and upgrade the kit
How an app gets the kit and keeps it current: prerequisites, registry and token, install and pin, the theme import, the bundler contract for Next and Vite, the upgrade checklist.
Docs map
The map of the written system: what the docs can do, where truth lives for a component, the showcase surfaces, what is on disk where.
Working here
How to work on this repo: the contributor's how-to, the agent's ground rules and doc map, and the toolkit.
Contributing
How to work on this repo itself: set it up, and add a component, a pattern, or a doc as the network of edits each really takes.
CLAUDE.md
Agent notes. Which doc is authoritative, what the canon owns, how the kit is released, and what is frozen.
AGENTS.md
The ground rules an agent must not break here: node, the dev server, semantic tokens, verify by running.
Toolkit
The toolkit's own README: nineteen modules, the runtime-suffix convention, what was fixed on port, and the pending publish decision.
Canon
Why the kit exists and how it can fail, how an app comes onto it, and everything that is banned.
Scripture
Why this project exists, what it must achieve, and an honest list of the ways it fails.
Guidebook
How to bring an app onto the kit, new or already built, and what went into speedway and walmart: the timeline, the lapses, what would have caught each sooner.
Do-nots
Every banned combination and canon do-not in the kit and the design language, in one place.
Reference
Looked up, not read through: what each release changed, the scripts the repo runs by hand, and the toolkit's backlog.
Why these stand apart
These three are reference, not reading. Nobody starts here and nobody reads them end to end: a release note is consulted when a pin moves, a script's entry when it is about to be run, the proposals file when a helper is about to be filed. Keeping them out of the reading groups keeps those groups short enough to read.
Kit changelog
Per release: added, changed on existing screens, and the Retires line naming the local copies it makes redundant.
Scripts
The do-nots regen, the citation checker, the dev-server guard, the triad push, and the retired hand publish, each from its own header.
Kit coverage ledger
The showcase pass instrument: exports vs gallery vs nav vs consumers, with the re-derivation method. Frozen at 0.0.25.
Toolkit proposals
Where an app agent files a generalizable helper in six lines. Open, snoozed, landed, discarded; nothing is deleted.
App templates
The starting points for a new app: one runnable skeleton per shape, each with its copy-out checklist, bundler contract, and build canary.
Which layer answers your question
The most common way to waste time here is reading the wrong layer.- Component propsWhat props does a component take
- Look and whyWhat should this look like, and why
- A list pageI was asked for a list page, what does that involve
- A record detailI was asked for a record detail
- Rules handled for youWhich rules does a component already handle for me
- MigratingHow do I bring an existing app onto this
- A new appHow do I start a new app
- A repo READMEHow should a repo README look
Working in walmart-mvp or speedway?
The kit gets the superset of what both apps need; an app stays on its pinned version until its own deliberate kit upgrade.Check your pin first. A rule written for a kit version is unreachable below it: walmart pins , speedway pins , and a caret on a 0.0.x version is a patch pin, so speedway resolves to exactly 0.0.14. The current numbers live in the design language overview.
Bringing an app onto the kit?
New or already built: install first, copy a template or migrate, then read the recipe for the screen you were asked for.The install page is the first hour (prerequisites, registry and token, theme import, the bundler contract). A new app starts from a template; an existing one migrates screen by screen. The guidebook is what went wrong the first two times.
Start here
The front door: what this is, how to install and upgrade the kit, and the map of everything written- READMEThe shared UI system every Versable app is built from.
- Install and upgrade the kitThe kit's front door: prerequisites, the registry line and token, install and pin, the theme import, the bundler contract, the upgrade checklist, where the design comes from.
- Docs mapThe four layers and what each can do for you, where truth lives for a component, the showcase surfaces, and where everything sits on disk.
Working here
How to work on this repo: the contributor's how-to, the agent's ground rules and doc map, and the toolkit- ContributingHow to set up, run, use, and extend this repo (formerly USAGE.md): a component, a pattern, a doc, as the network of edits each is.
- CLAUDE.mdAgent notes: how to work here, the doc map, the canon, releasing the kit, the freeze.
- AGENTS.mdRouting guide for any agent working in this repo.
- ToolkitThe framework-free utility package: what is in it, what each module belongs with, and who uses it.
Canon
Why the kit exists and how it can fail, how an app comes onto it, and everything that is banned- ScriptureThe intent layer: why this project exists, what it must achieve, how it works.
- GuidebookBringing an app onto the kit, new or already built: the layers, the order of work, the pin rules, how a correction flows back, and the retrospective on speedway and walmart.
- Do-notsEvery banned combination and canon do-not in one place, regenerated from source.
Design language
The cross-app visual canon: principles, presets, and worked cases cited to source- Design language indexThe thirteen traits, the layer-relation table, and the pin caveat.
- 0 · Overview and mental modelThe UI decisions, patterns, and behaviors proven in Speedway, codified.
- 1 · FoundationsColor, typography, spacing, radius, shadow, and responsiveness.
- 2 · Buttons and actionsThe one clickable-action control and its color, weight, icon, and wording rules.
- 3 · Status languageBadges, chips, pills, dots, banners, alerts, and the vocabulary rules behind them.
- 4 · Loading, empty, and error statesSkeletons, spinners, pending feedback, empty states, and in-page errors.
- 5 · Cards, surfaces, and stat tilesCards, framed sections, stat tiles, and surface spacing.
- 6 · TablesThe kit's richest component and the usage grammar around it.
- 7 · Toolbars and filtersList toolbars, facet dropdowns, search, and filter-state conventions.
- 8 · Navigation and shellSidebar, topbar, breadcrumbs, page title, activity rail, and the shell contract.
- 9 · Page compositionPage widths, padding, section rhythm, responsiveness, and the two page archetypes.
- 10 · OverlaysPeek panels, modals, dropdowns, and toasts, and the decision tree between them.
- 11 · MotionAnimation conventions, entrance patterns, and working cues.
- 12 · TypographyThe ramp, the roles, the title sets, the ink ladder, mono, tracking, truncation, and the do-nots.
- 13 · Forms and fieldsOne field anatomy, the widths that give a form its rhythm, sections as cards, the mode chooser,…
App patterns
How an app is built and documented: data loading, surface docs, E2E derivation- App patterns indexMethods versus recipes, and what each doc covers.
- 0 · Data loadingHow a Versable app gets data onto a screen.
- 1 · Documenting a surfaceThe authoring convention for a Versable app's surface docs.
- 2 · Deriving E2E cases from a surface docThe method.
- Deploying a Versable app on GCPA manual path for development, an automatic path for shipping, on GCP.
- Bringing an existing app onto the kitBringing an app that already works onto the kit without breaking what it does today.
- Starting a new app on the kitThe mirror of 04-migrating-an-app.md.
- The shape of a Versable repo READMEOne README structure for every Versable repo.
- 10 · A browsable listYou were asked for a list, a table, a queue, an index, a "page showing all the X".
- 11 · A record detailShowing one record's detail: a preview, a drill-in, everything about the row.
- Which rules a primitive could retireEvery rule in this system was written because a human caught something on a screen.
- 13 · When a solution is unsuitableHow to tell a solution does not fit, and how request-versus-reality drift means rethink, not one-shot.
- 14 · Validating a UI changeThe pass a UI change goes through before it is called done, the skills that run it, and when each one fires.
- 15 · Claim status vocabularyThe three grades a claim about the system may carry, what each one demands, and the rule that a rule nobody reads is not a rule. Cited by the scripture and by the platform contract.
- 16 · A module settings formYou were asked for a settings page, a module's parameters, a wizard step that configures a run, a…
Layer breakdowns
Six shipping pages taken apart layer by layer, shell to canon rule, with the lapses each one shows- Layer breakdowns indexThe breakdown template and the six pages it was applied to.
- Speedway: jobs listThe jobs list, layer by layer, a bespoke shell wrapping a work surface built almost entirely from one shared table component.
- Speedway: manual review queueThe manual review queue, the same shell as the jobs list, but under a filtered work surface with selection and editing pulled outside the table model.
- Walmart: JobsThe kit's AppShell in its one real consumer, a jobs table whose expanded row is a workflow stepper, and a toolbar the app built before the kit shipped one.
- Walmart: Import partsThe import flow, where a Dropzone plays the part of the page's own card and a duplicate-resolution modal carries most of the page's real logic.
- Kit: the AppShell galleryThe AppShell gallery, seven real shell shapes behind one tab strip, and a toolbar link that now takes the shape its own contract doc names.
- Kit: the Button galleryThe Button gallery, seventeen example cards deep, deliberately including the props no shipping screen has exercised yet.
Kit contract docs
One contract per component: props, sanctioned and banned combinations, snippets- AlertThe inline callout for a note, warning, or error that belongs in the page flow.
- AppShellWhole-app chrome: nav sidebar, topbar slots, and the padded page frame.
- BreadcrumbsWhere the reader is, spelled out; the trail above a page and the topbar crumb.
- ButtonThe kit's one clickable-action control.
- CardThe kit's one surface for grouped content.
- ChipA small toggleable tag, backed by daisyUI's badge and its style modifiers.
- CodeBlockStored source you can read, scroll, and copy, in a bordered frame.
- CopyButtonThe one-click copy control that acknowledges itself.
- DropdownA positioning primitive built on floating-ui, not a menu component.
- DropzoneA drag-or-browse file picker, the upload wizard's first step.
- EmptyStateThe "nothing here yet" preset over PageInfo for tables, lists, and search.
- FieldChipThe name of a data field or source file as a small pill: a label, never a value.
- IconThe registry that stands between every component and react-icons.
- Identity (IdentityRow / WorkspaceSwitcher)IdentityRow and its avatar: the person, workspace, or org strip.
- InlineEditText that edits in place: hover reveals a pencil, click swaps in an input.
- InputOne field for text, numbers, or a single checkbox or toggle.
- KickerThe small uppercase label that opens a section or names a tile; one primitive, two sizes.
- Kit inventoryEverything the kit provides in one derived list, components, patterns, contracts and do-nots.
- ListItemOne row of a list-in-card: icon or avatar, title, subtitle, metadata, actions.
- MarkdownA stored markdown document rendered with the kit's own parts.
- ModalThe dialog shell for a detail that IS the task.
- PageInfo, PageLoading, PageErrorThe centered icon, title, subtitle, and actions block when the page IS the message.
- PageSkeletonThe shape of the page that is coming, drawn while it loads, so nothing jumps when it lands.
- PageTitleThe page header row: identity, title and subtitle, inline zone, actions.
- PatternsApp-level composites built from kit primitives, each proven on a shipping screen.
- SchemaFormA form generated from a module's JSON Schema, in the kit's one field anatomy; refuses anything outside its vocabulary by name.
- SelectThe picker: a control button that opens a keyboard-navigable option list.
- SidePanelThe persistent right-hand column for secondary content beside the page.
- Spinner / Skeleton / SkeletonGroup / ProgressLoading primitives, thin wrappers over daisyUI's loading and progress.
- StatTileThe dashboard number tile: icon, label, one big figure, optional trend.
- StatusPill / StatusDotThe house vocabulary for how a record is doing, in two sizes.
- StepperA pipeline's stages in one strip; circles, connectors, and an optional click per stage.
- TableA lean presentational Table plus six independent feature hooks.
- TabsThe tab strip: pipeline stages, settings sections, record detail views.
- TimestampA relative time ("2h ago") that reveals the full, localized date and time on hover.
- ToastThe app's transient notification stack, reached only through pushAlert.
- TooltipA hover and focus label for an icon's meaning or a truncated value's full text.
Reference
Looked up, not read through: what each release changed, the scripts the repo runs by hand, and the toolkit's backlog- Kit changelogWhat each release adds, what changes on screens an app already has, and what an app can delete once it takes it.
- ScriptsThe six scripts this repo runs by hand, what each is for, when to run it, and what it must never do.
- Kit coverage ledgerEvery kit value export, where the gallery shows it, and how many files import it in each app. Frozen at 0.0.25; re-derive before quoting.
- Toolkit proposalsThe backlog of helpers that might belong in the toolkit: six lines to file, processed as a group.
- App templatesOne runnable skeleton per app shape and which to pick: react-router-ssr, vite-spa, next.
- PipelinesThe repo's generated-output pipelines and what each produces.
Foundry contract
The cross-app architecture contract: what the system is, the classes everything falls into, and the rules that bind every module- Contract indexThe tree's own map: what each layer holds and where a question goes.
- CharterWhy the contract exists and what it must achieve.
- System classesThe kinds of thing a system can be, and what each owes the others.
- Contract do-notsThe banned moves, in one place.
- PlacementWhere a new rule, doc, or decision goes in this tree.
- Contract changelogWhat changed in the contract and when.
Contract canon
How the system works, subsystem by subsystem: runner, identity, jobs, dispatch, storage, caching, observability, credits, deployment- Contract canon indexThe sixteen subsystem docs and how they relate.
- The concerns, and where each one stands> Evidence: 14 file:line witnesses as of 2026-08-18.
- The runner and the payload> Evidence: 16 file:line witnesses as of 2026-08-18.
- Identity and tenancy> Evidence: 10 file:line witnesses as of 2026-08-18.
- Jobs and state> Evidence: 9 file:line witnesses as of 2026-08-18.
- Dispatch and workers> Evidence: 22 file:line witnesses as of 2026-08-18.
- Storage and persistence> Evidence: 3 file:line witnesses as of 2026-08-18.
- Caching> Evidence: 2 file:line witnesses as of 2026-08-18.
- Observability> Evidence: 5 file:line witnesses as of 2026-08-18.
- Usage and credits> Evidence: 2 file:line witnesses as of 2026-08-18.
- Configuration and secrets> Evidence: 3 file:line witnesses as of 2026-08-18.
- Human in the loop> Evidence: 0 file:line witnesses as of 2026-08-18.
- The capability manifest> Evidence: 1 file:line witnesses as of 2026-08-18.
- Deployment and environments> Evidence: 3 file:line witnesses as of 2026-08-18.
- Local development and debugging> Evidence: 0 file:line witnesses as of 2026-08-18.
- Graceful degradation, variants, and several versions at once> Evidence: 1 file:line witnesses as of 2026-08-18.
- Outputs and transforms> Evidence: 0 file:line witnesses as of 2026-08-18.
Wire contracts
The exact shapes on the wire: module surface, runner verbs, manifest, caller keys, usage events, conformance- Wire contracts indexThe binding shapes and what conformance means.
- Contract: per-module caller keys (option C)The minimum a module must meet when it issues its own long-lived caller credentials instead of…
- Contract: conformanceThe smoke suite a module runs against itself.
- Contract: the capability manifest and the field registryThe normative shape of GET /manifest and the shared vocabulary that requires and provides name…
- Contract: the module surfaceThe HTTP surface every Foundry module exposes.
- Contract: the runner's verbsThe interface between a module's runner and its payload, in both directions.
- Contract: the usage eventOne unit of spend, as a module records it.
Contract guides
Judgment calls the contract leaves open: service granularity, outputs as a transform, data ownership, machine identity- Contract guides indexThe judgment calls and how to make them.
- Guide: service granularityFew big services with capabilities added inside, or many small modules?
- Guide: outputs as a transformWhen a consumer wants a shape the worker does not naturally produce (M rows from N items, an…
- Guide: data ownership, stores, and where configuration livesWhich store holds which entity, which layer is the source of truth for it, who writes it, and where…
- Guide: machine identity, a multi-contender guidebookWho mints the credential an app presents to a module, and how the estate supports more than one…
Contract patterns
How to build, consume, deploy and upgrade a module, end to end- Contract patterns indexThe end-to-end walkthroughs.
- Building a moduleWhat a request for a new module brings along, in the order that keeps the build from debugging its…
- Consuming a module from an appWhat a request for "call module X from our app" brings along: identity, the tenant, the job…
- Deploying a moduleHow a module gets from a repo to something a caller can reach, on GCP first, with a Render variant…
- Upgrading services-api onto the contractThe first module is not greenfield: services-api runs today, does content generation for real…
- The identity recipeThe owner asked for "an auth blueprint + recipe" because every app has a different auth model and…
- Authoring an agentic moduleThe doc the owner says keeps getting rewritten in every app: how an agentic capability (a model in…
Contract instances
Each real system read through the contract: what conforms, what diverges, what migrates- Contract instances indexThe systems and their conformance state.
- enhancement-product (App V5)Covers the Python backend of App V5, on Render rather than GCP.
- extractionVersable's agentic scraping web server, per the owner.
- foundry-runner (the first module built against the contract)> As of 2026-08-18 23:40 IST, runner step 1 in progress.
- speedwayRe-cut of ../evidence/20260817-speedway-recon.md against the canon matrix, plus a Lapses section.
- versable-runnerCovers services-api, runner-service, and runner-service-dev, which are three Cloud Run services in…
- walmart-mvpRe-cut of ../evidence/20260817-walmart-recon.md against the canon matrix, plus a Lapses section.
Contract ADRs
The recorded decisions and why they hold- ADR indexEvery recorded decision, one line each.
- ADR-001: Standalone modules, one runner implementationStatus: accepted, 2026-08-17 (owner ruling, recorded in…
- ADR-002: App-to-module identity is a shared issuer on a JWKS seamStatus: accepted, 2026-08-17 (owner ruling: "let's do b, can have a blueprint for a in the…
- ADR-003: Composability supported from the start, the composer not builtStatus: accepted, 2026-08-17 (owner ruling, ../evidence/20260817-source-docs-skeptical-read.md §B)
- ADR-004: Confidence carries its source; self-report is default, not lock-inStatus: accepted, 2026-08-17 (owner ruling, ../evidence/20260817-source-docs-skeptical-read.md §C)
- ADR-005: speedway and walmart-mvp are witnesses, not migration targetsStatus: accepted, 2026-08-17 (owner answer 8)
- ADR-006: A module is one capability by default, and the wire field is `input`Status: accepted, 2026-08-18 (owner nod on two defaults proposed after the class-model review)