The visual law every Versable app follows
Thirteen visual traits plus three cross-cutting references (prop vocabulary, accessibility and microcopy), 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 traits and references#
The first fourteen rows are the visual traits (and the overview); docs 14, 15 and 16 are cross-cutting references the traits point at.
| 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 four small-label 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 |
14-prop-vocabulary.md | prop vocabulary: the six visual axes (color, tone, kind, variant, shade, size) and the shared SemanticColor type |
15-accessibility.md | cross-component accessibility: name precedence, validity and message association, live-region severity, inert |
16-microcopy.md | microcopy: the copy guide for titles, helper text, placeholders, alerts, toasts and destructive confirms |
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.