@lotics/ui 47.6.0 → 47.6.1

package/docs/catalog.md

@@ -443,6 +443,11 @@ controls is `PressableRow` + **`PressDoor`** — never `PressableHighlight`, whi
 button and wraps its children (a button must not contain interactive descendants). `Table`/
 `TableRow` does exactly this internally, so a columnar register needs no assembly.
 
+A subject with ONE qualifying line under it — in a table cell, a row, or beside a mark — is
+**`CellStack`** (`title` + `caption`), never two `Text`s in a `View`. It owns the three-part
+stacked-pair rule that composition.md §Typography states: which rung the caption takes, which
+lines are tightened, and the zero gap. See §"Lists, tables & registers".
+
 ### Filters & view controls
 
 `SearchInput`, `ChipGroup`, `FilterChip` (+ `Slider range`, `Counter`), `Chip`,
@@ -463,6 +468,16 @@ passes through — `Skeleton` / `Loading` (in flight) → `ErrorState` (failed)
 (succeeded, nothing) → `CompletionState` (done). Pick by what the region can ASSERT: an empty
 says the read succeeded and found nothing, a failed read knows neither.
 
+**An EXCEPTION a check produced is `Finding`, not a `Callout` — and it does not matter who ran
+the check.** The discriminator is the SHAPE of what was found, never its author: two readings
+that disagree, with a magnitude between them, is a `Finding` (severity ranks it, `readings` name
+what each side says, `delta` says how far apart) — a rules engine comparing two stored figures
+qualifies exactly as an extraction comparing two documents does. A `Callout` is for a STATE with
+no second reading to contradict: a record past its validity, a row that will not bill. Reaching
+for a Callout on a genuine contradiction throws away the ranking, the magnitude and the
+provenance, and there is no way to get them back at the call site.
+→ `src/finding.tsx`, whose docstring owns this rule.
+
 ### Files
 
 **Pick the surface FIRST, and pick exactly one per set.** Documents get a LIST (`FileRows`),
@@ -526,8 +541,9 @@ layout). An add is `after` alone, a removal is `before` alone, an update is both
 is a `DiffValue` over `CardSelectItem` candidates — and the ROW around any of them belongs to
 your screen. See the AI-patterns doc indexed in [AGENTS.md](../AGENTS.md) for the laws; `Clarify` (the agent asks back — selectable
 `ChoiceList` options), `Sources` (provenance chips for AI output — at review scale,
-`label={null}` slots the chips at a section's bottom), `Finding` (one ranked insight from an
-AI check, laid out HORIZONTALLY: a severity dot, the title, and the `delta` right-aligned on
+`label={null}` slots the chips at a section's bottom), `Finding` (one ranked discrepancy from a
+cross-check — AI or a rules engine, the component does not care; see §"Status / feedback" for
+the Finding-vs-Callout call — laid out HORIZONTALLY: a severity dot, the title, and the `delta` right-aligned on
 that same line, over the `readings` stacked ONE PER LINE — each `source value`, no separator
 joining them (a middot claims a relation it will not name, and is the one mark a screen reader
 drops), both kept on
@@ -1660,6 +1676,23 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   A `description` passed as a NODE keeps its own leading — the component only sets it on the
   string branch, because forcing a line box on somebody else's subtree re-spaces content that
   may not be a line of text at all.
+- **`cell_stack`** — `CellStack`: a SUBJECT over one qualifying line, as a value primitive —
+  the commonest cell in any register, and the shape most often hand-rolled wrong. `title` +
+  `caption`, plus `weight` / `marked` / `size` / `color` / `tabular` / `align` /
+  `numberOfLines`.
+  It OWNS the three-part stacked-pair rule that [composition.md](./composition.md) §Typography
+  states, so a call site never re-derives it: the caption's rung follows **what else already
+  separates the pair** (a `medium` subject or a leading identity mark ⇒ the caption keeps body
+  size, because that line is often the disambiguator; both lines regular ⇒ it drops to `xs` or
+  the two read as peers); both body-rung lines take `leading="tight"`, an `xs` caption being
+  tight already; and the stack's `gap` is **0**, because each tight box already contributes
+  3px a side.
+  A LONE `title` is deliberately NOT tightened — tight leading closes a PAIR up, and there is
+  no second line to close up to. A `caption` passed as a NODE keeps its own leading and ink,
+  for the reason `ListItem`'s `description` does.
+  Reach for it over two `Text`s in a `View`: the excess height in a hand-rolled pair comes
+  from the LINE BOX, so no margin and no gap appears anywhere to explain it and no spacing
+  probe can see it — it is reported as "too far apart", never as its cause.
 - **`table`** — `Table` + `TableRow` + `TableCell`: the paginated high-volume register
   (columns defined once, `sortLabels` localizable; rows are `PressableRow`-based).
   CONTAINER-RESPONSIVE with no prop (measures itself, like `Breakdown`/`DetailTable`): when
@@ -2589,7 +2622,8 @@ component rather than showing it at zero.
 - **`sources`** — `Sources` + `SourceRef`/`SourceKind` (record | document | table | web |
   knowledge): provenance chips, per-kind glyphs.
 - **`finding`** — `Finding` + `FindingReading` + `FindingSeverity`/`FindingLabels`: one ranked
-  AI-check insight on two lines — severity dot, title, right-aligned `delta`, then the
+  discrepancy on two lines, from a cross-check by WHOEVER ran it — an AI extraction, a rules
+  engine, an audit — severity dot, title, right-aligned `delta`, then the
   `readings` with the source each came from; optional `detail` consequence, children slot, and
   the `finding` locale slice.
 - **`result_header`** — `ResultHeader` (+ `ResultTone`): the save-direct RECEIPT's outcome

package/docs/composition.md

@@ -318,6 +318,14 @@ verb is off-screen, and on an empty list there is no last row to sit under. The
 section's control line — it already carries the meta and the view controls — so the add belongs on
 it, in the same spot whether the section holds nought or forty.
 
+**The heading's FIRST child is the title — a mark for the subject goes in
+`SectionHeadingTitle`'s `leading` slot, never beside it.** `SectionHeading` reads child
+one as the title and groups everything after it, so an `Avatar` passed as a sibling
+becomes the title and the real title joins the trailing group — which is content-sized,
+so the row stops pushing the action to its right edge. Nothing clips and nothing errors;
+the action simply sits mid-row. `icon` is for a CATEGORY (an `IconName`); `leading` is for
+an IDENTITY — a company's avatar, a person's, a logo.
+
 **When the row runs out of width, the VERB wraps — the title never gives way.** The title names
 the section; the verb is the thing that can move. Getting this backwards is easy to ship because
 RN-Web resolves `flex: 1` to `flex-basis: 0%` with `min-width: 0`, so a title beside a button that
@@ -674,6 +682,23 @@ by — its key, code, or id — because that is what they are scanning against a
 or someone on the phone. No other column can take its place: a name repeats, a status is shared by
 dozens.
 
+**A set of records the reader COMPARES on a value is a register, and a `ListItem` list cannot be
+one.** `ListItem` gives a title, one description string and a right slot, so every field after the
+first is prose joined by separators — and a value inside prose cannot be scanned down a column,
+which is the whole act the reader came to perform. The tell is a **superlative badge**: a "cheapest",
+"best" or "fastest" mark appears exactly when there is no column to read the answer off, so it is a
+workaround for the missing form rather than a feature, and it disappears the moment the value gets
+a column. The other tell is a per-row badge repeating a value the rows are already SORTED by — that
+is a section heading printed once, not a pill printed on every row.
+
+Reach for `ListItem` where the rows are heterogeneous and the reader picks one by NAME — settings,
+a menu of destinations, a detail row. Reach for a register wherever they share a field set.
+
+**Sibling surfaces must be the same form.** Two tabs of one dialog, or two panes of one screen,
+showing the same KIND of subject in different forms reads as an accident: a reader parses shape
+before meaning, and the difference tells them the two are unrelated when they are the same thing
+from two sources.
+
 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
@@ -692,6 +717,29 @@ not a row count, it is whether the neighbouring rows survive the expansion.
 | `bleed` (legacy) | square wash, `Divider`-separated | only an edge-to-edge data grid that genuinely wants hard rules |
 | `inset` | rounded (radius 8) | grouped lists in a padded container (Accordion drill-downs) |
 
+**A leading MARK in a column reserves its slot on every row, including the empty ones.** An
+avatar, a thumbnail or a status dot that only some rows carry gives that column two left edges —
+the marked rows indent by the mark's width, the placeholder sits on the column's own edge — and a
+column is scannable precisely because its values start in the same place. Hold the gutter open
+with an empty box of the mark's width. The header stays on the column edge, which is what a
+column with a leading mark looks like everywhere.
+
+**A register centres its cells, and that is right until a TRAILING CONTROL has to line up
+with one of them.** With a control in the row's gutter, centring puts it wherever the tallest
+cell leaves it — 10px below the field on one row and 27px on the next, so the controls stop
+forming a column; that register passes `align="top"`. Without one, keep the default: centring
+lets each cell's block sit in the middle of the row, so a one-line value beside a two-line
+neighbour reads as balanced rather than stranded at the top. **Removing the control is a reason
+to drop `top` again** — nothing breaks when you forget, it just looks slightly wrong forever.
+
+**The mechanism, for the `top` case.** Centring resolves per cell: the moment one cell is two lines its
+single-line siblings sit at a different height, and the trailing control — centred
+against the tallest cell — drops below the field it acts on, by an amount that varies
+with the data, so the controls stop forming a column at all. A caller cannot fix this
+(`alignSelf` on the control reaches the slot's own centring, one level below the row's),
+which is why it is a `Table` prop. A one-line row is pixel-identical either way, so
+passing it costs nothing and omitting it is invisible until a value grows a qualifier.
+
 **A washed row BLEEDS its wash; it never insets its content.** All three variants
 carry `marginHorizontal: -ROW_WASH_BLEED` absorbed by an equal `paddingHorizontal`
 — net zero for layout — so a row's content sits on its container's own edge,
@@ -947,6 +995,17 @@ action goes to the referenced record's own page; a local `Drawer` that re-shows
 just showed makes "Open" mean *read that again, wider*, and leaves the real record unreachable
 from the only control that promised it.
 
+**A detail surface never contains a register of its own SIBLINGS.** The list it was opened from
+is still on screen behind it, and `onPrev`/`onNext` already walk that list — so a "related records"
+table inside the panel is the third rendering of one set, and the reader has to work out whether
+the three agree. The trap is that it can be RIGHT when it is built and rot into this later: a
+register that folds many children into one row (a lane, an order, a person) genuinely hides them,
+and a table in the detail is then the only way to see them. Flatten that register to one row per
+child — usually a good change on its own — and the table silently becomes a copy of the rows it is
+covering, with nothing failing. **When a list changes what a row stands for, re-read every detail
+panel it opens.** Keep the VERBS such a section carried (a bulk action over the group is real work
+the register may not offer) and move them to the section they act on.
+
 **A record surface answers *which record is this* first — and the block that does it is SHORT.**
 Identity is the handful of facts someone would say aloud to name this record (its number and its
 counterparty, usually two); everything else is an ATTRIBUTE and belongs below the answer the
@@ -968,6 +1027,14 @@ ONE at a time, because two open details push the next row off screen. The bounda
 weight, not its field count: read or light-edit (independent inline commits) expands, a real form
 with a submit and cross-field validation still earns its own surface.
 
+**A column of always-open inputs makes a list look like a form.** An inline editor is a framed
+box, so a register that puts one in every row of its NAME column renders eight boxes down the left
+edge and reads as eight fields waiting to be filled rather than eight records to scan. It also
+gives the column two left edges — the frame's and the text's — which no amount of aligning the
+rest of the row recovers. Put the editors on the values a reader actually revises in place (a
+quantity, a price) and leave the SUBJECT as text; it edits in the expansion, which is where
+editing lives anyway. The tell is a screenshot: count the frames before you count the rows.
+
 The expansion carries **EVERY** field, including the ones already in columns. Column cells are
 read-only, and `table_fit` tier 2 drops droppable columns on the explicit promise that a door
 reaches the dropped values — the expansion IS that door, so anything it omits is unreachable.
@@ -1159,6 +1226,13 @@ by what KIND of thing they are.
   rides its section's HEADING row at the right edge — see § The add-placement law for why, and
   for the one-verb-one-weight rule that keeps it `primary` wherever it renders. (The
   icon-only `+` `IconButton` — a composer's attach — is a different thing and keeps its glyph.)
+- **Edit is never an icon.** A pencil is not a word: it does not say WHAT it edits, it reads as
+  decoration beside real controls, and in a row it competes with the values it sits next to. Use
+  a `secondary` `Button` with the verb. `IconButton` is for a verb whose glyph IS the universal
+  name of the act *and* whose surface has no room for a word — a close ✕, an overflow ⋯, a
+  composer's attach. Reserve the row's action gutter wide enough for the label rather than
+  shrinking the verb to fit the gutter; a control that toggles a disclosure names both states
+  (`Sửa` → `Xong`), because a label that stays put while its effect reverses is a lie.
 
 ## The action-gating law — disabled + the reason as a co-located Callout
 
@@ -1656,6 +1730,13 @@ tight, so only the subject carries the prop. Then the stack's own `gap` goes to
 line box already contributes 3px above and below, giving 6px between the two, and a `gap` on top
 is a third source of space between lines that are meant to read as one.
 
+**All three pieces above are one component: reach for `CellStack` (`title` + `caption`) rather
+than assembling a pair by hand.** They have to agree with each other, and a hand-rolled stack gets
+one of them wrong silently — the excess height comes from the LINE BOX, so there is no margin and
+no gap anywhere to explain it, and every spacing probe passes. It surfaces as "too far apart" and
+gets fixed by tightening a gap, which is a fourth wrong number. Two `Text`s in a `View` is the
+tell. → [catalog.md §"Lists, tables & registers"](./catalog.md).
+
 Running text keeps prose leading. The default is for paragraphs, and `.ui-markdown` renders at it.
 
 **A CONTROL riding a text line must not resize that line.** A control is taller than the text it
@@ -1687,6 +1768,16 @@ row that must not look the same on every row. A register of twenty people in one
 twenty identical circles, with the largest and most colourful thing in the row carrying no
 information.
 
+- **The GLYPH is derived from the DISTINGUISHING part of the name, which is not always the
+  first word.** `avatarInitials` takes a name's first (and last) letters, which is right for a
+  person and wrong for an ORGANIZATION: an organization's name opens with its legal form, so a
+  register of companies marks the same letter on every row — and it is the same failure the derived
+  hue was written to fix, arriving through the glyph instead of the ground. Strip the form from
+  both ends before the name reaches the mark, and use the stripped name for the row's TITLE too:
+  whatever eats the first letters of a mark is also eating the first 60px of the column beside it,
+  where the words that tell two customers apart fall off the end. The legal name belongs on the
+  record the row opens, not in the list. **A hue tally cannot see this** — the ground is seeded
+  from the whole name, so a screen of identical letters still measures as N distinct colours.
 - **The hue is derived, never passed.** A per-app or per-screen map is a second copy of something
   the name already determines, and it drifts. `avatar_tone` is pure, so one person is one colour
   on every screen and in every session — the value is never stored.
@@ -1876,7 +1967,22 @@ selection washes).
 
 **Count the chromatic grounds on a finished screen — the tally is the check.** One or two hues used
 many times reads calm and deliberate; ZERO reads like a spreadsheet; ten used once each reads
-cheap. A hue with a SINGLE member, from a family used nowhere else on the screen, is a library
+cheap.
+
+**A tonal column cannot encode more than about two categories, and the limit is measurable rather
+than a matter of taste.** The tints are the 50-step, and 50-steps of NEIGHBOURING families are
+nearly the same colour: sky/blue/indigo measure 1.9–4.5 ΔE apart, against a just-noticeable
+difference of roughly 2.3. So a hue per value across five or six values ships a column that LOOKS
+coded and is not — the reader still reads every label, and the palette has spent itself saying
+nothing. The families far enough apart to actually separate are the warm ones, which already mean
+danger and waiting, so reaching for them to distinguish a category makes every red on the screen
+ambiguous.
+
+Give colour the ONE split in the set that a reader must not get wrong — the one where two values
+are not interchangeable — and let the label carry the rest. Two hues used many times is the
+disciplined tally above; it is also the most the medium can carry. Where the values are ORDERED
+rather than categorical, `ramp` is the tool: one family, shaded, where the eye reads sequence
+without having to resolve hue at all. A hue with a SINGLE member, from a family used nowhere else on the screen, is a library
 default nobody chose — the giveaway is that the call site mentions no colour at all, so the shade
 arrived from a component's fallback rather than from a decision. Either give it siblings or take it
 back to a neutral.
@@ -1889,12 +1995,43 @@ colours on one screen: collect every element's `color` grouped by what it MEANS,
 holding more than one value — or any value serving more than one meaning — is the finding, whatever
 the sizes are.
 
-**Supporting text is `muted`, and a raw neutral in its place is the usual cause of the above.**
-`color="muted"` is the token that means "this supports something else"; a hand-written
-`color="zinc-500"` is a *different, lighter* neutral that typechecks, renders plausibly, and is
-already spoken for — components mute a DEPARTED or disabled subject to it. Reach for the raw shade
-and on a departed row the mute and the metadata come out identical, so the state stops signalling
-anything. Grep a component for a raw neutral on `Text` before trusting that it reads muted.
+**Supporting text is `muted`, and there is no raw neutral to reach for instead.** `Text`'s `color`
+is a set of ROLES — `default`, `muted`, `inactive`, `inverted`, `danger`, `warning`, `success` —
+and carries no palette names at all. That is not tidiness; a shade name in this position is wrong
+three ways.
+
+*It cannot know its ground.* A call site names a colour without knowing what will be painted under
+it, and the kit paints several things under text: white, a `zinc-50` hover, a `zinc-100` selected
+row. The retired `zinc-500` cleared AA on white by 0.33 (4.83:1) and **failed on the selected row**
+at 4.40:1, for text at `sm`/`xs` where the bar is 4.5. A role is resolved once, centrally, against
+the darkest ground the kit permits — which is why `muted` is `zinc-600` (7.03:1 at worst) and not
+the lighter step that looks tempting in isolation.
+
+*It splits one role across two inks.* Supporting lines under a VALUE were `muted` while a heading's
+`description` was a raw shade — one structural role, "the line that supports the thing above it",
+rendering in two colours decided by what happened to sit above it.
+
+*And it cannot be re-pointed.* An inverted ground, a denser surface, a dark theme — a role name
+moves, a name that states its own value becomes a lie. `inverted` is the proof the kit already
+leans on: if shade names were right it would be called `white`.
+
+**The vocabulary is TWO LAYERS, and only one is a decision.** `colors.zinc[600]` is a primitive —
+a value, owned by nobody, the same ramp anyone could paste. `TEXT_INK` (`@lotics/ui/text_ink`) is
+the semantic layer that says `muted` → `zinc.600`, and it is where the rule lives. Components
+address ink only through the second.
+
+Keep them separate even when the design tool wants shade names. A designer picking `zinc-500` and
+an author typing `zinc-500` look like one source of truth, but what they agree on is a THIRD-PARTY
+RAMP — the decision itself is written in neither, so it gets re-made at every call site, which is
+precisely how one role came to render in two inks. `textInkTokens()` emits both layers in the W3C
+Design Tokens format with the alias intact (`{color.zinc.600}`, never a flattened hex), which is
+what a design tool imports as an ALIAS variable. One file, both tools, and re-pointing a role moves
+them together.
+
+`inactive` is the one ink below the AA floor, deliberately — WCAG 1.4.3 exempts text in an inactive
+component, and a disabled label or an absent value is not content. Everything else is asserted by
+`text_ink_contrast.test.ts`, which iterates the vocabulary the `TextColor` type is DERIVED from, so
+a newly added ink is checked automatically rather than when someone remembers to add a case.
 
 **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"`
@@ -2061,9 +2198,10 @@ file and wrong on the screen. If something cannot be wrapped in `Text` (a raw `T
 axis), take the rung from `type_ramp` rather than picking a number.
 
 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).
+`semibold`. Colors are ROLES and there are seven: `default`, `muted` (all supporting text),
+`inactive` (a disabled control's label, and a value that is not there yet), `onInverse` (requires a
+dark ground — illegal on the canvas), and the valence set (`danger`/`warning`/`success`). No
+palette names — see §"Supporting text is `muted`" for why a shade in this position is wrong.
 
 ## Touch & whitespace
 

package/docs/data_entry.md

@@ -385,6 +385,14 @@ where it must stay strictly inside its box — that is `framed`. A DISABLED `fra
 box: it drops the border and fill so it cannot promise a press, but it stays in line with the enabled
 fields beside it.
 
+**A `framed` field in a RIGHT-ALIGNED column must be told to fill its cell.** It sizes to its
+content, and the column's alignment then pins each box's RIGHT edge while its left edge lands
+wherever that row's value happened to end — so a column of amounts reads as a ragged stack of
+boxes, worse the more the values differ in length. Nothing measures wrong: every box is correct
+on its own, no text clips, and the values ARE right-aligned. Give the cell's editor a full-width
+wrapper so one box width serves the column. (`bare` has the mirror constraint above and cannot be
+right-aligned at all.)
+
 **`bare` puts its whole affordance in the hover edge, so nothing may outrank that edge.** Pass the
 variant as a PROP; never express it as a resting `borderColor: "transparent"` in `style`, which is
 applied after the hover rule and erases the edge one line after it is computed. The failure is

package/docs/reviewing.md

@@ -553,6 +553,50 @@ back-load the meaning, so the half that survives is the half the reader already
 **Source-side signature:** a fit or stack decision that reaches for a control/usability constant
 (`MIN_CONTROL_WIDTH`, a flex minimum) where the thing being measured holds prose.
 
+### 8h. Which columns SURVIVE the narrow width
+**Collect** the header labels a register still renders at 375, and diff them against 1280.
+
+A register sheds columns by rank rather than overflowing, so the question is never whether it
+fits — it always does — but WHICH columns it kept. The signature of a wrong rank is a survivor
+list missing the column the register exists for: an amount register that kept a name and a status
+and dropped the amount. It is invisible at desk width, which is where it gets reviewed, and no
+probe that measures a wide screen can see it.
+
+Read the survivor list, not the ranks in source: an unannotated column takes a rank ABOVE every
+explicit one, so a set where "the important ones are annotated" sheds the unannotated column
+first — annotating some columns and not others is the failure, not the fix. If the register has
+more than one column, either all of them carry a rank or none do.
+
+### 8h-bis. A cell that grows a second line lifts its first
+**Collect** one column's first-line `y` MINUS its row's top, for every row; report the SET.
+
+A register centres its cells, so a cell's content straddles the row's middle: one line sits ON the
+centre, two lines straddle it, and the two states put the first line at different heights. A column
+whose cell is sometimes one line and sometimes two therefore does not form a line down the page —
+its figures drift by half a line on exactly the rows that grew a caption, which are the rows that
+had something worth saying. A constant non-zero offset is fine (a one-line column centred in a
+two-line row is correct); a SET with more than one value is the finding.
+
+Fixing the cell that grew only MOVES it — the neighbour that did not grow is now the odd one. Fix
+it by making the varying cell's height constant: render the optional line always, empty when there
+is nothing to say. It costs no row height wherever some other cell is already two lines tall.
+
+*Two traps in the fix.* A lone `" "` collapses in the web renderer and the reserved line silently
+loses its height — use a non-breaking space. And a caption WIDER than its column does not clip: it
+overflows into the neighbour, so two adjacent captions close up and read as one sentence. A column
+holding a sentence is sized by the sentence, never by the figure above it.
+
+### 8i. Row controls against a multi-line cell
+**Collect** each row's trailing control top and the top of the field it acts on; report
+the SET of deltas, not the average.
+
+A register's rows centre their cells, so a cell that grew a second line leaves its
+siblings and the trailing control at a different height. The signature is a delta set
+with more than one value — 10px on one row and 27px on another means the offset tracks
+the data, which is worse than a constant one because the controls no longer form a
+column. Non-zero-but-constant is the same defect with luckier data.
+
+
 ### 9. The absence pass — what catches "bland"
 Every probe above reads an element that EXISTS. None fires on a screen where nothing is wrong and
 nothing is right, which is the screen reported as bland. Defect-removal converges on *inoffensive*;
@@ -563,7 +607,10 @@ this converges on *distinctive*.
   ten used once each reads cheap.
 - **Identity marks** — on a screen whose subject is an entity, count them. Zero is the finding,
   and so is N identical: a mark that looks the same on every row carries nothing, and it is the
-  largest, brightest thing there.
+  largest, brightest thing there. **Tally the GLYPH and the GROUND separately**, and report the
+  size of the largest GROUP rather than the count of distinct values — the two halves are derived
+  by different rules and fail independently, so a set of marks can be five distinct colours and
+  five copies of one letter, which "5 distinct marks" reports as healthy.
 - **What does the screen DECIDE?** A register listing every row at equal weight has no point of
   view. Usually the real answer when treatment fixes keep not landing.
 - **What is inherently visual in THIS data?** Usually the data itself: identity marks, status
@@ -684,7 +731,9 @@ instead of one blended string.
 ```js
 () => {
   const SZ = { '12px':'xs','14px':'sm','16px':'md','18px':'lg','20px':'lg','22px':'xl','24px':'xl','28px':'xxl','32px':'xxl/xxxl','48px':'xxxl' };
-  const INK = { 'rgb(24, 24, 27)':'default','rgb(82, 82, 91)':'muted','rgb(113, 113, 122)':'zinc-500','rgb(161, 161, 170)':'zinc-400','rgb(255, 255, 255)':'inverted' };
+  // An ink the kit no longer has a NAME for is a finding, not a label: the
+  // vocabulary is default / muted / inactive / inverted + the valence set.
+  const INK = { 'rgb(24, 24, 27)':'default','rgb(82, 82, 91)':'muted','rgb(161, 161, 170)':'inactive','rgb(255, 255, 255)':'onInverse','rgb(113, 113, 122)':'OFF-SYSTEM zinc-500 (retired)','rgb(63, 63, 70)':'OFF-SYSTEM zinc-700 (retired)' };
   const out = [];
   const walk = (n) => {
     if (n.nodeType === 3 && n.textContent.trim()) {

package/examples/tpl_attendance.tsx

@@ -143,7 +143,7 @@ function HomNayRow({ nv, selected, onPress }: { nv: NhanVien; selected: boolean;
           <Avatar name={nv.ten} size="md" />
           <View style={{ flex: 1, gap: 2, minWidth: 0 }}>
             <Text weight="medium" numberOfLines={1}>{nv.ten}</Text>
-            <Text size="sm" color="zinc-500" numberOfLines={1}>{nv.chucVu}</Text>
+            <Text size="sm" color="muted" numberOfLines={1}>{nv.chucVu}</Text>
           </View>
         </View>
       </TableCell>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "47.6.0",
+  "version": "47.6.1",
   "type": "module",
   "exports": {
     "./accordion": "./src/accordion.tsx",
@@ -35,6 +35,7 @@
     "./capture_row": "./src/capture_row.tsx",
     "./card": "./src/card.tsx",
     "./card_select_item": "./src/card_select_item.tsx",
+    "./cell_stack": "./src/cell_stack.tsx",
     "./charge_lines": "./src/charge_lines.tsx",
     "./check_circle": "./src/check_circle.tsx",
     "./checkbox": "./src/checkbox.tsx",
@@ -275,6 +276,7 @@
     "./tabs": "./src/tabs.tsx",
     "./text": "./src/text.tsx",
     "./text_disclosure": "./src/text_disclosure.tsx",
+    "./text_ink": "./src/text_ink.ts",
     "./text_input_field": "./src/text_input_field.tsx",
     "./text_link": "./src/text_link.tsx",
     "./text_utils": "./src/text_utils.ts",

package/src/alert.tsx

@@ -180,7 +180,7 @@ class Alert {
               </Text>
             )}
             {message && (
-              <Text nativeID={messageId} size="sm" color="zinc-500">
+              <Text nativeID={messageId} size="sm" color="muted">
                 {message}
               </Text>
             )}

package/src/avatar.tsx

@@ -45,7 +45,7 @@ export function Avatar(props: AvatarProps) {
           userSelect="none"
           size={AVATAR_TEXT[size]}
           weight="medium"
-          color="inverted"
+          color="onInverse"
           accessibilityElementsHidden
           importantForAccessibility="no-hide-descendants"
           aria-hidden

package/src/avatar.web.tsx

@@ -53,7 +53,7 @@ export function Avatar(props: AvatarProps) {
           userSelect="none"
           size={AVATAR_TEXT[size]}
           weight="medium"
-          color="inverted"
+          color="onInverse"
           accessibilityElementsHidden
           importantForAccessibility="no-hide-descendants"
           aria-hidden

package/src/avatar_group.tsx

@@ -146,7 +146,7 @@ export function AvatarGroup(props: AvatarGroupProps) {
         >
           {/* The rung's own type — the same one initials take. A fixed size here
               is how a stack ends up with a 14px count beside 12px initials. */}
-          <Text size={AVATAR_TEXT[size]} weight="medium" color="zinc-700" aria-hidden>
+          <Text size={AVATAR_TEXT[size]} weight="medium" color="muted" aria-hidden>
             {`+${hidden}`}
           </Text>
         </View>

package/src/bar_chart.tsx

@@ -314,8 +314,17 @@ export function BarChart(props: BarChartProps) {
 }
 
 const styles = StyleSheet.create({
+  // CONTENT-SIZED; the HOST decides whether a chart stretches.
+  //
+  // This was `flex: 1`, which RN-Web resolves to a zero basis on the parent's
+  // MAIN axis. A card body is a vertical stack, so the chart's height resolved to
+  // nothing and it painted its fixed-height content centred on that — outside the
+  // card. Every consumer then had to neutralise it by wrapping the chart in a row,
+  // and getting that wrapper wrong is silent at one width and broken at another.
+  // `Funnel` and `Breakdown` were content-sized all along, so the family did not
+  // even agree with itself. A host that genuinely wants a chart to fill a box
+  // still says so, on the box.
   chartContainer: {
-    flex: 1,
     justifyContent: "center",
   },
   verticalChartWrapper: {

package/src/board.tsx

@@ -290,7 +290,7 @@ export function BoardColumn(props: BoardColumnProps) {
     <View ref={ref} style={[styles.column, over && styles.columnOver]}>
       <View style={styles.columnHeading}>
         <View style={styles.columnIdentity}>{heading}</View>
-        <Text size="sm" color="zinc-500" tabular>
+        <Text size="sm" color="muted" tabular>
           {count}
         </Text>
         <View style={styles.columnAction}>{action}</View>

package/src/button.tsx

@@ -13,7 +13,7 @@ import { colors } from "./colors";
 import { CONTROL_RADIUS, FOCUS_RING } from "./control_surface";
 import { Icon, IconName } from "./icon";
 import { Ref } from "react";
-import { TextColor } from "./text_utils";
+import { TextColor } from "./text_ink";
 import { useTooltip, UseTooltipOptions } from "./tooltip";
 import { useFocusRing, composeHandler } from "./use_focus_ring";
 import { getButtonIconColor } from "./button_colors";
@@ -119,7 +119,7 @@ export function Button(props: ButtonProps) {
               weight="medium"
               // `inverted` — the kit's own white-on-dark ink, the same token the primary
               // uses, so a brand button and the primary read as one family.
-              color={brand && !disabledOrLoading ? "inverted" : getButtonTextColor(color, disabledOrLoading)}
+              color={brand && !disabledOrLoading ? "onInverse" : getButtonTextColor(color, disabledOrLoading)}
               userSelect="none"
             >
               {title}
@@ -206,10 +206,10 @@ export function getButtonTextColor(color?: ButtonColor, disabled?: boolean): Tex
   // Disabled fades the label to the zinc-400 disabled ink on EVERY variant —
   // the washed background alone is a one-step tint nobody reads as disabled.
   // (The primary keeps inverted ink; its zinc-300 surface carries the wash.)
-  if (disabled) return color === "primary" ? "inverted" : "zinc-400";
+  if (disabled) return color === "primary" ? "onInverse" : "inactive";
   switch (color) {
     case "primary":
-      return "inverted";
+      return "onInverse";
     case "secondary":
       return "default";
     case "danger":