@lotics/ui 11.3.0 → 11.5.0

package/docs/composition.md

@@ -0,0 +1,439 @@
+# Composition grammar
+
+The design-language contract for composing `@lotics/ui` screens: how a page is laid out, which
+heading construct belongs at which altitude, when content is carded vs flat, how rows/registers/
+drawers connect, the view-control vocabulary, and the color/typography/whitespace laws. Read this
+before laying out any screen — the component inventory lives in [the catalog](./catalog.md), and
+full worked-example screens ship as source in `examples/tpl_*.tsx` (picked by job in
+[templates](./templates.md)). Every rule here is enforced by the primitives' defaults; fighting
+them produces off-system UI.
+
+## Canvas & content column
+
+- **Canvas**: a full-bleed `colors.white` ScrollView with `padding: 28` (a `Drawer`'s scroll body
+  uses 24). Cards separate from the canvas by their own border + shadow, not by a tinted
+  background.
+- **Content column**: one centered column — `{ width: "100%", maxWidth, alignSelf: "center" }` —
+  sized to the job, with `gap: 16` between top-level bands/cards:
+
+| Job | typical `maxWidth` |
+|---|---|
+| Focused task flow (a pick run, a checklist) | 560 |
+| Single-record form / feed | 680–720 |
+| Dashboard, pivot, faceted browse | 920–1000 |
+| Register / work list / calendar | 1040 |
+| Wide wallboard / report | 1100 |
+
+## The heading ramp — one construct per altitude, no drift
+
+**The ramp is FIXED — the markdown ladder, no size knobs.** One outline on every surface; never
+restyle a heading level per-page.
+
+| Rank | `Text` size | Construct |
+|---|---|---|
+| `#` | `xxl` semibold | Page title — `PageHeader` / `RecordSummary` title |
+| `##` | `xl` semibold | Section title — `SectionHeadingTitle`, always |
+| `###` | `lg` semibold | Subsection title — `SubsectionHeadingTitle`, always |
+| body | `sm` | Everything else |
+
+- **Page band** — one per screen: a `Text size="xxl" weight="semibold"` title (`#`) + one `sm`
+  muted subtitle that says what the screen decides. Right side: the screen's ONE primary action
+  and/or a period filter — never a summary `Badge` (those belong to the KPI strip).
+- **Card header** — a card's own title band (or separate banded cards): `CardHeader` +
+  `CardHeaderTitle` (`sm` semibold; pass `info` whenever the title alone doesn't define the
+  numbers) + optional `CardHeaderMeta` (a count/unit/period, xs muted tabular).
+- **Section title** — ONE construct: `Section` › `SectionHeading` › `SectionHeadingTitle`
+  (`##` — xl semibold, optional muted `description` and `info` popover), everything left-aligned
+  at the column edge; `SectionHeadingMeta` and actions ride the heading row's right edge (the
+  title's `flex: 1` pushes them). The page column is a **`SectionStack`** — it owns the
+  between-section law (a fixed 56px beat + a bare hairline separating one section from the NEXT;
+  null/false children are skipped so a conditional section never leaves a stray hairline). The
+  `Divider` NEVER goes directly under a heading — that orphans the title from its own content.
+  Inside a DRAWER, a full multi-section workspace uses the real `SectionHeading` (its meta + action
+  slots carry each section's count and CTA); a `Text size="sm" weight="semibold"` stand-in is only
+  for small sub-groups. Do NOT wrap each section in its own `CardHeader`, do NOT hand-roll
+  sm-semibold lead lines on a flat page, and NEVER use a bare eyebrow as a section title.
+
+  **Warning:** two different `Section` components ship. The compound one described here comes from
+  `@lotics/ui/section_heading` (alongside `SectionHeading`/`SectionHeadingTitle`/
+  `SectionHeadingMeta`/`Subsection`/…). `@lotics/ui/section` exports a LEGACY collapsible
+  `Section` with a `title` string prop — a different component. Import from `section_heading` for
+  the grammar described here.
+- **Subsection title** — the level BELOW a section on a long record surface: `Subsection` ›
+  `SubsectionHeading` › `SubsectionHeadingTitle` (`###` — lg semibold; siblings — a `Badge`, a
+  `SectionHeadingMeta`, an action — ride the heading row's right edge). Sibling subsections stack
+  in a **`SubsectionStack`** (the same hairline law one step tighter: a fixed 24px beat + hairline
+  between groups — no margins, no hand-rolled dividers); a headingless `Subsection` is the
+  section's lead group. Group leads INSIDE a subsection's rows are `md` medium at most. Do NOT
+  hand-roll `Text weight="semibold"` group leads inside a section, and never promote a subsection
+  to its own section-level heading just to separate it.
+- **Eyebrow / label** — `<Text size="xs" color="muted" weight="medium">`, **sentence case, NEVER
+  `transform="uppercase"`**: a small quiet label above or beside content — an artifact tag
+  ("Proposed", "Question", "Suggested edit"), a field name, a metric caption, a minor one-line
+  label. **All-caps is banned** — it reads as shouting, and reflexively uppercasing every little
+  label is the #1 thing that makes a surface feel templated. Sentence case + medium weight, full
+  stop. (A COLORED status word — a verdict like "Mismatch" / "Resolved" — keeps the same xs/medium
+  shape with a status `color`, still not uppercase.) This applies to every hand-written label;
+  don't reach for a wrapper component either — just write the `Text`.
+- **Gate header** — a `Dialog` uses `DialogHeaderTitle`; a popover form uses
+  `Text size="sm" weight="semibold"` + an optional xs muted subtitle.
+
+## Period filters for time-constrained data
+
+Time-constrained data gets a **`DateRangeFilterField`** in the header band — never a static period
+badge. Every period-dependent number MUST follow the selection. Pass `includeTime` when the
+time-of-day matters: the trigger previews the chosen time (locale-aware) and the `labels` prop
+translates the presets, footer buttons, placeholder, and the time-segment editors.
+
+## Keyboard & focus
+
+- **Use `tabIndex`, never `focusable`.** React Native Web's `Pressable` silently ignores
+  `focusable` (it writes its own `tabIndex`), so set a pressable control's tab-stop status with
+  `tabIndex={0 | -1}` (`focusable` only works on a plain `View`/`TextInput`). Roving widgets
+  (`Tabs`/`SegmentedControl`/`RadioPicker`) keep ONE stop at `0`, the rest `-1`.
+- **NEVER let a FOCUSED control unmount.** A conditional pointer affordance that vanishes on use
+  (e.g. an "apply suggested value" pill shown only while a field is empty) must be
+  `tabIndex={-1}`, or the browser drops focus to `<body>` and the next Tab jumps to the page's
+  first focusable.
+
+### Focus rings are per-component, never global
+
+There is NO global focus CSS — the kit only resets the native outline. Every interactive control
+paints its OWN ring; nothing rings unless it opts in. Three ways, pick by base:
+
+- **`FocusRingPressable`** (`@lotics/ui/focus_ring_pressable`) — a `Pressable` that rings on
+  keyboard focus WITHOUT the hover wash; the base for any control whose hover affordance is its
+  BORDER, not a wash (inputs/selects, the inline editors, cells, tiles, nav buttons, menu
+  options). Forwards all `PressableProps`; its state-fn `style` exposes `hovered`/`focusVisible`
+  so the control paints its own border-hover. Reach for this before hand-rolling a Pressable + the
+  hook.
+- **`PressableHighlight`** — set the opt-in **`focusRing`** prop (or read `state.focusVisible`
+  from its style-fn / children for a bespoke treatment, e.g. `CardSelectItem`, which rings on
+  hover/press/focus).
+- **`useFocusRing`** (`@lotics/ui/use_focus_ring`) — the underlying hook for inputs / custom
+  surfaces. Returns `{ focusVisible, focused, focusProps }`; spread `focusProps`, apply
+  `focusVisible && { boxShadow: FOCUS_RING }` (comma-join any existing box-shadow).
+  `useFocusRing({ always: true })` for text-like inputs/selects (ring on ANY focus, as browsers do
+  for typing-capable fields); plain controls omit it (keyboard-only).
+
+The ring is the shared **`FOCUS_RING`** token (`@lotics/ui/control_surface` — a 2px zinc-900
+box-shadow flush against the box, layout-neutral). A mouse-opened popover trigger
+(Select/Combobox/InlineSelect/InlineDatePicker) wears the SAME token on its open state, so an open
+trigger reads identically to a keyboard-focused control. **Coverage is a contract**: EVERY
+interactive control must ring — a focusable control with no focus treatment is a bug; a surface
+that shouldn't ring is a non-control → `tabIndex={-1}`, not a missing ring.
+
+## Hover grammar — intensify the control's own signature
+
+Hover intensifies a control's OWN resting signature — never a foreign affordance. **Pick the base
+by WHAT THE SURFACE IS; never a raw `Pressable`.**
+
+| Surface | Examples | Resting signature | Hover | Base |
+|---|---|---|---|---|
+| Fields (type into / pick from) | `TextInputField`, `Picker`, `Select`, `Combobox`'s input, `NumberInput`, the date/time fields, `DateRangeFilterField`, the inline editors (`InlineSelect`/`InlineDatePicker`) | a BORDER | darkens the border to `HOVER_BORDER` (zinc-400); a borderless in-cell field REVEALS one | `FocusRingPressable` |
+| Actions | `Button`, `IconButton` | a FILL | darkens the fill (own color logic) — never a border, never a wash | built-in |
+| Pills / toggles | `Chip`/`ChipGroup`/`FilterChip` (via `chipSurfaceStyle`), `SegmentedControl`, `Tabs`, `Switcher`, `RadioPicker` | a pill SURFACE | washes it (white → zinc-100; pressed zinc-200); selected adds a ring/fill | `chipSurfaceStyle` |
+| Surfaces | `PressableRow`, `MenuButton`, list/menu items, `CardSelectItem`, `Accordion` headers | a row/card SURFACE | washes it — the grey wash IS the affordance | `PressableHighlight` |
+
+For fields: layer the hover-border AFTER `style` so it wins over the caller's resting edge, put the
+open ring (`FOCUS_RING`) on the open state, and **a field NEVER greys its content**. The bug this
+grammar prevents: a FIELD built on `PressableHighlight` inherits the wash AND its own border — it
+greys *and* animates its edge while its siblings only border-hover. Reach for `PressableHighlight`
+on a bordered/input control and you've made it.
+
+## Cards — banded and composable
+
+All from `@lotics/ui/card`. A plain `<Card>` has a 20px padding and the author owns the content; a
+**banded** card zeroes the padding and composes the family slots:
+
+```tsx
+<Card style={{ padding: 0 }}>
+  <CardHeader>
+    <CardHeaderTitle info="what this shows">Title</CardHeaderTitle>
+    <CardHeaderMeta>12</CardHeaderMeta>
+  </CardHeader>
+  <CardBody>…</CardBody>          {/* repeat with <Divider/> between */}
+  <CardFooter>hint(flex:1) + actions</CardFooter>
+</Card>
+```
+
+Never nest cards; never hand-compose a title or footer band. `info` is standard, not garnish — a
+reader who doesn't already know the data shouldn't have to guess what a number means.
+
+### Flat work execution & data capture vs carded monitoring
+
+A `Card` is ALWAYS a bordered, lifted container — **there is no "flat card"**. MONITORING /
+dashboard screens group with cards (and the `KPIStrip` band). WORK-EXECUTION screens — registers,
+lists, worklists — AND **data-capture / record screens (forms, wizards, billing, settings, inline
+records) are FLAT**: content sits DIRECTLY on the white canvas with no Card wrapper; separation
+comes from the row wash, gaps, and the `SectionHeading` + `Divider` rhythm. Reach for a Card only
+where a screen holds a DISTINCT region that must be told apart from another; a single register or
+list filling the screen needs none. ONE carve-out inside a flat form: **repeating SUB-OBJECTS
+(line items) are each their own small Card** (`padding: 16`), so discrete items read as discrete
+objects — hairlines between them blur into one run-on list.
+
+## Summaries — two altitudes, never mixed
+
+| Altitude | Component | Where | Shape |
+|---|---|---|---|
+| Dashboard | `<KPIStrip items={[{label, value, trend?, caption?, tone?, compact?, info?}…]}>` | TOP of a dashboard | a boxed stat band — a `Card` of `KPICard` columns |
+| Register / list | `<SummaryLine items={[{label, value, tone?, compact?, trend?, info?}…]}>` | BELOW the toolbar | a light inline line — a small `Metric` + muted label per item |
+
+A `SummaryLine` is recomputed from the FILTERED rows so it always describes WHAT'S SHOWN. Both are
+INFORMATIONAL — they never filter or navigate (that's the tabs/chips' job); if there are no
+cross-cutting numbers, drop them. Do NOT put a `KPIStrip` on a register page or a `SummaryLine` on
+a dashboard. Card stat rails use `KPICard`.
+
+## Numbers, money, dates
+
+- Free-standing numerals: `<Text tabular>` — always.
+- **Money**: `formatMoney(n)` from `@lotics/ui/format_money` (`compact` abbreviates values
+  ≥ 1,000,000 for strip captions). **Warning:** the full-value path formats via `Intl`, whose
+  output separates the currency symbol with a non-breaking space (the compact path uses a plain
+  space) — normalize `\s` when asserting on its output in tests.
+- **Dates**: `formatDate(value, opts)` from `@lotics/ui/format_date` — the date-VALUE formatter.
+  `format` (the date STYLE) ∈:
+
+| `format` | Renders |
+|---|---|
+| `date` (default) | `22/05/2026` |
+| `medium` | `22 thg 5, 2026` |
+| `long` | `22 tháng 5, 2026` |
+| `dayMonth` | `22 thg 5` |
+| `monthYear` | `Tháng 5 2026` |
+
+  **`time: true` is orthogonal** — it prepends the 24h time to ANY style (`14:30 22/05/2026`,
+  `14:30 22 tháng 5, 2026`); `compact` drops the year on the `date` style; `emptyLabel` renders
+  for null/invalid input. It's `Intl` + the product's conventions (stable `/` separators,
+  timezone-naive ISO parsed as local wall-clock, 24h time-first) — never hand-roll a date via
+  `Intl`/`padStart` for value display. For an order the presets lack (e.g. time-first
+  `HH:mm dd/MM/yyyy` in a doc builder): `parseDate` + assemble the missing order — never a regex
+  re-implementation. (Exempt: a component's own internal chrome — a calendar's header/weekday/a11y
+  labels, a gantt axis — renders its own set.)
+
+## Every number is a door
+
+Except the KPI strip: a component that summarizes records leads to the records behind it when
+pressed — switch to the filtered list, expand in place, or navigate. Expansion happens IMMEDIATELY
+below the pressed element — the composable `Accordion` family (`AccordionHeader` / `AccordionTitle`
+/ `AccordionMeta` / `AccordionContent`); a header-only accordion renders a plain row of identical
+rhythm, so lists mix expandable + static rows. The body is **flush** with the header's left edge
+(aligns with the title — like a `Section` body, no indent, no tinted well). `AccordionHeader` is a
+layout slot: `AccordionTitle`/`AccordionMeta` is the compact list-row heading, but for a
+**collapsible Section** (configurable font/level/description + count) compose the SAME
+`SectionHeadingTitle`/`SectionHeadingMeta` inside it — one heading family across static +
+collapsible.
+
+## No dead rows — registers & tables
+
+Every listed record is actionable. PRIMARY entity rows press-open the workspace `Drawer`
+(sequenced — see [master-detail](#master-detail--list--workspace-drawer-with-sequencing));
+read-only drill-downs expand via `Accordion` or glance via `Peek`; every other row gets an
+`ActionMenu` (⋯ → `MenuButton` items: destructive last + **confirmed** via `Alert`). The whole
+surface is the door: register rows are `PressableRow` (full-bleed wash including nested controls),
+Divider-separated.
+
+| `PressableRow` variant | Shape | Use |
+|---|---|---|
+| `register` (default) | rounded (radius 10) full-width hover/open/`marked` wash; content sits on the 20px gutter so a `Table` header + cells align | THE record list |
+| `bleed` (legacy) | 20px square, `Divider`-separated | only an edge-to-edge data grid that genuinely wants hard rules |
+| `inset` | rounded (radius 8), pulled in from the edge | grouped lists in a padded container (Accordion drill-downs) |
+
+The `Divider` BETWEEN rows is the resting separation; the wash is the hover state. `selected`
+shows a zinc-100 highlight; `marked` (a bulk-ticked row) a resting blue-50 tint.
+
+**The COLUMNAR register is `Table`/`TableRow`/`TableCell`**: define `columns` once — the header
+band + every row's cell widths derive from it and can't drift. ONE hairline under the header; the
+rows below it Divider-separated. A sortable column shows its `SortHeader` glyph ALWAYS (a neutral
+up/down glyph when unsorted) so it reads as sortable; pressing cycles none → asc → desc → none.
+A `TableRow` with no `onPress` renders a STATIC read-only row (no hover wash, no pointer cursor) —
+so `Table` also serves read-only tabular data (a fee breakdown, a spec sheet), not just interactive
+registers. A pressable `TableRow` REQUIRES `accessibilityLabel` ("Open …") — its keyboard door is
+an empty overlay with no content to derive a name from.
+
+Make a register SELECTABLE with the `Table` `leading` gutter + `selectAll` slot — a
+`CheckboxInput` per `TableRow` (its `leading` slot) + a select-all in the header band, the ticked
+rows `marked`, paired with a `FloatingActionBar`. The selection state is the **`useSelection()`**
+hook (`@lotics/ui/use_selection`: `selected` / `has` / `count` / `toggle` / `setAll` /
+`allSelected` / `indeterminate` / `clear`) — gating which rows CAN be ticked stays with you: pass
+only the selectable ids to `setAll`/`allSelected`/`indeterminate` (a non-selectable row gets a
+disabled checkbox, keeping the gutter aligned). Selection persists across pages, so `count` is the
+running total. `tpl_item_list` is the reference. Paginate OUTSIDE (slice + `Pagination` in the
+`CardFooter`).
+
+Right-hand columns align only if every trailing element is FIXED-width — give each trailing action
+a fixed `width`, so amount/status columns don't jitter.
+
+## Row actions are always-visible siblings — never hover-revealed, never nested
+
+A pressable row = a role-less surface (the hover/press wash covers the whole row) + an accessible
+"Open …" door (a button) + trailing actions (⋯, remove ✕, edit) as SIBLINGS of the door. A button
+must not contain another button, so each action is independently pressable and the ✕ isn't
+swallowed by the row press (`FileRow` and `PressableRow` are the references). The door wraps the
+row body ONLY when that body is non-interactive by construction (`FileRow`'s name/meta); where the
+body is arbitrary app content — `TableRow`'s cells, which legitimately carry a `Link` or a popover
+trigger — the door is an EMPTY absolutely-positioned sibling under the cells (tab stop + name +
+focus ring; the mouse rides the surface), so a control in a cell never nests inside it.
+
+Actions stay **visible** — a hover-only action is invisible to keyboard and touch users. The ONLY
+exception is a DENSE tree/register where a persistent per-row action would clutter: reveal on
+hover **OR focus-within**, keeping the action in the DOM + tab order and gating only its opacity,
+so it's still keyboard-reachable. Do that locally — there is deliberately no shared hover-reveal
+primitive (one existed and made the keyboard-inaccessible anti-pattern easy; it was removed).
+
+## Master-detail = list + workspace Drawer with sequencing
+
+Pressing a PRIMARY entity row opens the record workspace in a `Drawer` with `onPrev`/`onNext`/
+`position` ("3/24") over the visible ordering (←/→ arrow keys are built in). Key the drawer body by
+record id so per-record state resets on step. Facts are `DetailRow`s; the commit bar is a
+`DrawerFooter` (a hairline-topped band pinned to the panel bottom — render it as the LAST child,
+after the scroll body; actions sit right, a leading `<Text style={{ flex: 1 }}>` hint pushes them
+there). The open row shows a `selected` highlight (and `marked` for a bulk-ticked row). `Peek` is
+ONLY for secondary references — a glanceable summary popover on an inline reference (a customer
+name, a record id) with ONE action to the full record — never the primary row press.
+
+## Two work shapes, no side panels
+
+A work screen is ONE of two shapes — never a persistent side-by-side split (it dies on a phone,
+and the "detail" of a list belongs in a `Drawer`/sheet, not a second column):
+
+1. **Work each** — a flat register/list; press a row → its workspace `Drawer` (above).
+2. **Act on many** — a flat list with a leading `CheckboxInput` per row + a select-all header
+   band, plus a bottom-pinned `<FloatingActionBar count label onClear>` carrying the bulk
+   action(s) while ≥ 1 row is ticked (it renders nothing at count 0); a row that can't take the
+   action has no usable checkbox. Bar weight gradient, left → right: the built-in Clear is muted
+   (the quietest act), destructive bulk = `danger-secondary` + icon, secondary bulk = `secondary`
+   + icon, ONE primary CTA last — never repeat the count in a CTA title; the bar's label already
+   carries it.
+
+When a region genuinely must sit beside the list (a source/remainder summary, a capacity picker),
+make it a TOP summary header or move it into a `Popover`/sheet at the decision point — not a
+standing column.
+
+## One control radius
+
+Every interactive control (`Button`, the inputs/selects/pickers, `SearchInput`, `MenuButton`,
+`Tabs`, the `SegmentedControl` track, `ChipGroup`/`FilterChip`/`Chip`) wears **`CONTROL_RADIUS`**
+(10, from `@lotics/ui/control_surface`) — never a literal. Containers are deliberately larger
+(`Card` 16). An element NESTED inside a padded control (a segmented thumb, a
+combobox chip, an ✕ on a chip) takes `CONTROL_RADIUS − padding` so its corner stays CONCENTRIC
+with the parent — set it equal and the inner corner bulges past the outer curve. Round-by-function
+controls (avatars, status dots, switches, sliders, progress bars, `IconButton`) stay full (999); a
+small square toggle (`Checkbox`, 24px) keeps a proportional small radius (6 — the same fraction of
+its box that 10 is of a 40px control), not the band radius. No capsules — `Button` has no pill
+shape.
+
+## One view-control vocabulary
+
+All view controls are 40px tall (`CONTROL_HEIGHT`), `sm` labels, in ONE wrapping band:
+
+- **`SearchInput`** is THE search box — a white `TextInputField` preset (the shared
+  `CONTROL_RADIUS` like every other input, a thin border, the leading search glyph + a clear ✕).
+  It reads as search by its ICON + white fill, not a distinct shape, so a toolbar of controls
+  stays one consistent band. Never a bare `TextInputField` + search icon.
+- **`ChipGroup`** is THE one-of-N lens (≤ ~10 options the user flips between; include "All";
+  counts in the label). Filters ONE list to a SUBSET — including by process stage / lifecycle
+  state.
+- **`FilterChip`** is THE secondary-dimension filter — a compact chip that opens a composed
+  popover editor (`OptionList` multi / `RangeSlider` / `Counter` / date range). Single-select
+  closes on pick via the `{({ close }) => …}` render prop.
+- **`ColumnFilter`** is the TYPED column filter — give it a `FilterableColumn`
+  (`type: "text" | "number" | "select"`) + a controlled `ColumnFilterValue` and it renders the
+  right editor (contains / range / multi-select) inside a `FilterChip`, with
+  `columnFilterToConditions` mapping the value to query predicates. Reach for it — ONE compact
+  chip per dimension — when a register filters on SEVERAL columns (origin, destination, carrier,
+  type…). Never hand-roll a row of bespoke chips/filters, and never use a permanently-expanded
+  `ChipGroup` for a secondary dimension.
+- **`Combobox`** is the SEARCHABLE picker — reach for it over `ColumnFilter` when the value is ONE
+  of a large/growing set you type to narrow (a port, a customer) rather than a short fixed list.
+  Pass `recentOptions` (the same option list) so a click opens the full list, then typing filters.
+  The **From → To route picker** is two of them (`icon="map-pin"`, `clearable`) with an
+  `arrow-right` between — flight-search style.
+- **`Tabs`** switch between VIEWS/sections (different content/layout) — never a subset of one
+  list. A tab earns a `status` dot (the optional `TabOption.status`, a `ColorName`) only when its
+  area needs attention (a blocker / missing item) — the resting state has none.
+  **`SegmentedControl`** chooses a MODE/PARAMETER of the SAME view (2–4 peers, no panel swap).
+- **Layout**: search + secondary filters LEFT, the primary CTA RIGHT, in ONE band. A `ChipGroup`
+  one-of-N lens is fine ONLY when the band has no `SearchInput`; once a search is present, the
+  status filter becomes a `Select`/`FilterChip` dropdown — never a row of pills competing with the
+  search.
+
+## Commit & feedback surfaces
+
+- **Footer actions align RIGHT.** `PopoverFooter`/`DialogFooter` default `align="end"`;
+  `DrawerFooter` is right-aligned by construction. Commit at the right edge, secondary to its
+  left. Never left-flow a Save/Submit.
+- **Empty result**: `<EmptyState message hint? icon? action?>` — never a bare muted Text.
+- **Inline status**: `<Callout tone="info|success|warning|error|neutral">` — compound (like
+  Card): compose `CalloutTitle`/`CalloutText`/`CalloutActions` inside. `Callout` is INLINE;
+  `Alert` is the blocking modal; `Badge` is a one-word pill.
+- **One primary action per surface.** Everything else secondary/muted; destructive = `danger`
+  styling + an explicit label. (A grouped BUILDER section — line items — MAY give its own Add
+  action `primary`; it sits at a different altitude than the form's one terminal commit.)
+- **Button labels carry no trailing ellipsis** ("Assign", not "Assign…"). **Button color is
+  VALENCE/RISK, never category**: the ladder `muted < secondary < primary` is the emphasis axis;
+  `danger` (and its quieter `danger-secondary`) marks destructive — that's the whole axis. No
+  "success"/green button. Decision UIs put positive/negative color on the STATUS (dot) and verdict
+  (colored `Text`), not the buttons.
+
+## Color discipline — solid / tint / ramp + ONE accent
+
+Every status / data-viz / accent color comes from a NAMED helper (`@lotics/ui/colors`), never a
+hand-picked `colors.<family>[shade]`:
+
+| Helper | Returns | Use |
+|---|---|---|
+| `solid(name)` | the family's 500 | dots, chart series, meter accents |
+| `tint(name, α)` | a low-alpha wash of the 500 | cell/segment tints, dimmed states |
+| `ramp(name, count)` | N shades of ONE family, strong → light | a coherent single dimension (an ordered funnel, a breakdown) — the label carries identity, the shade only orders |
+
+A status is ONE family NAME (`{ color: "emerald" }`) and every weight derives from it. **One
+accent per screen purpose** (blue = pipeline, emerald = money, red = danger, amber = waiting).
+Direct `colors.*` access is reserved for NEUTRALS (`zinc`, `border`, `white`, the `*[50]`
+selection washes).
+
+**TEXT never wears `solid()`** — the 500 is a FILL shade (dots, series). A status word/number uses
+`Text`'s valence tokens: `color="danger"` (red-900) / `"warning"` (amber-700) / `"success"`
+(emerald-700) — all AA on white. Map a dynamic `ColorName` to a token at the call site; hue nuance
+(rose vs orange) stays on `Badge`s. Links use `Link`/`TextLink` (blue-600), never `solid("blue")`.
+
+## Status indicators have a WEIGHT — match to prominence, never to a metric
+
+Lightest → heaviest:
+
+1. **Colored `Text`** — a verdict WORD in a header (the valence tokens above).
+2. **`Badge variant="dot"`** — a categorical STATE in a scannable column / legend.
+3. **`Badge`** (tonal pill, the default) — a record's PROMINENT status: a drawer/detail header.
+
+A register's dense rows read lighter — the row's primary status is `variant="dot"`, its drawer
+twin tonal. A `Badge` is never a metric value.
+
+## Typography
+
+Only the `Text` primitive (`size` / `weight` / `color` / `transform` / `tabular` / `level` for
+semantic heading rank). Uppercase tracking is built into `transform="uppercase"` — never hand-set
+`letterSpacing`.
+
+On web, the heading sizes are **responsive** at the 768px viewport breakpoint (the kit's screen-size
+boundary); native uses the base column:
+
+| `size` | base / native | web ≥ 768px | Role |
+|---|---|---|---|
+| `xs` | 12 | 12 | eyebrows, meta, captions |
+| `sm` | 14 | 14 | body (the default) |
+| `md` | 16 | 16 | emphasized body, group leads |
+| `lg` | 18 | 20 | `###` subsection titles |
+| `xl` | 22 | 24 | `##` section titles |
+| `xxl` | 28 | 32 | `#` page/record title |
+| `xxxl` | 32 | 48 | hero numbers |
+
+(Line heights are baked per size and platform-tuned; don't override them.) Weights: `regular` / `medium` /
+`semibold`. Colors: `default` (zinc-900), `muted` (zinc-600), `inverted`, the valence set
+(`danger`/`warning`/`success`), and the explicit `zinc-900/700/500/400` steps (`zinc-400` is the
+disabled ink).
+
+## Touch & whitespace
+
+Anything pressable is ≥ 40px tall (8px minimum gap between pressables). 16px between cards, 24–28
+canvas padding, 16–20 inside bands, 10–12 between content lines. Density comes from alignment +
+hierarchy, not cramming.