The visual law every Versable app follows
Thirteen traits, each with principles, presets, and cases worked from shipped code.
Start at doc 0#
00-overview.md is the entry point: the mental model, the
token layering, where each rule came from, and the consumer pin caveat that
decides whether a rule below is reachable in your app yet. Read it before
treating anything here as settled, then open the trait you were asked about.
The thirteen traits#
| Doc | Trait |
|---|---|
00-overview.md | overview and mental model, plus provenance and consumer pins |
01-foundations.md | foundations |
02-buttons-and-actions.md | buttons and actions, including the accessibility principle §A9 |
03-status-language.md | status language, the three small-tag species |
04-loading-and-states.md | loading, empty, and error states, including failure states §A11 |
05-cards-and-surfaces.md | cards, surfaces, and stat tiles |
06-tables.md | tables |
07-toolbars-and-filters.md | toolbars and filters |
08-navigation-and-shell.md | navigation and shell |
09-page-composition.md | page composition |
10-overlays.md | overlays, and the peek-modal-page decision tree |
11-motion.md | motion |
12-typography.md | typography: the ramp, roles, title sets, the ink ladder, mono, tracking, truncation, do-nots |
13-forms-and-fields.md | forms and fields: one field anatomy, widths as rhythm, sections, mode choosers, tables in a form, the three modes, validation voice, loading, presets, keyboard, do-nots; the SchemaForm canon |
Each trait doc carries §A principles, §B presets, §C worked use cases cited to
file:line.
How this layer relates to the other two#
The canon is law. It says what a surface should be and why. It does not say what props a component takes, and it never restates a component contract.
| You are asking | Read |
|---|---|
| what should this look like, and why | here |
| what props does this component take | ../../packages/ui/docs/ |
| I was asked for a screen, what does that bring along | ../app-patterns/ |
| which of these rules does a component already handle for me | ../app-patterns/12-primitives-and-rules.md |
Two things to know before you rely on a rule#
Check your pin. A rule written "as of kit 0.0.N" is unreachable in an app
pinned below N, and a caret on a 0.0.x version is a patch pin. The consumer
pins differ; 00-overview.md carries the current table.
Deviation is legitimate and never free. Owner ruling D1 lets a surface break the overlay tree when the break buys better and more consistent UX. What the ruling retired was silent discretion, not discretion. A surface that deviates records the reason in its own doc.
Section C renaming#
A canon doc's §C renames from "through Speedway" to "through the apps" in the same commit that adds its first non-speedway case. Lazy migration by owner ruling, no sweep.