@lotics/ui 43.4.0 → 43.5.0

package/AGENTS.md

@@ -15,9 +15,10 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 | Doc | Read it for |
 |---|---|
 | [docs/catalog.md](./docs/catalog.md) | **The complete inventory** — Reach-by-role (each data role → the ONE canonical component) + every `@lotics/ui/<module>` entry point (incl. `@lotics/ui/vite`'s `loticsOptimizeDeps` + `loticsResolve()` — the pre-bundle list and the whole `resolve` block a custom-code app's `vite.config.ts` imports rather than hand-carries, dev-link included). Read before building any screen; reuse first. |
-| [docs/data_entry.md](./docs/data_entry.md) | Which editing pattern for which job — inline edit, fieldset forms, browser-autofill suppression (search controls only), find-or-create (`Combobox`), line items, handoffs, phased records, billing, tags, dispositions, attachments (`InlineFiles` for a record ROW — list + one CTA, `multiple` decides add-vs-replace; the `FilesEditor` COMPOUND for a whole section — root owns selection/gallery/confirm, you compose the bar, a HOST verb reads `useFilesEditorSelection` — plus the three-way file INTAKE: CTA + `FileDropTarget` + `usePasteFiles`), stage gates, whether a multiline value keeps its fixed reserve or `autoGrow`s (who decides the length — the field, or whoever is typing), the commit-on-blur vs action-press ordering law (the kit gates the press — `pending_commits`). |
+| [docs/data_entry.md](./docs/data_entry.md) | **a picker over a select field keeps the field's colours** (`optionPicker` — the hand-rolled `map` to `{value,label}` drops `color`, so a value reads coloured in a register and grey in the editor); Which editing pattern for which job — inline edit, fieldset forms, browser-autofill suppression (search controls only), find-or-create (`Combobox`), line items, handoffs, phased records, billing, tags, dispositions, attachments (`InlineFiles` for a record ROW — list + one CTA, `multiple` decides add-vs-replace; the `FilesEditor` COMPOUND for a whole section — root owns selection/gallery/confirm, you compose the bar, a HOST verb reads `useFilesEditorSelection` — plus the three-way file INTAKE: CTA + `FileDropTarget` + `usePasteFiles`), stage gates, whether a multiline value keeps its fixed reserve or `autoGrow`s (who decides the length — the field, or whoever is typing), the commit-on-blur vs action-press ordering law (the kit gates the press — `pending_commits`). |
 | [docs/ai_patterns.md](./docs/ai_patterns.md) | AI acts, the human stays in charge — composer, live run feed (`AgentRun`), the one law's split — it turns on WHO supplied the values (machine → a gate: a diff when something is being replaced, a full editable preview when records are being created from a document; human-typed → save-direct + the `ResultHeader` receipt), findings, provenance, confidence; **after the run** — a stored record that fills up from several writers (a person, a chat agent, an extraction, an automation) and remembers none of them: an unwritten value must not render like a written one, a machine's prose and a person's must not share a treatment, model markdown goes in `variant="embedded"`, and the read path must project every field the write paths set; the UI half of the SDK's [ai doc](../app-sdk/docs/ai.md), the whole run in a dialog (`AgentRunScope`/`AgentRunPane`/`AgentRunActions` — a parked question REPLACES the feed, actions in the footer, **Stop** while streaming), **stopping** (`cancel` stops the run, `abort` only stops listening — so closing a dialog must `cancel` or it keeps billing); **review surfaces compose from atoms** — `DiffValue` (a changed value, droppable in any cell/row/total), `DiffMark` (what happened to the row — ONE circular disc, every surface), `useChangeSet` (accept/reject/undo bookkeeping, no layout) — see [MIGRATION.md](./MIGRATION.md) for the `ChangeReview` family they replace |
-| [docs/composition.md](./docs/composition.md) | The design-language contract — canvas + content column, heading altitude (incl. eyebrow vs group lead — a label is one or the other), banded cards, register vs inset rows (incl. the register laws a row centres its cells by: every cell a FIXED height, a pressable cell on the shared hover token, a column sized by what it carries), the button ladder and **what underlined text may mean** (it GOES somewhere or REVEALS something — never mutates; blue leaves the surface, muted stays on it, and the one in-prose disclosure exception is scoped there), master-detail `Drawer` on a LIST screen vs a child collection's row EXPANDING inside a record, view controls, RECORD EXTENT (one page, sections scrolled to and never routed to), color discipline, typography, whitespace, and how to TEST an overlay component (a `Popover`-backed surface never mounts under jsdom). |
+| [docs/composition.md](./docs/composition.md) | The design-language contract — canvas + content column, heading altitude (incl. eyebrow vs group lead — a label is one or the other), banded cards, register vs inset rows (incl. the register laws a row centres its cells by: every cell a FIXED height, a pressable cell on the shared hover token, a column sized by what it carries), the button ladder and **what underlined text may mean** (it GOES somewhere or REVEALS something — never mutates; blue leaves the surface, muted stays on it, and the one in-prose disclosure exception is scoped there), master-detail `Drawer` on a LIST screen vs a child collection's row EXPANDING inside a record, view controls, RECORD EXTENT (one page, sections scrolled to and never routed to), **the register's rhythm** (no hairline between rows — their own height and the hover wash separate them; the register's one line is the band capping the columns, because that is the break whitespace cannot state. Density is `TableRow`'s `minHeight`, never a mode), **a register that TRIAGES** (`TableGroup` — titled bands ordered by what needs the reader now, grouped by what implies a different ACTION rather than by a category already in a column), **the register's own craft** (a column header treated as CHROME a step lighter than row metadata, sentence case in the table header too, and a supporting line one RUNG BELOW the line it supports rather than a fixed size), **identity marks** (a mark that looks the same on every row carries nothing — `Avatar` derives its hue from the name and takes circle/square for person vs organization; the palette is ordered by contrast, not spectrum, and never paints a person red or amber), **where the accent goes** ("which of these" — a selected row, an active filter; never DATA and never the focus ring, while a page-scale position marker like an active TAB takes `primary`, the ink the kit already spends on "this is on"; and selection must not share a wash with hover), **theming is an app-level ESCAPE HATCH, not a product surface** (`applyLoticsTheme({ … })` once at boot, before `mount`, writing the `--lotics-*` roles on the document root; nothing in the platform writes a theme, and `apps.theme.color` is the launcher icon only — the five `var()` roles plus the three font rungs ARE the whole mechanism, and wrapping a component cannot replace them because RN-Web writes `fontFamily` per element and background/border do not inherit), color discipline, **typography** (the ramp is DATA in `type_ramp`, one table both platforms derive from; leading and tracking are baked per rung and a hand-set `letterSpacing` is always a second copy of the curve), whitespace, and how to TEST an overlay component (a `Popover`-backed surface never mounts under jsdom). |
+| [docs/reviewing.md](./docs/reviewing.md) | **Reviewing a screen you built** — the other docs say what good looks like; this one says how to find out whether you achieved it, because "it looks fine" is the same claim as "it should work" made with the same evidence. Measure, never eyeball: render it, extract computed values, let the table show the defect. Two GATES that outrank every treatment question (**SUBTRACT** — what question does this element answer, and count FACTS not elements; **RIGHT CONTROL** — name the species before treating it), then 10 probes each naming what to COLLECT and the SIGNATURE in the numbers: type inventory (range, singletons, the label/value shrink war), ground+border+radius across siblings, what each RULE separates, gap RATIOS, the state diff (paint may change, geometry may not), alignment drift (incl. a centred child that moves while its container measures identical), the surface walk (open it, press it, read the settled string), the DATA probe (what is really in the table — incl. grepping rendered text for internal ids), the ABSENCE pass that catches "bland", and microcopy. Plus the extraction snippets, what measurement cannot see, and how to act on a finding (fix the CLASS, and never resolve one with "the docs say X"). |
 | [docs/testing.md](./docs/testing.md) | Driving the kit in a browser — the three anatomies where the a11y tree says one thing and a driver must do another: a `PressDoor` row whose named button always intercepts pointer events (by design), portalled overlays that render at the top of the DOM, and custom pointer drag that `dragTo` cannot move. |
 | [docs/templates.md](./docs/templates.md) | The map of `examples/tpl_*.tsx` — what shape each template solves and which to start from (copy + adapt, never import) — plus the record-surface composition rules (pipeline order, static shape, decision budget) and the ACTIVITY shape — a communications feed where the row's label is the GIST and the body varies by medium, one anatomy rather than a row type per kind. |
 

package/MIGRATION.md

@@ -4,6 +4,99 @@ Breaking changes, newest first — normally per major, plus the rare minor that
 anyway (recorded under its exact version). The current contract lives in `AGENTS.md` + `docs/`;
 this file exists only to move an app from one release to the next.
 
+## 43.5.0 — registers, type and theming all change appearance
+
+No API is removed and nothing throws, but four DEFAULTS moved, so every register and every avatar
+in your app renders differently on upgrade. Each is reversible at the call site if you need the
+old look while you catch up.
+
+**Table column headers are sentence case, not all-caps** — and one ink step lighter
+(`zinc-500`). `Table` and `SortHeader` were uppercasing every column label, which the heading ramp
+bans and names the #1 templated tell. The ink step is not cosmetic and cannot be skipped: at
+`muted` the header matched a row's supporting line in size, weight AND colour, so dropping the
+case alone leaves it reading as a stray label rather than as the band naming the columns.
+
+**Row separators are lighter than the header rule.** The band capping a table keeps
+`colors.border`; the hairlines between rows are `zinc-100`. Every rule used to be `border`, which
+is what makes a register read as a grid instead of a list with a heading.
+
+**`Avatar` grounds its initials in a hue derived from `name`**, not `colors.accent`. A register of
+people used to be N identical discs — the largest, most colourful element in the row carrying no
+information. Pin the old look on one avatar with `style={{ backgroundColor: colors.accent }}`.
+`Avatar` also gained `shape="circle" | "square"`; an organization takes `square`, and `circle`
+stays the default, so existing call sites are unchanged.
+
+**`colors.accent_wash` defaults to blue-50, not zinc-100**, so a SELECTED row carries the accent.
+It had defaulted to a grey while `accent` defaulted to blue-600 — one token pair disagreeing with
+itself, which left every unthemed app with a colourless "you are here". Related: selection and
+hover no longer share a wash (hover is `zinc-50`), because the row whose record was open looked
+exactly like the row under the pointer.
+
+**`COMPACT_THUMBNAIL_SIZE` is 40, not 32.** The row-riding file tile follows the row height above
+— at 32 it read as a stray glyph with 40px of air around it. It is also the threshold between a
+badge and a card, so a tile at 40 still renders a document as a bare badge rather than printing the
+filename inside itself. Nothing to change unless you passed a literal size to `FileThumbnail` in a
+row; take the constant instead.
+
+**`LoticsThemeProvider` is replaced by `applyLoticsTheme`.** Theming is an app-level escape hatch
+— an app declares one identity at boot and never changes it — so it is a function called before
+`mount` rather than a component wrapping the tree:
+
+```diff
+-import { LoticsThemeProvider } from "@lotics/ui/theme";
++import { applyLoticsTheme } from "@lotics/ui/theme";
++
++applyLoticsTheme(MY_THEME);
+ mount(
+-  <LoticsThemeProvider {...MY_THEME}>
+-    <LoticsLocaleProvider locale={vi}><PortalHost><App /></PortalHost></LoticsLocaleProvider>
+-  </LoticsThemeProvider>,
++  <LoticsLocaleProvider locale={vi}><PortalHost><App /></PortalHost></LoticsLocaleProvider>,
+ );
+```
+
+Same roles, same additive semantics, same variables. It writes them to the document root exactly
+as the provider did, so portalled surfaces (`Drawer`, `Dialog`, `Popover`) keep the theme — and
+called before `mount` the variables are in place for the first paint, where the provider's effect
+ran after one. `useLoticsTheme`, `LoticsThemeContext` and `DEFAULT_ACCENT` are gone with it; they
+had no callers. `THEME_VARS` and the `LoticsTheme` type are unchanged.
+
+**A register has no rule between its rows.** `Table` drops the hairline that used to separate them
+— rows are separated by their own height (72px, up from 52) and the hover wash, and the one line
+left is the band capping the columns. Nothing to change and no prop to set; a surface that needs
+density sets `minHeight` on the row. There is deliberately no way to ask for the rules back: a
+table of VALUES rather than of objects is `Matrix` (a numeric grid) or `DataGrid` (a compact one).
+
+**Text is airier, and the ramp now reaches native.** The rungs that carry running text moved to
+prose leading — `sm` 14/24 and `md` 16/26, about 4px more line box each — so a note typed into a
+field, the same note rendered as markdown, and a label beside them all sit at one rhythm. Tracking
+is negative at every rung and steepens with size. Nothing to change, but LAYOUT SHIFTS: a
+single line is taller even when it does not wrap, so hand-fixed heights around text may need a
+look. React Native apps see the larger change, because native had been running a stale ramp of its
+own with a flat tracking value — it now derives from the same table as web.
+
+**`index.css` no longer defines `--font-size-*`.** The twelve size/line-height variables were a
+third copy of the ramp and disagreed with the real one at every rung (`--font-size-sm-line-height`
+handed out 20px where `Text` renders 24). If you referenced them on a hand-rolled DOM node, set
+`data-text-size="sm"` on the element instead: `text.css` matches that attribute anywhere, and it
+applies size, leading and tracking as one rung. The `--color-*`, `--input-*` and `--font-weight-*`
+variables are unchanged.
+
+**Column headers in `DataGrid` are sentence case too.** The 43.5.0 header work reached `Table`
+and `SortHeader` first; `DataGrid` kept `text-transform: uppercase` and `+0.3` tracking, which is
+the last positive tracking in the kit. Both surfaces now label their columns identically.
+
+**A file drop target lights up in the ACCENT, not a fixed blue.** `FileDropzone` and
+`FileDropTarget` read `colors.accent` / `colors.accent_wash` for their drag state, so a themed app
+no longer flashes brand blue across the most conspicuous moment on the screen. Unthemed, the wash
+is unchanged and the ring moves one step darker (blue-500 → blue-600).
+
+Additive in the same release, nothing to change: `TableGroup` (a titled band of rows inside a
+`Table`), `optionPicker`
+(spread a select field's options into any picker WITH their colours), `FileRows`' `press`
+prop (`"open"` — no gallery), `Avatar`'s `shape` prop, and the `avatar_tone` /
+`avatar_props` / `type_ramp` modules.
+
 ## 43.3.0 — a `bare` inline field sits on the column, and Enter finishes a one-line one
 
 Two fixes to `Inline*`, both of them behaviour a caller cannot see in a prop name.

package/docs/catalog.md

@@ -425,11 +425,41 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   whose text darkens the instant it is focused reads as the text MOVING (at 14px a darkness
   change re-weights every stroke's antialiasing), which is a bug no box measurement can
   see. Hand-rolling a raw input means taking this style, not just its font size.
+- **`font_family`** — the three Inter stacks (`fontFamilyRegular` / `fontFamilyMedium` /
+  `fontFamilySemiBold`). Weight in this kit is a FAMILY, not a `font-weight` axis: each rung is
+  a separate file, which is why `Text`'s `weight` prop swaps the family rather than a number.
+  Take these only when styling something `Text` cannot wrap; on web they resolve through
+  `--lotics-font-*` so a theme reaches them.
+- **`display_font`** — `fontFamilyDisplay`, the face `<Text family="display">` renders in, and
+  the ONLY themeable typeface. There is deliberately no body-face role: body weight is three
+  coupled families, `text.css` hand-tunes tracking for Inter's glyphs and for Vietnamese
+  diacritics at 12px, and `font-feature-settings: "cv11","ss01","ss03"` are Inter's own
+  alternates. A variable for the body face would not fail loudly — it would render every screen
+  subtly miscalibrated. Changing the body face is a kit change, done once for everybody.
+- **`type_ramp`** — the type ramp as DATA: `TYPE_RAMP_MOBILE` / `TYPE_RAMP_DESKTOP` (size +
+  leading per rung, the 768px breakpoint between them), `TYPE_TRACKING` (em per rung, negative
+  throughout and steepening as the type grows), `TypeRung` / `TypeRungName` (`TextSize` IS this
+  set), and `trackingPx` for platforms with no em unit. `Text` renders through two mechanisms —
+  a `data-text-size` attribute matched by `text.css` on web, a `StyleSheet` on native — and this
+  is what both derive from, so the two cannot disagree. Read it to learn what a rung IS; you
+  almost never need to import it, because `Text size=` is the way to ask for a rung. Reach for
+  it only when styling something `Text` cannot wrap (a raw `TextInput`, a canvas, a chart axis)
+  and the result has to sit at a rung exactly.
 
 ### Theming, locale & tokens
 
-- **`theme`** — `LoticsThemeProvider` / `useLoticsTheme` + `DEFAULT_ACCENT`: the single
-  brand accent (OKLCH blue by default) that chart fills, hero CTAs, and focus rings read.
+- **`theme`** — `applyLoticsTheme(theme)` + `THEME_VARS`: THE ESCAPE HATCH by which an app
+  carries someone else's brand. Call it ONCE at boot, before `mount`. Six optional roles —
+  `accent`, `primary`, `background`, `border`, `bodyFont`, `displayFont` — and it is ADDITIVE, so
+  setting one leaves every other at the kit's value. It writes the `--lotics-*` custom properties
+  on the DOCUMENT ROOT, which is what reaches surfaces react-native-web mounts on `document.body`
+  (`Drawer`, `Dialog`, `Popover`); a theme scoped to a React subtree reaches the register and not
+  the drawer opened from it. Prefer it over declaring the variables in your own stylesheet: the
+  selection wash is DERIVED (the accent at 7%) and one `bodyFont` has to reach all three weight
+  rungs, and both fail quietly by hand. No-op on native, where `colors` is a literal table.
+  **Theming is not a product surface** — nothing in the platform writes one, and `apps.theme.color`
+  is the launcher icon's colour only. → [composition.md](./composition.md)
+  §"Theming is an app-level ESCAPE HATCH".
 - **`locale`** — `LoticsLocaleProvider` / `useLoticsLocale` + the shipped `en` (default) and
   `vi` packs. Set the language ONCE at the root; wired components resolve **prop → provider
   locale → English default**. Each pack also carries a **`bcp47`** tag (`en`→`en-US`,
@@ -437,7 +467,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   pure core) so the segmented field's part ORDER (dd/MM vs MM/dd), the picker calendar's
   weekday/month names, and `formatDate` display all follow the provider with no per-instance
   `locale` prop — an explicit `locale` still overrides. **Limitation:** the calendar/gantt
-  views and the comment labels are not yet provider-wired — pass their `labels` props directly.
+  views and the comment labels do not read the provider — pass their `labels` props directly.
 - **`colors`** — the palette + `withAlpha`, `solid`, `tint`, `ramp`, `ColorName`,
   `isColorName`, `asColorName` (coerce a stored option/status token to a `ColorName`,
   neutral fallback).
@@ -470,8 +500,11 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`fonts.css`** — the Inter sheet (400/500/600, served by absolute URL so it resolves on
   every origin an app runs from); the app entry imports it ONCE or every `Text` falls back
   to system fonts.
-- **`index.css`** — CSS custom properties (`--font-size-*`, `--input-font-size`, …) for
-  hand-rolled DOM surfaces; components don't require it.
+- **`index.css`** — CSS custom properties (the `--color-*` palette, `--input-font-size` /
+  `--input-line-height`, `--font-weight-*`) for hand-rolled DOM surfaces; components don't
+  require it. It carries no type ramp: for SIZE on a raw DOM node, set
+  `data-text-size="sm"` — `text.css` matches that attribute on any element and applies the
+  rung's size, leading AND tracking together, which loose variables cannot.
 
 ### Icons & identity
 
@@ -486,9 +519,17 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `themeColor` palette token (unknown → neutral zinc) holding any Lucide icon by runtime
   name via `DynamicIcon`; `size` sm|md. One render wherever an app shows — launcher, list,
   picker, settings.
-- **`avatar`** — `Avatar`: image-or-initial person avatar (`source`/`name`/`size` — a rung,
-  see above; `announce` when standalone — decorative by default because the name text usually
-  sits beside it).
+- **`avatar`** — `Avatar`: image-or-initial identity mark (`source`/`name`/`size` — a rung,
+  see above; `shape` `circle` (a person, default) or `square` (an organization); `announce` when
+  standalone — decorative by default because the name text usually sits beside it). The initials
+  ground is DERIVED from `name`, not passed — see `avatar_tone`.
+- **`avatar_props`** — `AvatarProps` + `avatarShapeStyle`: the prop contract BOTH `avatar.tsx`
+  and `avatar.web.tsx` implement. It lives in a third module because only one of them is ever
+  compiled — `tsc` resolves `./avatar` to the native file while every browser loads the web one,
+  so a prop declared on one side typechecks everywhere and silently does nothing in the browser.
+- **`avatar_tone`** — `avatarTone(name)`: the initials ground, one stable hue per name, from a
+  contrast-ordered palette that excludes `red` and `amber` (a person is not a warning). Pure and
+  never stored, so one person is one colour on every screen. See composition.md §Identity marks.
 - **`avatar_size`** — the shared avatar scale: `AvatarSize` (`sm|md|lg|xl`), `AVATAR_PX`,
   `AVATAR_TEXT`, `avatarInitials`. Import `AVATAR_PX` when a sibling box must match an
   avatar's pixels (a stack's overlap, a dashed placeholder) so the two cannot drift.
@@ -505,7 +546,10 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 ### Layout & surfaces
 
 - **`card`** — `Card`, `CardHeader`, `CardHeaderTitle` (+ `info` ⓘ popover),
-  `CardHeaderMeta`, `CardBody`, `CardFooter`.
+  `CardHeaderMeta`, `CardBody`, `CardFooter`. A card separates from the canvas by its own border
+  and shadow, never by a tinted background, and it is a BAND on a page rather than a box around
+  every group — nesting one inside another is how a screen ends up reading as boxes all the way
+  down. → [composition.md](./composition.md) §"Cards — banded and composable".
 - **`inset`** — `Inset`: a tinted, recessed content surface (zinc-50 fill, 10 radius, 14
   pad, 12 gap) — the "well" INSIDE a Card/Section for a grouped sub-form, an inline fill
   editor, or a nested block. **NOT a `Callout`:** a Callout is a status BAND (and
@@ -541,7 +585,11 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`stack`** — `Stack`: gap-spaced row/column; `useSeparator` inserts `Separator`s between
   children.
 - **`spacer`** — `Spacer` + `SpacerSize` (the fixed size scale).
-- **`divider`** — `Divider`: the bare hairline.
+- **`divider`** — `Divider`: the bare hairline. **Ask what it SEPARATES before reaching for
+  it.** A line between two like things (row from row, item from item) says what the space
+  between them already says, and a register full of them reads as a spreadsheet; a line under a
+  column band or above a total separates CHROME from CONTENT, which whitespace cannot say. →
+  [composition.md](./composition.md) §"The register's rhythm".
 - **`separator`** — `Separator`: a `Divider` pre-wrapped in vertical padding (`padding:
   SpacerSize`, default 8) — the between-groups rule WITH breathing room, what `Stack
   useSeparator` inserts and what menus/popovers put between option groups.
@@ -565,12 +613,20 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   genuinely cannot use it — one with a rail, a side panel, or a scroller it must hold a ref to —
   still lands on the same edge by importing that token. It OWNS its `ScrollView` and exposes no
   scroll props, which is the real limit on adoption.
-- **`accordion`** — `Accordion` + `AccordionHeader`/`AccordionTitle`/`AccordionMeta`:
+- **`accordion`** — collapsible section rows, and the commonest piece of wrong-ALTITUDE
+  furniture: a record's sections are scrolled to, never folded away, so an accordion inside one
+  hides content behind a press that the page's own scroll already reaches. It earns its place
+  where the folded content is genuinely optional (a long log, an advanced group) and the reader
+  can finish their task without ever opening it. → [composition.md](./composition.md)
+  §"Canvas & content column". `Accordion` + `AccordionHeader`/`AccordionTitle`/`AccordionMeta`:
   expandable section rows.
 - **`tabs`** — `Tabs`: switch between content sections; WAI-ARIA tablist + roving tabindex;
   each `TabOption` takes an optional `status` `ColorName` → a small attention dot before its
   label, for a tab whose area needs work.
-- **`segmented_control`** — `SegmentedControl`: the exclusive small-set switch.
+- **`segmented_control`** — `SegmentedControl`: the exclusive small-set switch. Picking between
+  this, `ChipGroup`, `RadioPicker`, `Select` and `Tabs` is decided by OPTION COUNT and by
+  whether the choice filters a view or sets a value — not by taste. →
+  [data_entry.md](./data_entry.md) §"Choosing a CHOICE control".
 - **`danger_zone`** — `DangerZone`: the destructive section — a soft danger-tinted frame
   (the kit's `tint`/`solid`, never raw hex) + a danger heading + a description + a
   destructive action slot (children, e.g. a `danger` Button); sits APART at the bottom of a
@@ -729,6 +785,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   surface. **NOT for a type / category / attribute / count — that's inline `Text`, never a Badge**
   (see composition.md "Badge is for status only"). A bare `<Badge>` is `dot`.
 - **`status_badge`** — `StatusBadge`: an enabled/disabled pulse badge (`enabled` + `label`).
+- **`option_picker`** — `optionPicker(options, { variant? })`: spread into any picker (`InlineSelect`/`Select`/`OptionList`/`Combobox`) to feed a select field's options in WITH their configured colours. Supplies `options` + `renderOptionContent` together — the hand-written `map` to `{ value, label }` drops `color` silently, so an edited value renders greyer than the same value in a register. → data_entry.md.
 - **`option_badge`** — `OptionBadge`: a select value as its configured colored badge.
 - **`callout`** — `Callout`, `CalloutTitle`, `CalloutText`, `CalloutActions` (`tone`
   info|success|warning|error|neutral): inline status band — a MESSAGE (`warning`/`error`
@@ -746,7 +803,10 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   flow (a form that won't save) use `Callout tone="error"`; this is for a region with no content
   to show, where a tinted strip leaves the area collapsed.
 - **`completion_state`** — `CompletionState`: the "all done" terminal state.
-- **`skeleton`** — `Skeleton`: loading placeholder blocks.
+- **`skeleton`** — `Skeleton`: loading placeholder blocks. **Mirror the layout that is
+  arriving** — same row count, same column widths, same heights. A skeleton of a different
+  shape makes the content jump when it lands, which is more disruptive than an empty box
+  would have been. First of the four region states; the other three are under `error_state`.
 - **`loading`** — `Loading`: the centered indeterminate loading state (composes
   `DotsIndicator`).
 - **`activity_indicator`** — `ActivityIndicator`: the bare spinner.
@@ -797,12 +857,21 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`member_select`** — `MemberSelect` + `MEMBER_UNASSIGNED`: the member picker (a `Select`
   of `MemberChip` options; `unassignedLabel` prepends the unassigned option).
 - **`radio_picker`** — `RadioPicker`: labelled radio group for a small visible single
-  choice.
-- **`chip_group`** — `ChipGroup`: pill single-select over a small visible set.
-- **`checkbox`** — `Checkbox`: the bare square check control.
+  choice. → `data_entry.md` §"Choosing a CHOICE control" — and check the states really ARE
+  exclusive: independent capabilities that happen to be exclusive today bake today's
+  combinations into the type.
+- **`chip_group`** — `ChipGroup`: pill single-select over a small visible set. → `data_entry.md`
+  §"Choosing a CHOICE control" for which control the count and the job call for.
+- **`checkbox`** — `Checkbox`: the bare square check control. Bare means UNLABELLED — reach for
+  `CheckboxInput` unless something else already names it (a table's select-all, a row's
+  leading slot). A square means CHOSEN; a ring means DONE, and spending the wrong one teaches a
+  reader that a ticked pick-list is work already carried out. → AGENTS.md, Iron rules.
 - **`checkbox_input`** — `CheckboxInput`: checkbox + label as one labelled control.
-- **`switch`** — `Switch`: the bare toggle (a cell/toolbar boolean).
-- **`counter`** — `Counter`: increment/decrement numeric stepper (filter facet).
+- **`switch`** — `Switch`: the bare toggle (a cell/toolbar boolean). A boolean IS a switch —
+  not a two-option select, not a popover holding one checkbox — and it commits on flip, so it
+  belongs only where there is nothing to save.
+- **`counter`** — `Counter`: increment/decrement numeric stepper (filter facet). For a value a
+  person TYPES rather than nudges, `NumberInput`; stepping to 47 is not an input method.
 - **`slider`** — `Slider` + `rangeSummary`: drag a continuous number along a track. ONE thumb
   by default (a volume, a threshold); `range` turns on the second and the value becomes
   `[low, high]` (a price band, a filter facet). `labels={false}` when the caller prints the
@@ -1191,7 +1260,9 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 
 ### Lists, tables & registers
 
-- **`list`** — `List`: children separated by hairline `Divider`s.
+- **`list`** — `List`: children separated by hairline `Divider`s. That default is right for a
+  short set of unlike items (a menu, a settings group) and wrong for a long run of like ones —
+  there, the rules are the noise and `Stack` with a gap reads calmer. → `divider` above.
 - **`list_item`** — `ListItem`: the plain list row. A pressable row with a `right` slot
   presses BESIDE it, never around it: the slot holds a control, and a button may not contain
   one — `<button>` inside `<button>` is invalid HTML and buries a second tab stop and name
@@ -1239,6 +1310,8 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   position (a group band, a totals line) and the gutter stays blank so the cells beside it stay
   in line. A position is NEVER an identity: sort or filter and row 12 is a different record —
   a stable handle is a column, and it leads the cells. Worked screen: `tpl_item_list`.
+- **`table`** rhythm — rows are separated by their own height and the hover wash, never by a hairline; the register's one line is the band capping the columns. 72px rows, overridable per row with `TableRow`'s `minHeight` when a surface genuinely needs density. There is no `spacing` prop: a table of VALUES rather than of objects is a different component (`Matrix`, `DataGrid`). → [composition.md](./composition.md) §"The register's rhythm".
+- **`table` › `TableGroup`** — a titled BAND of rows inside a `Table` (`label`, `count?`, `color?` for a single valence dot). Turns a register that presents records into one that triages them: group by what implies a different ACTION, order the bands by what needs the reader now, and let air rather than a rule separate them. → [composition.md](./composition.md) §"A register that TRIAGES".
 - **`sort_header`** — `SortHeader` + `SortState`/`SortDir` + `cycleSort` + `sortBy` +
   `SortHeaderLabels`: the sortable column header and the sort-state helpers `Table`/
   `DataGrid` consumers drive.
@@ -1417,17 +1490,39 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 
 ### Numbers & charts
 
+**These are where a work screen gets its visual interest, and it is the only kind that survives
+contact with a real dataset.** Software with no photography has to find its imagery in the data —
+a figure at display size, a delta's colour, a line's shape, a bar's proportion, digits aligning
+down a column. Each of these is information first, so none of it is the decoration that gets cut
+in review. A screen reported as flat or boring is usually a screen with numbers in it rendered as
+sentences. → [composition.md](./composition.md) §"Character comes from the DATA".
+
+Two failure modes to hold against them. A figure nobody compares to anything is not a metric — it
+is a number with a large font, and the size promises a significance it cannot deliver. And a
+delta, ring or bar with no comparator states a relationship that does not exist; SKIP the
+component rather than showing it at zero.
+
 - **`kpi_card`** — `KPICard`: one headline metric in a card (trend chip slot, sub-caption,
-  ⓘ definition).
-- **`kpi_strip`** — `KPIStrip`: the boxed dashboard stat band.
+  ⓘ definition). The card is what makes it a KPI rather than a number: it holds the definition
+  (ⓘ), so the reader can find out what "on-time %" counts without leaving the screen.
+- **`kpi_strip`** — `KPIStrip`: the boxed dashboard stat band. Every item has to answer a
+  question the surface below it cannot — a strip restating totals the table already carries is
+  the trim test failing, and it costs the reader a pass over the screen to discover that.
 - **`metric`** — `Metric`: a bare headline figure (`format`
-  currency|number|percentage|none, `tone`, `size` sm|md|lg|hero).
-- **`trend_chip`** — `TrendChip`: the signed ±% delta chip.
+  currency|number|percentage|none, `tone`, `size` sm|md|lg|hero). Bare = no card, no label of its
+  own, so whatever contains it has to name it. Always `tabular` — it is set that way here, and it
+  is why a column of figures aligns instead of jittering on proportional digits. It sets no
+  tracking of its own; the rung's tracking comes from `Text`.
+- **`trend_chip`** — `TrendChip`: the signed ±% delta chip. Reads as a delta only next to the
+  value it moved from, so put it beside the figure, never in its own column.
 - **`trend_footer`** — `TrendFooter`: the "Up X% vs last period" caption under a chart card
   — signed `value` (0 = flat), `periodLabel`, optional `detail`; `goodDirection="down"`
   flips green/red for metrics where down is good; SKIP it when there's no comparator.
   Direction words via the `trendFooter` locale slice; goes in `SectionCard footer`.
-- **`sparkline`** — `Sparkline`: the inline mini trend line.
+- **`sparkline`** — `Sparkline`: the inline mini trend line. Sized for a ROW or a card corner:
+  it carries SHAPE (rising, spiky, flat) and no readable values, which is exactly what a
+  register wants — a column of them turns "12 numbers per row" into a pattern the eye reads
+  without stopping. Reach for a real chart the moment someone needs to read a value off it.
 - **`bar_chart`** / **`line_chart`** / **`pie_chart`** — `BarChart` / `LineChart` /
   `PieChart`: the canonical SVG chart set (no recharts).
 - **`progress_bar`** — `ProgressBar`: the determinate meter; `compact` = ONE row, track + a
@@ -1624,12 +1719,19 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   the single in-flight upload tile `FileGrid` renders; reach for it only when hand-rolling a
   non-grid upload layout — it is i18n-free by design, so a bare call site owes it `labels`
   (`FileGrid` resolves them from `LoticsLocale.fileUpload` on your behalf).
+- **`file_thumbnail`** — **TWO RUNGS, and which one you pass decides what the tile IS.**
+  `COMPACT_THUMBNAIL_SIZE` (40) is a tile that RIDES A ROW — the file's identity mark, beside the
+  name — and it renders a document as a bare badge, because the row already names the file and a
+  40px box has no room to name it again. `THUMBNAIL_SIZE` (96) is a tile that stands on its own in
+  a grid, and it becomes a CARD that prints the filename itself. Pass 96 into a row and you get the
+  same string twice, the second copy truncated. The row rung is the same 40 an `Avatar` takes at
+  `lg`, because both answer "which row is this", and both sit in a 72px register row.
 - **`file_thumbnail`** — **`diff`** puts a `DiffKind` corner mark on a tile (top-LEFT, the one
   corner remove/selection/uploading do not claim) and fades a `removed` one. The mark rides a
   white RING: a tile's ground is an arbitrary photo, and a pale tint over a pale scan is a
   smudge. A `removed` tile fades its BODY only — the mark stays at full strength, since a faded
-  mark is the smudge the ring exists to prevent. Ignored below 32px: a 22px disc on a compact
-  tile is the tile, and a compact strip lives inside a row that carries the change instead. A grid says MEMBERSHIP well (arriving, leaving) and PAIRING not at
+  mark is the smudge the ring exists to prevent. Ignored at the ROW rung: a corner disc on a row-sized tile is the tile, and such a tile lives
+  inside a row that carries the change instead. A grid says MEMBERSHIP well (arriving, leaving) and PAIRING not at
   all — nowhere on a 96px tile to name what a replacement supersedes — so a set where things
   are being REPLACED wants `FileRow`. Also: `FileThumbnail` + `DisplayFile` + `THUMBNAIL_SIZE` /
   `COMPACT_THUMBNAIL_SIZE` + `getMediaIcon`: the completed tile — the right surface per