Concepts
Concepts
Why interfaces are built the way they are: each concept follows one template, labels every claim about users with its source and strength, and links to the components that implement it.
The component pages tell you what to call. The concept pages tell you what to build and why, so a person or an AI agent can make the call that no prop table answers: how tall a first screen should be, where an action bar goes when the keyboard is open, when to hide detail.
How a concept page is built
Every concept uses the same nine parts in the same order.
| Part | What it holds |
|---|---|
| Definition and vocabulary | The terms, and what each means and does not mean. |
| Evidence | Claims about users, each with a source, a strength label and its scope. |
| The contract | The principles we derive. Kept apart from the evidence so a finding is never confused with a rule of thumb. |
| How the library implements it | Tokens, components and live demos. |
| Anti-patterns | What goes wrong, and the alternative. |
| Checklist | Things you can verify. |
| Prompt for your AI | A paste-in instruction that carries the contract into a coding agent. |
| Limits | What we do not know and the date of the last review. |
| References | Every source cited, with what it supports and what it does not. |
Writing a concept
Add site/src/content/docs/concepts/<id>.mdx with group: Concepts. Wrap each claim about users in <Claim strength="…" refs="…" scope="…">, close with <Limits reviewed="YYYY-MM-DD"> and <Refs ids="…">, and add any new source to site/src/data/evidence/references.json only after opening it and recording the wording you relied on. The rules are on How we use evidence; bun test packages/ui/tests/evidence-rules.test.ts checks them.
For AI agents
Each page is also plain markdown at /llms/concepts/<id>.txt, with its claims, scope, limits and references intact. The ca-ui-mcp server returns it with get_guide.
The backlog
Twenty concepts we plan to write, ordered by how often a coding agent gets them wrong when nothing tells it better. Each is written in full with the template above only after its sources are opened and recorded. Until a concept is written there is no page and no claim.
| # | Concept | Scope in one line |
|---|---|---|
| 1 | Viewport-complete UX | Written. The first screen, viewport units, safe areas, keyboard, reflow. |
| 2 | Targets and focus | Written. Target size, visible focus, focus not hidden, modal focus. |
| 3 | Motion that respects people | Written. Essential and non-essential motion, the reduced-motion setting. |
| 4 | Appeal is not usability | Written. What appeal ratings do and do not show. |
| 5 | Color is never the only signal | State, error and status carried by more than hue. |
| 6 | Contrast across themes | Text and outline contrast in light, dark and high-contrast, and in every preset. |
| 7 | Forms that finish | Labels, errors, autocomplete, input types and recovery from a mistake. |
| 8 | Empty, loading and error states | What a screen shows before, between and after data. |
| 9 | Progressive disclosure, honestly | What may be hidden and what must stay visible: prices, limits, frequent actions. |
| 10 | Navigation and orientation | Where am I, where can I go, how do I get back, on a phone and a desktop. |
| 11 | Dense data and tables | Scanning, alignment, sorting, row actions and mobile fallbacks. |
| 12 | Text that reads | Measure, line height, scale, truncation and what survives a long translation. |
| 13 | Internationalization in layout | Length growth, right-to-left, numbers, dates and currency. |
| 14 | Overlays and layers | Dialogs, popovers, tooltips and toasts: which one, and how they stack. |
| 15 | Touch, pointer and hover | Designing for coarse pointers without breaking the mouse, and no hover-only actions. |
| 16 | Performance as experience | Loading, layout shift, interaction latency and what the thresholds measure. |
| 17 | Offline and slow networks | What a screen does with no connection, and what it promises. |
| 18 | Trust and confirmation | Destructive actions, undo, confirmation wording and honest defaults. |
| 19 | Notifications and interruption | When to interrupt, how often and how to let people turn it off. |
| 20 | Adaptive and generated interfaces | Auditability, reversal and unwanted surprise when an interface changes itself. |