@lotics/ui 43.4.0 → 43.5.0

package/docs/composition.md

@@ -33,6 +33,26 @@ them produces off-system UI.
 | Register / work list / calendar | 1040 |
 | Wide wallboard / report | 1100 |
 
+**ONE LEFT EDGE — the whole page, and then the whole APP.** Headings, detail labels, prose, a
+table's first column, a footer's totals, a dialog's title. Then check the screen this one OPENS: a
+list and the record it opens are one reading column seen twice, and both must derive from ONE
+constant rather than happening to match today.
+
+The offender is nearly always a row that PADDED for its own hover wash instead of bleeding it
+(`ROW_WASH_BLEED`), which pushes its content in by the bleed while everything above it stays put.
+Fix the row, then DELETE the compensators that were added around it — once the row is right they
+become double-corrections, and they are the reason the edge drifts back the next time someone
+touches it. Two exceptions are legitimate and neither needs a fix: a self-contained overlay (a
+menu, a popover) has nothing to align with, and an indent that something VISIBLE occupies — a
+checkbox, an ordinal, an identity mark — is explained by the thing occupying it.
+
+**A row beat belongs to the PAGE, not to the row.** Collect every row primitive's height on one
+screen before calling any of them right — the kit's own defaults do not agree with each other,
+because each was picked for its own surface: `ListItem` is 64, a ruled `Table` row is 52, a
+`Button`-height control is 40. Stack three of those in one column and it reads as three rhythms,
+each defensible alone. The page picks one beat and the primitives take it (`minHeight` on the
+row, `spacing` on the table).
+
 ## 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
@@ -45,9 +65,21 @@ restyle a heading level per-page.
 | `###` | `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).
+- **Page band** — the screen's TYPE ANCHOR, and only secondarily a label. A register's own type
+  runs 12–16px, so a page without a band tops out around a **1.33x** range between its largest and
+  smallest text, and that reads flat no matter how much colour is on it — scale is the one
+  hierarchy device colour cannot substitute for. Restoring a `Text size="xxl" weight="semibold"`
+  title takes the same screen to ~2.7x. It also gives the page somewhere to land: without it the
+  first thing on the screen is a search input, which is chrome.
+  Yes, the title usually repeats the nav. Accept the repetition — a heading that names the screen
+  costs one line and buys the whole type range, and the alternative (inventing a title the nav
+  does not say) is worse.
+  **A second line carries LIVE STATE, never a gloss.** "Track each record's status and print the
+  right document for its stage" explains the WIDGET, and a band has no use for it. But a
+  register's counts are not that line either: they are the result of the TOOLBAR, so they belong
+  under it — see § Summaries.
+  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).
@@ -222,6 +254,43 @@ by WHAT THE SURFACE IS; never a raw `Pressable`.**
 | 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` |
 
+**ONE signal per species, and it has to be strong enough to carry alone.** `HOVER_BORDER` is
+zinc-500, not 400, because at 400 the shift was zinc-200 → zinc-400 on a 1px line — measurably a
+change and visually almost nothing, so the inline editors had grown a background TINT on top to
+compensate. That left two hover languages in one kit, and a reader crossing a record surface met
+both. Strengthen the shared signal rather than letting one control add a second; a control wearing
+two is the tell that the first one is too weak for everybody.
+
+**A themeable control derives EVERY state from its token — rest, hover, press, disabled.** The
+failure is a control that resolves `colors.primary` correctly at rest and then paints a fixed
+neighbouring zinc the moment it is touched, so a branded button turns grey under the pointer. Watch
+for an OPAQUE overlay especially: a `backgroundImage` gradient drawn over a themed
+`backgroundColor` hides it entirely while every token in the source reads correct. On web a token
+is a `var()`, so "the same colour, lighter" cannot be computed at the call site — use a translucent
+white/black overlay, which lifts any hue and cannot go stale against a palette it does not know.
+
+**A control changes PAINT across its states and never GEOMETRY** — and every property it paints
+has exactly ONE owner. Text that shifts on focus, a border that thickens, a ring drawn twice, a
+tint applied on one path only: each is two pieces of code owning one property and happening to
+agree at rest. It survives review because a resting screen is what gets looked at, and the second
+owner only speaks when the control is touched. The fix is to give the property one owner — a
+shared surface helper, a single frame kept across the view→edit swap — never to nudge the second
+owner into agreeing with the first, which leaves both in place for the next person to re-break.
+
+**A control riding a hoverable surface must be DARKER than that surface** — and you have to hover
+BOTH to see whether it is, because reaching the control means crossing its host. Equal washes
+vanish at exactly the moment they are pointed at; a control LIGHTER than its host reads as a hole
+punched in the row rather than as a target sitting on it. Neither failure is visible at rest, and
+neither is visible hovering the control alone, which is why a control that measures perfectly can
+still disappear in use. Take `ROW_CONTROL_HOVER` / `ROW_CONTROL_PRESS` (`control_surface`), which are a step past the
+row's own wash for exactly this reason; a hand-picked grey chosen against the resting row is the
+finding however plausible the value looks.
+
+**A SELECTED control needs a GROUND, not a heavier outline.** Among white pills a 1px border change
+is noise — it is the same signal hover already spends, one step stronger, so selection and hover
+compete instead of reading as different things. Selection changes what the box IS (a fill, a wash);
+hover changes how intensely it says it.
+
 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
@@ -264,8 +333,17 @@ objects — hairlines between them blur into one run-on list.
 | 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?, color?}…]}>` | BELOW the toolbar | a light inline line — a small `Metric` + muted label per item |
-| Register / list, with a SHAPE | `<Summary buckets={…}><Summary.Header>…</Summary.Header><Summary.Distribution/><Summary.Facts/></Summary>` | BELOW the toolbar | headline figure + distribution bar + the buckets named, all derived from one bucket list |
+| Register / list | `<SummaryLine items={[{label, value, tone?, compact?, trend?, info?, color?}…]}>` | BELOW the toolbar, above the rows | a light inline line — a small `Metric` + muted label per item |
+| Register / list, with a SHAPE | `<Summary buckets={…}><Summary.Header>…</Summary.Header><Summary.Distribution/><Summary.Facts/></Summary>` | BELOW the toolbar, above the rows | headline figure + distribution bar + the buckets named, all derived from one bucket list |
+
+**A summary goes BELOW the controls that produce it.** Its figures are the result of the toolbar —
+they move every time the reader touches a filter — so the layout has to state that order: set the
+query, then read what it returned. Above the toolbar the screen answers before it has been asked,
+and the numbers change behind the reader's eye while they are still choosing.
+
+It is not the page band's subtitle either, for the same reason. A subtitle describes the SCREEN,
+which does not change; these describe the QUERY, which the toolbar just rewrote. The band carries
+the title, and the summary sits under the controls, immediately above the rows it counts.
 
 `SummaryLine` is `Summary`'s `Facts` row on its own — reach for the compound when the set has a
 distribution worth drawing, and for the bare line when it is only a few aggregates. A
@@ -445,8 +523,9 @@ Two corollaries, both counter-intuitive enough to state:
 - **Shrinking a NEIGHBOURING cell does not fix it.** The spread is a function of the varying
   cell's own range, not of the row's height: a 20/42 cell spreads 11px in a 52px row and 11px in
   a 68px one. Only bounding the cell that varies removes it.
-- **The fix is never a cross-axis knob.** `Table` has no `align` (see MIGRATION 32.0.0): topping
-  the cells leaves the chrome centred, so the row reads as scatter instead.
+- **The fix is never a cross-axis knob.** A column's `align` is horizontal (`"left"`/`"right"`,
+  for a money column); there is deliberately no VERTICAL one, because topping the cells leaves
+  the chrome centred and the row reads as scatter instead.
 
 Bound a cell by giving every row the same content, not by hoping the data is uniform. A line that
 appears only when its field is set is the defect; RESERVING the line is the fix — **but only when
@@ -987,6 +1066,249 @@ a pointer. `PressableHighlight` and `FocusRingPressable` set the arrow for every
 on them (`CURSOR_DEFAULT`); a component on the bare `Pressable` sets it itself, and the few
 that act set `CURSOR_ACTION` back over the top.
 
+## The register's rhythm — no rule between rows, one under the band
+
+A register's rows are separated by their own height and a small gap. The only mark a row makes is
+the rounded wash it paints when you point at it. There is no hairline between rows and no way to
+ask for one.
+
+| | |
+|---|---|
+| Between rows | nothing — 4px and their own height |
+| Under the column band | a hairline (`colors.border`) |
+| Row height | 72, overridable per row with `TableRow`'s `minHeight` |
+
+**WHAT a line separates is the whole test — not how big the break feels.** A rule between two rows
+divides LIKE FROM LIKE, and the space between them already says that. The band's rule divides
+CHROME from CONTENT — a row of labels from the records they name — and no amount of whitespace
+states that, because whitespace is what already separates the rows from each other. Removing it was
+tried on a real register and the column band floated: with nothing beneath them the labels read as
+a first row rather than as the header of the rest.
+
+Drawing both makes them compete, and a grid of equal lines is most of what "it looks like a
+spreadsheet" means.
+
+**The hover wash does the work the rule did**, and it already has the shape: `PressableRow` bleeds
+its ground past the content and rounds it, so a register reads as a stack of cards with no card
+component involved. That is why dropping the rules does not make rows ambiguous — the separator
+moved from a permanent line to a pointer-following one. The row has to be tall enough for that wash
+to read as a surface rather than a stripe, which is what the 72 buys.
+
+**Density is a number, never a mode.** A surface that genuinely needs more rows on screen sets
+`minHeight` on the row. What no caller can ask for is the rules back — and that is deliberate,
+because a table of VALUES rather than of objects is a different component: `Matrix` for a numeric
+grid (a statement, a pivot, a rollup), `DataGrid` for a compact one. The distinction the two
+rhythms used to express already lived at the component boundary; offering it again as a prop was a
+third way to say the same thing, and the way that let a register contradict this rule.
+
+## A register that TRIAGES — `TableGroup`
+
+A flat register sorted by a column hands the reader every row at equal weight and leaves the
+deciding to them: "which of these needs me today" is answered by reading all of them. `TableGroup`
+moves that decision into the screen — a titled band of rows with a count.
+
+**Group by what implies a different ACTION, never by a category the reader can already see.**
+Bands like *Waiting on you* / *Gone quiet* / *Open* / *Closed* each name a different response, so
+the grouping tells the reader something no column does. Grouping by a value that is already a
+column is a sort wearing chrome: it spends a band per value to repeat the cell beside it.
+
+- **Order the bands by how much they need the reader NOW**, not alphabetically and not by size. A
+  register is read top-down, so the first band is the answer to "what do I do today".
+  A stated next step outranks silence — it is a commitment already made, and it names the work.
+- **An empty band renders nothing**, never an empty heading: a title over no rows states a pile
+  that is not there.
+- **At most one band carries a dot.** A valence mark on every band is decoration; on the one band
+  whose urgency comes from a CLOCK rather than from something someone wrote down, it is a signal.
+- **Air separates bands, a hairline separates rows.** The band boundary is the largest break
+  inside the register and the row rules are the smallest — drawing both as lines makes them
+  compete and the grouping stops reading. No rule under a band heading either; that orphans the
+  title from the rows it opens.
+- **Ordinals restart inside a band** where they are shown: the reader's question there is "which
+  of these", not "which of all".
+- **Watch the ratio of headings to rows.** Four bands over ten rows is a lot of chrome for a
+  little content, and the shape only pays off as the register grows. A register that will never
+  hold more than a screenful is usually better flat.
+
+Banding also changes what the COLUMNS have to carry, and the check is worth running afterwards: a
+column that exists to signal presence ("is there a next step?") is now stated by the band, so it
+is left carrying only its text — and it will be empty in every band but one. That is not
+necessarily wrong (which pile against what specifically), but it is a new duplication to look at.
+
+## The register's own craft — what "it looks like a spreadsheet" actually is
+
+Three defects produce that report, none of them about colour, and all three measured on a shipped
+screen that had already passed a design audit. (The fourth was drawing a line between every row;
+that one is settled above — a register has one line, and it is the band.)
+
+**A column header is a LABEL at the body size** — `sm` / `muted` / `medium`, matching the values
+it heads in size and separating from them by weight and ink. It is not an eyebrow: an eyebrow is
+`xs`, calibrated to sit quietly beside a value it captions, and a column header names a whole
+column of them. Dropped to `xs` and lightened past `muted` it stops being legible and starts
+reading as a caption that lost its value — small type is not the same as quiet type. The active
+SORTED column steps up in ink, never in weight; semibold belongs to the heading ladder.
+
+**Sentence case, in the table header too.** The heading ramp already bans all-caps and names it
+the #1 templated tell; `Table` and `SortHeader` were uppercasing every column label in every app,
+which is the loudest possible version of the thing the rule exists to stop. Removing the case
+without replacing the separation is what left the header looking adrift — the ink step above is
+the replacement, and the two changes only work together.
+
+**A row's SUBJECT is `medium`, never semibold.** Semibold is the heading ladder's weight — `#`,
+`##`, `###` are all semibold — so a register whose row subjects are semibold renders its content
+at heading weight once per row, in the same font CUT as the page title (`Inter_600SemiBold` is a
+separate file, a heavier stroke than the number suggests). The subject leads by SCALE instead: one
+size step above the values beside it. Moving size and weight together is one step too many.
+
+**A supporting line is ONE RUNG BELOW the line it supports — never a fixed size.** A `md` subject
+over an `xs` caption is a 16→12 drop, while the same shape in the next column drops 14→12; the
+wider pair then reads as though its second line shrank rather than stepped. Pick the rung
+relative to the primary and the pair scales together. The probe: collect every primary/supporting
+pair on the screen and divide. A spread in the RATIOS is the finding, not a spread in the sizes.
+
+**A CONTROL riding a text line must not resize that line.** A control is taller than the text it
+sits beside — a 24px `CopyButton` on an 18px `xs` line — so a flex row containing both is sized by
+the CONTROL, and `alignItems: "center"` then spends the difference above the text. The line's text
+starts lower, and the pair reads with a wider gap than the identical pair one column over that
+happens to carry no control. Measured on a register: 5px under the name against 2px under the
+figure beside it, from one `gap: 2` shared by both.
+
+It is invisible in review because every number is defensible — the gap is right, the rungs are
+right, the control is the documented size — and the defect is the interaction between them. It is
+also the harder half of *same shape, same treatment*: the reason for the difference is real, and a
+reader cannot see it.
+
+Pin the row to the TEXT's line box (`height` = the rung's leading) and let the control overflow it.
+The hit area is unchanged — it paints outside the box rather than growing it — and the text sits
+where it would if the control were not there. The same applies to any verb riding a value: a
+`CopyButton`, an `InlineButton`, a count chip.
+
+## Identity marks — a mark that is the same on every row carries nothing
+
+`Avatar` derives its ground from the NAME (`avatar_tone`), and takes `shape="circle" | "square"`
+— a person or an organization.
+
+**The shape varies only where the surface MIXES entity types** and the reader acts on which is
+which: a search result holding both people and companies, a "related records" list, a picker over
+two directories. On a surface whose rows are all one kind of thing — a register of records, a
+roster, a list of accounts — pick ONE shape and hold it. The distinction is real, but a reader
+does not act on it there, and a column of mixed circles and squares reads as an inconsistency
+rather than as information. That is the general form: a structural device asserts a difference,
+and asserting one the reader cannot use costs more than it gives.
+
+Both exist for the same reason: the mark's entire job is making a row identifiable at a glance,
+so it is the one element in the row that must not look the same on every row. A register of
+twenty people in one accent colour is twenty identical circles, with the largest and most
+colourful thing in the row carrying no information; and a register of companies drawn with a
+person's disc asserts they are the same kind of entity, which the column header alone has to
+correct.
+
+- **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.
+- **A palette of identity hues is ordered by CONTRAST, not by spectrum.** Listed by hue, six
+  consecutive entries are six shades of one purple, and any two names hashing to adjacent buckets
+  look identical. Interleave. This is invisible to every count-based test — a hash returning seven
+  distinct buckets still renders six neighbouring purples — so it is checked by eye, on real
+  names from the language the app actually runs in.
+- **A person is never `red` or `amber`.** Those mean danger and waiting everywhere else, and a
+  palette that can paint someone red makes every red on the screen ambiguous.
+- **Every register row should carry a LEADING MARK, best effort from the data.** An avatar, a
+  logo, a thumbnail, a file badge, a coloured initial — something the eye can aim at without
+  reading. A register whose rows open with text starts flat, and the symptom is reported as
+  anything but the cause ("that avatar looks too small", "it looks plain"), because a missing
+  element is invisible by definition. A person gets initials; an account gets the squared mark; a
+  record with no likeness of its own borrows the identity a reader actually scans for — a deal
+  takes its account's mark, since "whose deal is this" is the question being asked of the list.
+  Only rows with genuinely no identity are exempt: a list of amounts, a log of events.
+- **The rung follows what the row is ABOUT**: `lg` where the entity is the row's subject, `md`
+  where it is one field among columns (see `avatar_size`).
+
+The brand did not lose a home when the disc stopped carrying it — it moved to chrome, below.
+
+## Character comes from the DATA — the answer when a screen reads "bland"
+
+Every rule above removes a defect. None of them ADDS anything, so a screen can pass all of them
+and still be reported as plain, boring, or unfinished — which is a different complaint with a
+different fix. Removing defects converges on *inoffensive*; these three questions converge on
+*distinctive*.
+
+- **What is inherently visual in THIS data?** Work software has no photography, so the data itself
+  is the imagery: identity marks (above), status colour, file-type badges, sparklines, proportion
+  bars, tabular figures aligning down a column. Every one of these is information first and
+  decoration never — which is why they are the only kind of visual interest that survives contact
+  with a real dataset. Reaching instead for a gradient, an illustration or a hero band adds weight
+  without adding a single fact.
+- **What does the screen DECIDE?** A register listing every row at equal weight has no point of
+  view: it hands the reader the same undifferentiated wall the query returned. A screen with a
+  point of view puts what needs attention first (`TableGroup`), spends its one accent on where the
+  reader is, and lets everything else recede. This is usually the real answer when treatment fixes
+  keep not landing.
+- **What makes this belong to THIS product?** Default typeface, default greys, default accent,
+  default control shapes is a *well-built generic screen*, and no further polish changes that. The
+  fix at that point is a theme (`applyLoticsTheme`), not another treatment pass — and knowing
+  which of the two you are looking at saves a great deal of pointless nudging.
+
+Type SCALE is the fourth, and it belongs with the others: range = largest ÷ smallest across the
+screen, and under about 2× reads flat *at any amount of colour*. Scale is the one hierarchy device
+colour cannot substitute for. A register with no page band tops out near 1.33×.
+
+## Where the accent goes — "where you are", and nothing else
+
+`colors.accent` paints the state that answers **where the reader is** on a SURFACE: the selected
+row's ground (`accent_wash`), an active filter. It never paints DATA — a status, a series and a
+valence all come from a palette family, so an accent can never overwrite a meaning — and it never
+paints the focus ring.
+
+**A page-scale position marker takes `primary`, not `accent`** — an active tab's underline is the
+case. `primary` is already the ink the kit spends on "this is on": a checkbox's fill, a switch's
+track, a picked option's tick, the one primary button. An active tab is the same claim at page
+scale, so it belongs to the same ink, and the rail then sits at the same weight as the CTA it
+shares a screen with. Painted in `accent`, an unthemed screen gets exactly one blue thing on it —
+a single-member hue from a family used nowhere else, which is the definition of a library default
+nobody chose (see § Color discipline), three pixels from a near-black button.
+
+The line between the two: `accent` marks WHICH OF THESE (a row among rows, a filter among
+filters), `primary` marks THIS IS ON (a control's state, the section you are in).
+
+`accent_wash` is derived from `accent`, not chosen beside it. The two used to default to blue-600
+and zinc-100 — one token pair disagreeing with itself, so every app that themed nothing got a
+colourless "you are here".
+
+**Selection and hover must not share a wash.** They did, and the register's one piece of
+persistent state was erased by a transient one: the row whose record is open looked exactly like
+the row under the pointer. Hover is neutral and lighter (it answers "you can press this"),
+selection carries the accent.
+
+### Theming is an app-level ESCAPE HATCH, not a product surface
+
+An app sets its own identity in its own code — `applyLoticsTheme({ … })` once at boot, before
+`mount`. **Nothing in the platform writes a theme**,
+there is no settings screen for it, and `apps.theme.color` is the LAUNCHER ICON's colour and
+nothing else. Read that as the boundary rather than as a gap waiting to be filled: the mechanism
+exists because a customer occasionally needs their own typeface, not because theming is a feature
+we sell.
+
+**What makes it possible is small and load-bearing.** `colors.web.ts` reads five roles through a
+CSS variable with the kit's own value as the inline fallback, and `font_family.web.ts` does the
+same for the three weight rungs. That indirection is the ENTIRE mechanism — and it cannot be
+replaced by wrapping a component and passing styles down, which is the intuition to check before
+reaching for it. React Native Web writes `fontFamily` onto every `Text` element itself, so a
+wrapper's font has nothing to inherit into; and `background-color` and `border-color` do not
+inherit in CSS at all, so no ancestor can reach a `Button`'s fill or a `Table`'s hairlines. The
+only alternative to the variables is passing `style` at every call site, which is a fork rather
+than a theme.
+
+**Prefer `applyLoticsTheme` over declaring the variables by hand**, because two of the values are
+DERIVED and getting either wrong fails quietly: `accent_wash` is the accent at 7%, and one
+`bodyFont` has to reach all three weight rungs or the medium and semibold runs stay in the kit's
+own face and the screen reads as a font that half-loaded.
+
+**It is a function, not a provider**, and the shape follows from what theming IS: an app declares
+one identity at boot and never changes it. A React component bought a memo, a wrapper element, a
+layout effect, a restore-on-unmount and a context nobody read — all of it lifecycle for a value
+with no lifecycle. Calling it before `mount` is also strictly better than a provider could be: the
+variables are in place for the FIRST paint, where a provider's effect ran after one.
+
 ## Color discipline — solid / tint / ramp + ONE accent
 
 Every status / data-viz / accent color comes from a NAMED helper (`@lotics/ui/colors`), never a
@@ -1003,6 +1325,13 @@ accent per screen purpose** (blue = pipeline, emerald = money, red = danger, amb
 Direct `colors.*` access is reserved for NEUTRALS (`zinc`, `border`, `white`, the `*[50]`
 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
+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.
+
 **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
@@ -1069,6 +1398,22 @@ them on a shared baseline — the symptom is usually reported as "the alignment
 The check is cheap and worth running whenever a component takes a size: render the small rung and
 measure the TEXT inside it, not the box. If the text did not move, the prop is only half wired.
 
+**SMALL is not QUIET.** When a label reads wrong, check whether someone made it smaller *and*
+fainter to make it recede — that trades legibility for quiet, and it usually causes the very
+complaint it was meant to fix, because a reader who cannot read a label reports the block as
+cluttered rather than as small. Recede with INK, at the same rung. `xs` is for genuine meta (a
+timestamp, a count), not for a label that a person actually has to read.
+
+**A LABEL sharing a row with a flexible VALUE must be told which one gives way.** Two items in one
+flex row, and whichever cannot shrink forces the other to. A value floored at its longest
+unbreakable word leaves the label absorbing every remaining pixel — collapsing to a
+one-character-wide column many times taller than the row it names. It is invisible wherever the
+values happen to fit, which is usually the width it was built at, and it appears the first time a
+real record carries a long one. Decide deliberately: `flexShrink: 0` on the one that must stay
+whole (a fixed-length key, a label), `flexShrink: 1` + `numberOfLines` on the one that may clip,
+and pick by which is still USEFUL truncated — `RC-2026-0…` is unusable, `(555) 384-7…` is still
+recognisably a phone number.
+
 
 
 Only the `Text` primitive (`size` / `weight` / `color` / `transform` / `tabular` / `level` for
@@ -1076,7 +1421,7 @@ semantic heading rank). Uppercase tracking is built into `transform="uppercase"`
 `letterSpacing`.
 
 On web, the heading sizes are **responsive** at the 768px viewport breakpoint (the kit's screen-size
-boundary); native uses the base column:
+boundary); native uses the base column, because a phone is a phone:
 
 | `size` | base / native | web ≥ 768px | Role |
 |---|---|---|---|
@@ -1088,7 +1433,22 @@ boundary); native uses the base column:
 | `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` /
+**Leading and tracking are baked per rung — never set either by hand.** Both curves live in
+`type_ramp.ts`, and the rungs carrying running text sit at PROSE leading (14/24) so a typed note
+and the same note rendered as markdown read at one rhythm. Tracking is negative at every rung and
+steepens as the type grows — nothing in the kit tracks positive except `transform="uppercase"`,
+which compensates for the caps itself.
+
+A hand-set `letterSpacing` is a finding wherever it appears, and it fails in a specific way: it
+looks like a local decision and is actually a second copy of the curve. Three of them shipped
+before this was written — a private size→tracking table on `Metric` that put the product's
+summary figures at ZERO while the sentence beside them tracked -0.48px, a flat value on `Text`
+itself that was the whole of native's tracking, and `+0.3` left on a column header after its size
+and weight had been corrected. Each was defensible in its own file and wrong on the screen. If
+something cannot be wrapped in `Text` (a raw `TextInput`, a chart 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).
@@ -1193,6 +1553,17 @@ that praises it is marketing.
   a middot is usually a substitute for. Facts of two different KINDS want two lines, not one
   line with a glyph between them. (Verbatim quoted DATA keeps its own delimiters — this governs
   copy we write, not text we reproduce.)
+- **STRUCTURE MUST ENCODE SOMETHING TRUE.** Every structural device is an assertion, and a false
+  one is decoration that costs more than it gives. A rule asserts *these are separate*; an eyebrow
+  asserts *this labels what follows*; a number asserts *there is an order the reader needs*; a
+  badge asserts *this is a state*; a colour asserts *this differs in kind from its neighbour*.
+  Numbered markers on a set nobody traverses in order, a divider between two things that belong
+  together, a coloured pill on a city — each reads as information and carries none, and the cost
+  is paid by the devices that ARE telling the truth, which get discounted along with it.
+- **One job per element.** A label labels, an example demonstrates, a caption qualifies. Nothing
+  quietly does double duty — and a SHORTENED element still has to justify existing, because
+  trimming makes it pass every length check while leaving the question of whether it earns its
+  place unanswered.
 - **Plain language over jargon; effect over mechanism** ("Record visibility", not "Row-Level
   Privacy") — if a term needs explaining, replace it. **One concept = one word everywhere** —
   pick the term once and reuse it on every surface.

package/docs/data_entry.md

@@ -75,6 +75,31 @@ message on a `touched` flag set `onBlur`, keep the commit gated on the real vali
 showing error clear live as the value becomes valid — the shape [`useForm`](../src/use_form.ts)
 already has: errors arrive from a validate pass, and editing a field clears that field's error.
 
+## A picker over a select FIELD keeps the field's colours — `optionPicker`
+
+    <InlineSelect {...optionPicker(fields.status?.options ?? [])}
+                  value={statusKey} onSave={(v) => save({ status: v })} />
+
+Spread it into `InlineSelect`, `Select`, `OptionList` or `Combobox` — it supplies both the
+`options` and the `renderOptionContent` that paints each one.
+
+**The obvious call site throws the colour away, silently.** A picker takes `{ value, label }`, so
+every app writes `options.map((o) => ({ value: o.key, label: o.label }))` — and `color` is not in
+that shape, so it never arrives. Nothing errors and nothing looks broken; the value simply renders
+as a coloured chip in the register and as bare grey text the moment someone goes to CHANGE it,
+which is backwards. Recognition matters most in the list you are choosing from, and a filter
+popover of identical grey rows makes the reader match text where they could have matched a colour.
+It is worth grepping for: the mapping is boilerplate, it looks correct, and one CRM had thirteen
+of them.
+
+The mapping and the renderer ship together deliberately. Returning only the options would leave
+each caller to write the `renderOptionContent` that reads `data`, and an app that mapped correctly
+but forgot the renderer lands back on grey text with nothing to indicate why.
+
+Default `dot`: a picker row is a place to READ a set of choices, and a stack of filled pills is
+heavier than the list describing them. Pass `{ variant: "tonal" }` where the selected value is the
+surface's one prominent status.
+
 ## Inline edit — the preferred way to edit an existing record
 
 When the whole record is editable (a detail/record screen, dense settings), don't wrap it in a