@lotics/ui 12.1.2 → 13.7.0

package/AGENTS.md

@@ -1,5 +1,10 @@
 # @lotics/ui — the UI reference index
 
+> **Upgrading to v13 from 12.x.** `RadioPicker`'s **`direction`** prop was removed — the
+> picker is always the stacked column of full-width choices. A former `direction="row"`
+> usage just drops the prop. Additively, `DetailRow` and `FormField` gained a **`warning`**
+> field annotation (amber, the third tone between `description` and `error`).
+
 > **Upgrading to v12 from 11.x.** Two exports were removed: **`CommentComposer`** (compose
 > comments with THE kit `Composer` — attach via `actionsButton`/`files`; `CommentList` is
 > unchanged) and **`DetailRow.info`** (field annotations are explicit — use the new

package/docs/catalog.md

@@ -95,8 +95,8 @@ Batch draft-form state → `useForm`.
 
 ### Edit a record's fields in place
 
-The `Inline*` family: `InlineTextInput` · `InlineNumberInput` · `InlineSelect` ·
-`InlineMemberSelect` · `InlineTagSelect` · `InlineDatePicker` · `InlineTimePicker`; a
+The `Inline*` family: `InlineTextInput` · `InlineNumberInput` · `InlineSelect` (single or
+`multi`) · `InlineMemberSelect` · `InlineDatePicker` · `InlineTimePicker`; a
 READ-ONLY field in that same column uses `InlineStatic` (matches the editor box exactly, no
 input chrome, so it aligns pixel-for-pixel). A stack of labelled field rows lives in
 `DetailTable` + `DetailRow`; the record's identity band is `RecordSummary`; its money
@@ -105,10 +105,9 @@ summary is `Ledger`.
 ### Tasks / to-dos — pick by ALTITUDE
 
 A task-management PAGE (many tasks, grouping, filters, expandable rows) is COMPOSITION —
-there is NO Task component (a Reminders row and a Linear column-grid share almost nothing):
-`CheckCircle` + a struck `InlineTextInput` + your meta cells; see
-[`tpl_tasks`](../examples/tpl_tasks.tsx) (quick list) and
-[`tpl_task_board`](../examples/tpl_task_board.tsx) (columns). A record's own small CHECKLIST
+there is NO Task component: `CheckCircle` + a struck `InlineTextInput` + your meta cells
+(`InlineDatePicker`/`InlineMemberSelect`/`InlineSelect`, all `variant="cell"`); see `tpl_record`'s
+Tasks section (the canonical task pattern) and [`tpl_task_board`](../examples/tpl_task_board.tsx) (columns). A record's own small CHECKLIST
 (the 5–8 tasks living in a drawer/section) is the `Checklist`/`ChecklistRow` compound +
 `SuggestionChip` commons + `CaptureRow` — see [`tpl_record`](../examples/tpl_record.tsx) /
 [`tpl_item_list`](../examples/tpl_item_list.tsx).
@@ -342,10 +341,15 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 
 - **`card`** — `Card` · `CardHeader` · `CardHeaderTitle` (+ `info` ⓘ popover) ·
   `CardHeaderMeta` · `CardBody` · `CardFooter`.
+- **`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
+  `warning`/`error` render as an ARIA `alert`) — wrapping form fields in an alert is wrong.
+  The law: **content + fields → `Inset`; a message → `Callout`.**
 - **`section_heading`** — `Section` · `SectionHeading` · `SectionHeadingTitle` ·
   `SectionHeadingMeta` · `Subsection` · `SubsectionHeading` · `SubsectionHeadingTitle` — the
   card-less twin of the Card family, compound, owns no margin; spacing via the Section gap
-  (12, fixed), no body component. `SectionHeadingTitle` is ALWAYS `##` (xl semibold;
+  (16, fixed), no body component. `SectionHeadingTitle` is ALWAYS `##` (xl semibold;
   `weight="medium"` opt-down only) + `info` for an ⓘ provenance popover after the title,
   same as `CardHeaderTitle.info`. `SubsectionHeadingTitle` is the `###` lg-semibold level-3
   title of a named group inside a section (same `info` ⓘ affordance as the section title) —
@@ -356,10 +360,11 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `SectionHandlers.expand/collapse`). **Warning:** two modules export a `Section` — the
   layout grammar's card-less region is the one in `section_heading`; import from
   `@lotics/ui/section` only when you specifically want this collapsible titled block.
-- **`section_stack`** — `SectionStack` · `SubsectionStack` — divided stacks that own the
-  between-block law: a fixed beat + hairline `Divider` BETWEEN blocks, skipping null
-  children (56 for the flat page's Sections, 24 for a section's Subsections); stop
-  hand-rolling gap + `<Divider />` pairs.
+- **`section_stack`** — `SectionStack` · `SubsectionStack` — stacks that own the
+  between-block law, skipping null children: `SectionStack` = a fixed 56px beat + a hairline
+  `Divider` between top-level blocks; `SubsectionStack` = a fixed 32px beat, space-only (no
+  hairline — titles carry the grouping, `divided` an opt-in for a rare headingless stack);
+  stop hand-rolling gap + `<Divider />` pairs.
 - **`section_card`** — `SectionCard`: a titled card with a one-line description and an
   optional hairline-set `footer` (where `TrendFooter` and source notes go).
 - **`stack`** — `Stack`: gap-spaced row/column; `useSeparator` inserts `Separator`s between
@@ -434,6 +439,15 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`pressable_row`** — `PressableRow`: THE register row — full-width hover/open wash,
   `selected` (the open record) vs `marked` (ticked in bulk-select), forwards `ref` for
   popover anchoring.
+- **`linked_record_box`** — `LinkedRecordBox`: a bordered box scoping ANOTHER record's data
+  (`icon` · `name` · `subtitle` · vertical `facts`), the WHOLE box a keyboard door into its
+  detail (`onOpen`/`doorLabel`); verbs ride an `actions` slot in a hairline-fenced footer at the
+  bottom (destructive LEFT, go-to RIGHT — the divider draws itself when `actions` is present, so
+  don't hand-add one). Use it wherever a record points at another (a shipment's customer, an invoice's
+  party, a case's sibling). It **enforces the a11y contract** copy-pasting got wrong: a
+  container with interactive descendants is never `role="button"` (invalid HTML) — an internal
+  empty door sibling carries the tab stop / name / focus ring, verbs lift above via `zIndex`.
+  The reassign picker / empty state that swaps in for the box is the consumer's.
 - **`pressable_highlight`** — `PressableHighlight`: the hover-wash + keyboard-focus-ring
   `Pressable` under `MenuButton`/`Switcher`/custom pressable surfaces; its style-fn/children
   receive `hovered` + `focusVisible`.
@@ -453,12 +467,16 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 
 ### Badges, status & feedback
 
-- **`badge`** — `Badge`: the tonal pill; `variant="dot"` = pill-less colored dot + label,
-  the LIGHT state indicator.
+- **`badge`** — `Badge`: a STATUS indicator (lifecycle state / risk / quality cue), the ONLY
+  thing it's for. **Default `variant="dot"`** (pill-less colored dot + label, the light indicator);
+  `variant="tonal"` is the heavy filled pill — opt in sparingly for the ONE prominent status of a
+  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_badge`** — `OptionBadge`: a select value as its configured colored badge.
 - **`callout`** — `Callout` · `CalloutTitle` · `CalloutText` · `CalloutActions` (`tone`
-  info|success|warning|error|neutral): inline status band.
+  info|success|warning|error|neutral): inline status band — a MESSAGE (`warning`/`error`
+  are ARIA `alert`s). For a form / nested content surface use **`Inset`**, never a Callout.
 - **`empty_state`** — `EmptyState`: centered placeholder for an empty list/filter result —
   `message` + `hint`, optional `icon` anchor and `action` CTA.
 - **`completion_state`** — `CompletionState`: the "all done" terminal state.
@@ -506,13 +524,14 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   the tint; override via `style` only when a surface genuinely wants otherwise.
 - **`number_input`** — `NumberInput`: numeric input; `format` for currency/units.
 - **`search_input`** — `SearchInput`: the search box for toolbars/filters.
-- **`form_field`** — `FormField` + `useFormField`: label / description / error / `optional`
-  marker wrapper; the fieldset grid cell (`half`/`full` widths — see the data-entry patterns
-  doc indexed in [AGENTS.md](../AGENTS.md)).
+- **`form_field`** — `FormField` + `useFormField`: label / description / warning / error /
+  `optional` marker wrapper (the three field-annotation tones — muted / amber / danger — all
+  wired into the input's describedby); the fieldset grid cell (`half`/`full` widths — see the
+  data-entry patterns doc indexed in [AGENTS.md](../AGENTS.md)).
 - **`form_text_input`** — `FormTextInput`: `FormField` wrapping a `TextInputField`; the
   one-line labeled text field. Controls without a Form\* twin just wrap in `FormField`.
 - **`form_switch`** — `FormSwitch`: the FormField-labeled twin of `Switch` — toggle +
-  clickable `label` (pressing it flips the value) + optional `description`/`error`; the
+  clickable `label` (pressing it flips the value) + optional `description`/`warning`/`error`; the
   settings-form boolean row. A bare toggle in a cell/toolbar → `Switch`; a full-row menu
   toggle → `SwitchButton`.
 - **`form_picker`** — `FormPicker`: `FormField` wrapping a `Picker` — one labeled native
@@ -558,20 +577,41 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   INSIDE the control and inline error, commit on blur (Enter saves, Escape reverts) or
   `controls="buttons"`; KEYBOARD focus on the closed view opens edit mode with the input
   focused (type → Tab → type — see the data-entry keyboard contract), pointer focus never
-  does; `background="tint" | "transparent"` (the zinc-50 editability chip vs
-  flat for dense uniformly-editable surfaces).
+  does; **`variant: "form" | "cell"`** is THE axis that separates a form field from a data-grid
+  cell (see below).
 - **`inline_text_input`**, **`inline_number_input`** (`format` for currency/units),
   **`inline_select`**, **`inline_member_select`**, **`inline_date_picker`**
   (`format="datetime"`, `optionalTime`; keyboard focus opens the TYPED segmented `DateField`
   — locale field order, separator advances, Alt+ArrowDown floats the calendar; click still
-  opens the calendar popover), **`inline_time_picker`** — the Inline\* per-field
-  editors; `InlineSelect`/`InlineMemberSelect` render the resting value like its option —
+  opens the calendar popover), **`inline_time_picker`** — the inline field editors (a form field by
+  default, a grid cell with `variant="cell"` — see the split below);
+  `InlineSelect`/`InlineMemberSelect` render the resting value like its option —
   `renderOptionContent` by default, `renderSelected` to override — a chip/badge at rest, not
-  just text.
-- **`inline_tag_select`** — `InlineTagSelect`: the MULTI inline editor — a tag SET in the
-  inline vocabulary: selected tags render as badges inside the standard chip (`renderTag`),
-  clicking floats a multi `OptionList` (checkbox rows), CLOSING commits the new set in one
-  `onSave` — never a borderless `Select` posing as an inline field.
+  just text. **`InlineSelect` is single OR multi** — pass `multi` for a tag SET (`value: T[]`,
+  commits the new set on popover-CLOSE; selected tags render as badges via `renderSelected`),
+  mirroring `Select`'s `multi` axis; there is NO separate tag component. Both modes take
+  `allowCustom` (a create-a-tag/option row) + `searchable`. **`InlineMemberSelect` takes `avatarOnly`**
+  — the resting display is the bare AVATAR (no name/chevron, a dashed "add" ghost when unset) for a
+  DENSE row where the name won't fit (a task-row assignee); the dropdown rows still show avatar + name.
+  `InlineDatePicker` takes a **`tone`**
+  (`TextColor`) that colours the resting date by
+  semantic state — overdue red, soon-due amber (the caller owns the rule, e.g. a task's `dueTone`);
+  the value text IS the signal, no separate dot.
+  **The form/cell split — one `variant`, not a second family.** Every `Inline*` editor is BOTH a
+  form field and a data-grid cell; `variant` picks which:
+  - **`variant="form"`** (default) — a zinc-50 chip at rest + a hover-BORDER. THE editability
+    affordance on a surface that MIXES editable and static values (a `DetailTable` / record field).
+  - **`variant="cell"`** — transparent at rest + a background-tint WASH on hover (`zinc-100` /
+    `zinc-200` press — the same `PressableHighlight` language as the row/cell beside it), and it reads
+    VALUE-FIRST: the date drops its resting calendar glyph, a select drops its chevron (the column
+    header + the uniformly-editable grid are the affordance; the saving spinner still shows). For a
+    DENSE, uniformly-editable surface — a register/`DataGrid` column, a task row (worked example:
+    `tpl_task_board`'s columns, `tpl_record`'s Tasks section).
+
+  There is NO separate `*Cell` component family — a data-grid cell is `<InlineSelect variant="cell" …/>`,
+  not a `SelectCell`. (Naming a component for a USE, and duplicating the picker stack to flip two
+  style properties, are both things the kit forbids.) A custom pressable cell you hand-roll should
+  match the `variant="cell"` language: the `PressableHighlight` wash, never a border.
 - **`inline_static`** — `InlineStatic`: a READ-ONLY value matching the Inline\* box metrics
   EXACTLY (height, padding, 1px transparent border) so a non-editable field — a computed
   total, a system ID, a synced/locked value — aligns pixel-for-pixel in the same column;
@@ -583,15 +623,16 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   edit; optional `trailing` slot renders a right-side action/badge after the value (units
   belong IN the value via `InlineNumberInput format`). The FIELD-ANNOTATION vocabulary (same
   names + meanings as `FormField`), always EXPLICIT — a row never hides guidance behind an ⓘ:
-  **`description`** = persistent guidance, under the VALUE (stacked mode mirrors the form
-  order label · description · control); **`error`** = field-level failure under the value,
-  danger + alert semantics (the `Inline*` editors already render their own transient save
-  errors — don't wire both); invalid/cross-field STATE = a co-located `Callout`; **`flat`**
+  **`description`** = a fact / persistent guidance (muted), under the VALUE (stacked mode
+  mirrors the form order label · description · control); **`warning`** = a consequence to weigh
+  before acting (amber, announced); **`error`** = field-level failure under the value, danger +
+  alert semantics (the `Inline*` editors already render their own transient save errors — don't
+  wire both); invalid/cross-field STATE = a co-located `Callout`; **`flat`**
   on a flat-text value row (`InlineStatic`, plain `Text`) tucks the annotation up by the
   control band's slack so its gap matches a chip row's.
   `DetailTable`: the compound parent of
   a row STACK — `labelWidth` (default 130) / `trailingWidth` / `minHeight` (default 40, the
-  inline-control grid) declared ONCE + the 6px row gap; with `trailingWidth` every row
+  inline-control grid) declared ONCE + the 8px row gap; with `trailingWidth` every row
   reserves the trailing column so value cells share one width and trailing items align at
   one x, like a table. RESPONSIVE with no prop: it measures its own container (onLayout, not
   the viewport — works inside a Drawer; the unmeasured first frame renders opacity-0 so the

package/docs/composition.md

@@ -370,6 +370,11 @@ All view controls are 40px tall (`CONTROL_HEIGHT`), `sm` labels, in ONE wrapping
 - **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.
+- **Nested content / a sub-form goes in an `Inset`, NEVER a `Callout`.** A Callout is a
+  MESSAGE, and `warning`/`error` render as an ARIA `alert` — wrapping form fields in an alert
+  makes a screen reader announce the whole form as one time-sensitive alert. `<Inset>` is the
+  tinted "well" for a grouped sub-form / inline fill editor / nested block: **fields + content
+  → `Inset`; a message → `Callout`.**
 - **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.)
@@ -407,29 +412,50 @@ gate's SCOPE, once** — never prose beside the button, never revealed only on p
 
 ## Field annotations & linked records
 
-- **The field-annotation vocabulary** (same names + meanings on `FormField` and `DetailRow`,
-  always EXPLICIT — never a hidden ⓘ on rows): **`description`** = persistent guidance (under
-  the VALUE on a horizontal row — the label column has no room for prose; stacked mode wears
-  the form order label · description · control); **`error`** = field-level failure under the
-  value, danger + alert semantics (the `Inline*` editors already render their own transient
-  save errors); cross-field / record-level STATE = a co-located `Callout`. Rows share ONE
+- **The field-annotation vocabulary** — THREE tones, same names + meanings on `FormField` and
+  `DetailRow`, always EXPLICIT (never a hidden ⓘ on rows): **`description`** (info, muted) = a
+  content/domain fact or persistent guidance, under the VALUE on a horizontal row — the label
+  column has no room for prose; stacked mode wears the form order label · description · control;
+  **`warning`** (amber) = a consequence the user should weigh before acting, announced on
+  appearance; **`error`** (danger + alert semantics) = an invalid state under the value (the
+  `Inline*` editors already render their own transient save errors); cross-field / record-level
+  STATE = a co-located `Callout`. Every tone is USEFUL AND TERSE — a short clause stating the
+  fact or consequence, never widget mechanics, never a second sentence; `warning` marks a
+  consequence, not decoration. Rows share ONE
   alignment law: the row top-aligns and label · control · trailing each center within the
   first control line — a tall value block never drags the label. A FLAT value row
   (`InlineStatic`, plain `Text`) sets **`DetailRow flat`**: the annotation tucks up by the
   control band's slack so the perceived gap under the text equals the gap under a chip —
   the band's invisible bottom half must never read as a hole above the description.
 - **A LINKED record never renders as field rows** — another record's data must not read as
-  fields on THIS one. The reference shape (`tpl_record`'s Customer/Handoff, inline — no
-  wrapper component): a BORDERED, fully pressable box (glyph anchor · identity · facts
-  stacked vertically) whose press opens the record's detail drawer (read-only rows + the
-  navigate verb); the action row sits INSIDE the box — destructive LEFT in danger, go-to
-  RIGHT. Editing the linked record happens on ITS page, never here. The press ANATOMY:
-  the box is a `PressableRow` (role-less, non-focusable surface — hover wash spans the
-  nested verbs) with the keyboard DOOR — an EMPTY absolutely-positioned `role="button"`
-  sibling carrying the tab stop, the accessible name and the focus ring — beneath the
-  content, and the interior verbs lifted above it via `zIndex: 1`. NEVER `role="button"`
-  on a container with interactive descendants: a button must not contain a button
-  (invalid HTML, a hydration error, and AT double-announcement).
+  fields on THIS one. Use **`LinkedRecordBox`** (`tpl_record`'s Customer/sibling are the worked
+  examples): a BORDERED, fully pressable box (glyph anchor · identity · facts stacked
+  vertically) whose press opens the record's detail drawer; the verbs ride its `actions` slot
+  in a hairline-fenced footer INSIDE the box — destructive LEFT in danger, go-to RIGHT. One verb
+  set across every box of a group (a party wall's five links all read "Gỡ", not a mix of
+  "Đổi"/"Gỡ"): with a clearable link, changing = remove → the empty-state picker re-prompts, so
+  the destructive verb covers both required anchors and optional adds. Editing the linked record happens on
+  ITS page, never here.
+  **The empty / attach state is a find-or-create `Combobox`, never a bare picker** (`tpl_record`'s
+  Customer is the worked example): rows are `renderOptionContent`-rich, NOT a wall of bare names —
+  the premium shape is a **glyph tile (28·radius 7·zinc-100) · the name over a muted metadata line**
+  that carries the type + identifying fact as TEXT (`type · code · city`), joined by "·" and free to
+  wrap the row taller. A type/attribute is **NOT a status, so it is text, never a `Badge`** (see
+  Badge discipline below). The row should read like the `LinkedRecordBox` it becomes — reuse the same
+  kind-glyph. (The kit suppresses `renderOptionContent` on the `allowCustom` "Create …" row so it keeps its plain + look.)
+  Plus `allowCustom` + `customOptionPlacement:"top"` + `customOptionLabel={q => 'Create "…"'}`. In
+  `onValueChange`, an existing pick attaches; the custom row opens a create **`Dialog` prefilled with
+  the typed query** (mint the record + link it) — so a party absent from the registry is created
+  WITHOUT leaving the record. `customOptionPlacement:"top"` keeps the create row visible while the
+  keyboard highlight stays on the first MATCH, so Enter on a partial never makes a duplicate. A
+  linked record seeded by a workflow (not user-attached) skips the picker — show the box or an
+  `EmptyState`, no create affordance. The component OWNS the press ANATOMY (the error-prone part hand-rolling
+  got wrong): the box is a `PressableRow` (role-less, non-focusable surface — hover wash spans
+  the nested verbs) with the keyboard DOOR — an EMPTY absolutely-positioned `role="button"`
+  sibling carrying the tab stop, the accessible name and the focus ring — beneath the content,
+  the interior verbs lifted above it via `zIndex: 1`. NEVER `role="button"` on a container with
+  interactive descendants: a button must not contain a button (invalid HTML, a hydration error,
+  and AT double-announcement).
 
 ## Color discipline — solid / tint / ramp + ONE accent
 
@@ -452,16 +478,27 @@ selection washes).
 (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
+## `Badge` is for STATUS only — everything else is text
 
-Lightest → heaviest:
+A `Badge` means STATE that must read at a GLANCE — a lifecycle status, a risk level, a quality
+cue. That is the ONLY thing it is for; keep the vocabulary scarce so a colored chip always MEANS
+status. **A type / category / attribute / count is NOT a status — render it as inline `Text` (a
+muted metadata line, free to wrap the row taller), NEVER a Badge.** A party's type, a document
+kind, a city, "3 files" → text. If you're reaching for a Badge in a row or an option list "to
+show more info," STOP — that's text. (The bug that set this rule: tonal type-pills sprinkled
+through combobox option rows.)
 
-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.
+When it IS a status, match weight to prominence — lightest → heaviest:
 
-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.
+1. **Colored `Text`** — a verdict WORD in a header (the valence tokens above).
+2. **`Badge variant="dot"` (the DEFAULT)** — a colored dot + label; a categorical STATE in a
+   scannable column / legend / inline. Reach for this by default; a bare `<Badge>` is `dot`.
+3. **`Badge variant="tonal"`** — a filled pill, the HEAVY exception: the ONE prominent status of
+   a surface (a drawer/detail header). Opt IN explicitly and sparingly; one per view, never
+   sprinkled through rows.
+
+A register's dense rows read lighter — the row's primary status is `dot`, its drawer twin may go
+tonal. A `Badge` is never a metric value.
 
 ## Typography
 

package/docs/data_entry.md

@@ -13,13 +13,14 @@ in [the templates](./templates.md) (`examples/tpl_*.tsx`).
 | You're capturing… | Reach for | Why |
 |---|---|---|
 | an EXISTING record's fields | [**Inline edit**](#inline-edit--the-preferred-way-to-edit-an-existing-record) (`Inline*`) | edit in place, no form mode |
+| a value in a DENSE ROW / register `DataGrid` cell (a task's due · assignee · status) | the SAME `Inline*` editor in **`variant="cell"`** | transparent at rest + a background-tint wash on hover (not the form's chip + border), value-first (the date drops its calendar glyph) — one editor per value type, `variant` picks form vs grid; there is no separate `*Cell` family |
 | a brand-NEW record | **create-then-refine** (`tpl_record`: "New" is ONE CLICK → a fresh Draft; everything refines in place on the record surface) | nobody fills 5 sections in one sitting; the surface is the editor |
 | a RELATED record (pick or make) | [**find-or-create**](#find-or-create--the-combobox-family-is-the-control) (`Combobox allowCustom`) | one control covers both |
 | REPEATING rows you build & revise | [**line items**](#line-items--create--preview--edit-a-composition-not-a-primitive) (create→preview→edit) | add / edit / remove, live totals |
 | CHARGES that bill onto documents | [**billing**](#billing--the-invoice-document-is-the-unit) (`tpl_record` Billing section) | the invoice document is the unit |
 | a record's FEE/charge SUMMARY | [**`Ledger`**](#fee-summary--ledger) (worked example: `tpl_item_list` drawer) | grouped money lines, one emphasized total — no bars/charts |
 | a multi-value TAG field | [**`Select multi`**](#tag--multi-value-field--select-multi) (`renderSelected` → `Chip`) | chips composed, not a separate control |
-| ONE choice from a small visible set | **`ChipGroup` pills** (or `RadioPicker` — column when options carry descriptions, row when short) | required single-select, one tap, every option visible |
+| ONE choice from a small visible set | **`ChipGroup` pills** (or `RadioPicker` — a stacked column of full-width choices, right when options carry descriptions) | required single-select, one tap, every option visible |
 | ONE pick from a BIG registry (ports, projects…) | on a RECORD surface: **`InlineSelect searchable`** (search lives in the popover); on a form/attach surface: **`Combobox`** with `value` | an inline row stays an inline editor — a persistent search input breaks the surface's grammar |
 | a YES/NO on a record | **`CheckboxInput`** as the `DetailRow` value | a boolean needs no editor mode |
 | a STATUS with terminal outcomes | [**disposition**](#disposition--lifecycle-status-is-asymmetric-by-phase) (open → resolve → revise) | guides the decision |
@@ -71,7 +72,7 @@ calendar popover stays the pointer path (click the resting value, as ever) — i
 the only path. A PARTIAL entry never commits and never clears the stored value: the field
 stays in edit mode showing the `datePicker.invalidDate` inline error until fixed or Escaped.
 
-The POPOVER editors (`InlineSelect` / `InlineMemberSelect` / `InlineTagSelect`) deliberately
+The POPOVER editors (`InlineSelect` / `InlineMemberSelect`) deliberately
 do NOT auto-open on focus — a popup opening on Tab arrival traps traversal; per the WAI-ARIA
 combobox contract they open on Enter/Space from the keyboard.
 
@@ -94,16 +95,16 @@ One per type:
   ADD/REMOVE a time — the value's own shape, date vs datetime, is the source of truth
   (`optionalTime` is ignored when `format="datetime"`).
 - **`InlineTimePicker`** — a time-only value.
-- **`InlineTagSelect`** — the MULTI member — a tag SET in the inline vocabulary: selected tags
-  render as badges inside the standard chip, clicking floats a multi `OptionList` (checkbox rows),
-  CLOSING commits the new set in one `onSave` — never a borderless `Select` posing as an inline
+- **`InlineSelect multi`** — the MULTI mode of `InlineSelect` (there's no separate tag component):
+  a tag SET (`value: T[]`), selected tags render as badges inside the standard chip, clicking floats
+  a multi `OptionList` (checkbox rows), CLOSING commits the new set in one `onSave` — never a borderless `Select` posing as an inline
   field.
 
 They split across two shared shells. The same-height **input-swap** editors (`InlineTextInput`,
 `InlineNumberInput`, `InlineTimePicker`) render **`InlineEditFrame`** driven by the
 **`useInlineEdit`** hook (the view⇄edit toggle, draft buffer, and async save) — swap a custom
 input into that pair to join the family. The **popover** editors (`InlineSelect`,
-`InlineMemberSelect`, `InlineDatePicker`, `InlineTagSelect`) instead compose **`InlineEditView`**
+`InlineMemberSelect`, `InlineDatePicker`) instead compose **`InlineEditView`**
 (the resting box, wired as the popover trigger) with their OWN `useState` for open/draft/saving/
 error — a pick, not a keystroke, is the edit, so `useInlineEdit` doesn't fit. `onSave` is async
 either way: the saving spinner sits INSIDE the control at its right edge (never a sibling — that
@@ -118,7 +119,7 @@ list's active-highlight and doubles the footer hairline), and never a persistent
 cell (noise on a dense board, and a pressable nested in the trigger is invalid DOM). `onSave`'s
 `next` stays non-null — a caller opts in per field; the clear fires `onClear`, which writes `null`
 (the app workflow must ACCEPT null on that input — a `select`/`date`/`member` field clears on
-null). `InlineTagSelect` (multi) needs no `onClear` — an empty set is already a valid `onSave`.
+null). `InlineSelect multi` needs no `onClear` — an empty set is already a valid `onSave`.
 
 ### The row stack — `DetailTable` + `DetailRow`
 
@@ -127,19 +128,20 @@ A STACK of rows lives in a `DetailTable` (label · value · trailing laid out li
 zinc-50 chips need) holding `DetailRow`s — set `trailingWidth` when ANY row carries a trailing
 action/badge, so EVERY row reserves the column and one row's `Copy` button never makes its editor
 narrower than its neighbours'. Rows share ONE alignment law: the row top-aligns and label ·
-control · trailing each center within the first control line — annotations (`description` under
-the value, `error` in danger with alert semantics; both indented to the chip's 8px text inset)
-grow the row downward without dragging the label. The full annotation vocabulary lives in
-composition.md §Field annotations.
+control · trailing each center within the first control line — annotations (the three tones
+under the value: `description` muted · `warning` amber · `error` danger, each indented to the
+chip's 8px text inset) grow the row downward without dragging the label. The full annotation
+vocabulary lives in composition.md §Field annotations.
 
 ### The editability affordance
 
-An editor AT REST sits on a zinc-50 chip — THE editability affordance: users see what's editable
-without hovering. `background="transparent"` opts a field out of the chip — for DENSE,
-uniformly-editable surfaces (a task list/board where EVERY cell edits: the chip repeated
-everywhere is noise and distinguishes nothing; hover/focus still reveal the input). Keep the chip
-wherever editable and static values MIX. A `disabled` editor rests FLAT automatically — the chip
-is the editability promise, and an inert field must not make it.
+A `variant="form"` editor (the default) AT REST sits on a zinc-50 chip — THE editability affordance:
+users see what's editable without hovering, and it hovers via a BORDER (an input's edge). Keep it
+wherever editable and static values MIX (a `DetailTable` / record field). `variant="cell"` opts out
+of the chip — transparent at rest + a background-tint WASH on hover — for DENSE, uniformly-editable
+surfaces (a register/`DataGrid` column, a task row where EVERY cell edits: the chip repeated
+everywhere is noise, and the wash matches the row/cell it sits in). A `disabled` editor rests FLAT
+automatically — the chip is the editability promise, and an inert field must not make it.
 
 A READ-ONLY value in the same column — a computed total, a system ID, a synced/locked field — is
 **`InlineStatic`**: it copies the editor box metrics exactly (height, padding, 1px transparent