# Component specs One section for each component in the design language. Write any framework's version of a component from its section. [`components.html`](components.html) shows each state as static markup, and [`tokens.css`](tokens.css) holds the values. The [decisions](decisions.md) record why each choice was made. Each section has these parts: anatomy, states, then Do and Don't, keyboard and screen reader, motion, and forced colors. A part that does not apply says "None", with the reason. Do names the choice to make, and Don't names the mistake to avoid; neither repeats the spec. A section may add tokens and parts of its own. Sizes are in CSS pixels at the default 16px root font size. Type, spacing, and control sizes are set in rem (pixels ÷ 16), so they follow the reader's font-size setting; borders, focus rings, and shadows stay in pixels. A percentage mix means `color-mix(in srgb, A n%, B)`. ## Layers | Layer | What it holds | A new project | | --- | --- | --- | | Core | Tokens, depth, controls and their states, focus, motion, accessibility, forced colors | Adopts it as is | | Identity | The terminal folio look: the `~/name` header, the project registry, mono display headings, `##` section marks, terminal plates, captures, and the mono section rail | Replaces it with its own | The identity layer reads only the identity tokens (`--color-project`, `--color-project-dark`, `--font-ui`, `--font-mono`) and the terminal tokens. A core component never depends on an identity component. ## Groups The sections follow the catalogue's purpose groups, in this order. Each component keeps its layer. | Group | Components | | --- | --- | | Actions | Button, quiet action | | Selection | Checkbox and radio, radio card group, switch, toggle button, segmented control | | Inputs | Text input and textarea, select, field wrapper, slider | | Feedback and status | Progress, score, badge, alert | | Containers and overlays | Surface and card, figure, dialog, drawer | | Navigation | Navigation list, section rail, find field, breadcrumbs, pager, tabs, skip link, keyboard key | | Code and examples | Code block | | Identity | Command plate, terminal capture, site header, page type and helpers | A control's **States** line names each interactive state it has. In `components.html` each control section lists the same states in `data-states`, and the Control states table shows them; a test checks the three agree. ## Rules for every control - **Sizes.** `sm`, `md`, and `lg` use `--control-sm`, `--control-md`, and `--control-lg` for height, with `--text-sm`, `--text-md`, and `--text-lg`. At tablet width (`max-width: 800px`) touch targets use `--control-lg`. - **Borders.** Every control keeps a 1px border, transparent unless its section says otherwise, so forced colors can draw an edge. - **Depth.** Each control takes its shadow from the [depth tiers](DESIGN.md#depth). - **Hover.** Hover fills apply only where the pointer can hover. Put every `:hover` rule that sets a background, shadow, border colour, or text colour in `@media (hover: hover)`, because a touch screen keeps `:hover` on the last element tapped. The pressed tint stays outside the query: it shows only while a finger is down. - **Press.** Only a button has a pressed state; see [Button](#button). A [quiet action](#quiet-action) tints on press without sinking. Other controls have no `:active` treatment: they show their latched state as their section says. - **Focus.** One ring for every role but fields: `outline: var(--focus-width) solid var(--color-focus); outline-offset: var(--focus-offset)` (2px, 3px), with no halo or glow. `--color-focus` is the accent (`--color-accent`), which reaches 3:1 on `--color-bg`, `--color-surface`, and `--color-surface-raised` in both themes. It sits around primary, danger, and selected controls too. Do not give a role its own ring colour; where a variant must recolour the ring, set only `outline-color`. The ring is drawn over the control's own raise or sink shadow, which does not change. It goes on the visible part of a composite control: the switch track, the radio card, and the slider thumb. A dark plate (command plate, terminal capture) sets `--color-focus: var(--color-project-dark)`, the dark-theme accent, which reaches 3:1 on the plate in both page themes. In forced colors, a control that opts out of adjustment (a checked box, the switch track, a pressed segmented option) sets `outline-color: CanvasText`. Inside a scrolling or clipping parent, the ring is inset (`outline-offset: calc(var(--focus-width) * -1)`), and a comment names the reason. Only `:focus-visible` shows a ring; pointer hover never does. - **Field focus.** Fields (input, select, textarea, and the search wrapper) draw no ring. On `:focus-visible` (the search wrapper uses `:has(input:focus-visible)`) the 1px edge turns `--color-accent`, and `--shadow-field-focus` (`inset 0 0 0 2px`, the accent at 18% over transparent) draws a muted accent line inside it, with `outline: none`. The fill does not change in either theme. An invalid field keeps its `--color-error` edge while focused, and its inset line is `--shadow-field-focus-invalid` (`--color-error` at 18%). Forced colors drop the inset line, so a focused field there draws `outline: var(--focus-width) solid Highlight; outline-offset: -1px`. - **Disabled.** Opacity 0.58, `cursor: not-allowed`, and no hover or press. Buttons drop their shadow. Fields drop theirs and fill with the `--color-well` well (the grey well in light; the same as rest in dark). Other controls keep theirs. Use the native `disabled` attribute. A link styled as a button has no disabled state: use `