@lotics/ui 43.4.0 → 43.5.0

package/docs/reviewing.md

@@ -0,0 +1,477 @@
+# Reviewing a screen you built
+
+The other docs say what good looks like. This one says how to find out whether you achieved it.
+
+That gap is the reason this file exists. An agent cannot see the screen it just wrote any better
+than it can see a bug it just introduced — "it looks fine" is the same claim as "it should work",
+made with the same evidence. Every rule in [composition.md](./composition.md) was written the last
+time it was broken, by someone who had read it. So the discipline is not *know the rules*, it is
+**render it, measure it, and let the numbers say whether the rules held**.
+
+Everything here is about a screen **that already renders**. Building one starts at
+[catalog.md](./catalog.md) (which component) and [templates.md](./templates.md) (which shape).
+
+---
+
+## The method
+
+**"Looks off" is a hypothesis, not a finding.** An impression cannot be compared across a screen
+or re-checked after a fix. Extract computed values and let the table show the defect. Every
+finding cites numbers.
+
+1. **Render it** — `lotics app dev` for an app, a preview route for a screen. Drive it with
+   browser automation that can evaluate JS in the page.
+2. **Run the two gates**, then the probes.
+3. **Fix, then re-measure.** A design fix is verified the way it was found.
+4. **Screenshot too.** Numbers say *what* is wrong; a picture says *that* something is, and some
+   defects live only in the picture — a mark floating over a tile that never loaded measures
+   perfectly and is obviously broken on sight. Take it even when the numbers are clean.
+
+**Map raw CSS back to the ladder as you go.** A finding reads as `xs/500/muted`, not
+`12px/500/rgb(82,82,91)`, so the treatment classes are visible at a glance. The rungs are in
+[`type_ramp`](../src/type_ramp.ts); above 768px `lg`/`xl`/`xxl`/`xxxl` are 20/24/32/48 and below
+it 18/22/28/32, so the same rung reports different pixels at the two widths — resolve against the
+width you are measuring.
+
+**Widths: measure at 1280 and 375.** Treatment bugs are width-independent on a screen that merely
+REFLOWS — but a screen that FORKS (`useScreenSize().small`, a container query, a different
+component per bucket) is a second screen running code the other width never executes, so a plain
+defect can sit there forever while every measurement at the other width passes. Audit each fork as
+its own screen.
+
+**Read the width the component actually RECEIVES, never the viewport you set.** A gallery or docs
+shell wraps it in its own nav, so "1280" may be rendering at 1060 and every conclusion is wrong in
+the same direction. The kit measures the CONTAINER, not the screen — see AGENTS.md, Iron rules.
+
+---
+
+## Two gates, before any probe
+
+A perfectly-treated element that should not exist still measures clean, and a wrong control cannot
+be treated into a right one. Both of these are cheap and both outrank everything below.
+
+### 1. SUBTRACT
+
+Per element, ask what QUESTION it answers and who is asking. A value nobody compares across rows
+is not a column; a figure the summary already totals does not need repeating per row; a fact
+derivable from its neighbour is a second copy that can disagree. Cut it, then re-ask whether the
+screen got worse.
+
+*The tell that you are subtracting too little:* reaching for a smaller size, a tighter gap, a
+truncation or an abbreviation — each makes the excess harder to read instead of removing it.
+"Cramped" is almost always COUNT, which no width fixes.
+
+*Then count FACTS, not elements:* three well-made blocks all reporting that someone was absent is
+one fact three times. → [composition.md](./composition.md) §"Touch & whitespace" (the trim test).
+
+### 2. RIGHT CONTROL
+
+Name each control's SPECIES and justify it — against the ladder in
+[data_entry.md](./data_entry.md) §"Choosing a CHOICE control" (by option count, not taste), then
+against the `tpl_*` that already solved this shape.
+
+A boolean is a switch, not a popover holding one checkbox. An exclusive choice belongs only where
+the states really are exclusive — *independent capabilities that happen to be exclusive today*
+bake today's combinations into the type. And check the species is not furniture from another
+ALTITUDE: a list-row disclosure nested in a list row, a section header serving as a field label.
+Each reviews clean in isolation and reads as clutter in place.
+
+---
+
+## The probes
+
+Each names what to COLLECT and the SIGNATURE — what the numbers look like when it is wrong. The
+rule behind it lives in the area doc named beside it; this file never restates one.
+
+### 1. Type inventory
+**Collect** every text node as `rung / weight / ink`, with a sample of what wears each.
+
+- **Range** = largest ÷ smallest. Under ~2× reads flat *at any amount of colour* — scale is the
+  one hierarchy device colour cannot substitute for. A register with no page band measures ~1.33×.
+- **Weight is a font FAMILY here, not an axis.** Semibold is a separate, genuinely heavier file,
+  and the heading ramp is semibold at every rung — so semibold on a row subject, a value or a
+  label renders content at heading weight. State steps up in INK, never into the heading weight.
+- **Same shape → same treatment.** Group every element by its visual SHAPE (label-over-value,
+  figure+caption, icon+row, chip) and check each group has ONE treatment. A reader parses shape
+  before meaning, so an unexplained difference reads as an accident however principled the reason.
+- **Singletons.** A rung/weight/ink combination appearing ONCE either wants siblings or wants to
+  join an existing class. Pick the sibling set by STRUCTURAL ROLE, not visual resemblance.
+- **Pairs.** For every primary+supporting pair, divide. A spread in the RATIOS is the finding, not
+  a spread in the sizes.
+- **A label sharing a row with a flexible value: measure the LABEL across rows whose values differ
+  in LENGTH.** Whichever of the two cannot shrink forces the other to, so a value floored at its
+  longest word leaves the label absorbing every pixel and collapsing to a one-character column
+  many times taller than the row it names. Invisible wherever the values happen to fit — usually
+  the width you audited. The signature is the label's box CHANGING SHAPE row to row: collect width
+  and height per row and treat a spread as the finding, never the average.
+- **Shrunk composites.** Where a component is sized by its container rather than its own scale,
+  measure the type INSIDE it, not the box — a badge dropped into a cell can scale its own label to
+  five pixels, internally consistent and invisible to every treatment probe. The fix is rarely a
+  bigger box; ask what the thing IS on that surface. But separate unreadable TYPE from unreadable
+  MARK before ruling: a badge's label never reaches the ladder at any row-scale size, so 5px
+  proves only that you measured a mark.
+
+→ [composition.md](./composition.md) §"Typography", §"The heading ramp".
+
+### 2. Ground, border and radius across siblings
+**Collect** `background-color`, `border`, `border-radius` and height for every control in a group.
+
+- **A singleton ground is a finding**, like a singleton type treatment: four buttons at `h=40`
+  with identical type, three with a ground and the destructive one transparent. Readers parse
+  box-vs-no-box before colour.
+- **A SELECTED control needs a GROUND, not a heavier outline** — among white pills a 1px border
+  change is noise.
+- **Tally chromatic grounds.** Disciplined is one or two hues plus greys. A hue with a single
+  member, from a family used nowhere else, is a library default nobody chose — the call site
+  usually mentions no colour at all.
+- **A control riding a hoverable surface must be DARKER than it** — and hover BOTH to see it,
+  since reaching the control means crossing its host. Equal washes vanish exactly when pointed at;
+  a LIGHTER one reads as a hole rather than a target. Neither is visible at rest or when hovering
+  the control alone. `ROW_CONTROL_HOVER` / `ROW_CONTROL_PRESS` in `control_surface` are a step
+  past the row's own wash for exactly this; a hand-picked grey is the finding however plausible.
+- **A pressable that does not NAVIGATE must not wear navigation ink.** Blue underlined text
+  promises a destination; a control opening a modal, a peek or an inline expansion is not one.
+- **A semantic token passed where a raw value is expected fails SILENTLY and typechecks.** A prop
+  typed `color?: string` takes a CSS colour, not a design token, so `color="muted"` is an invalid
+  colour and the element falls back to full-strength ink while the compiler stays quiet. Diff the
+  computed `color`/`stroke` against the token you INTENDED, using neighbouring text that carries
+  the real token as the control.
+- **A control drawing NOTHING at rest is text**, not a quiet control. Collect every pressable's
+  RESTING `background-color`, `border-width` and `text-decoration`: all three empty means the only
+  affordance is the hover wash, which is invisible to keyboard and touch. It measures perfectly
+  and has a real focus ring; what fails is that nobody presses it.
+
+→ [composition.md](./composition.md) §"Color discipline", §"Buttons & action labels", §"Every number is a door", §"Hover grammar".
+
+### 3. Rules — ask what each one SEPARATES
+**Collect** every border/divider with weight, colour and width.
+
+The test is not how big the break is. A rule between two rows divides **like from like** —
+whitespace says that just as well, which is why a register can drop every internal rule and read
+calmer. A rule under a column band divides **chrome from content**, and whitespace cannot say
+that, because whitespace is already what separates the rows. Delete the like-from-like ones
+however important the break feels. Backwards produces both failure modes: a grid of equal lines
+that reads as a spreadsheet, and a lone survivor that becomes the loudest thing on a quiet surface.
+
+Also: **the most important break must never be tighter than a routine one** — a hand-rolled rule
+beside a `SectionStack` is the usual cause.
+
+→ [composition.md](./composition.md) §"The register's rhythm".
+
+### 4. Gaps — measure RATIOS, not sizes
+**Collect** the gap WITHIN a group and BETWEEN groups, and divide. Near 1 is the defect however
+reasonable each number looks alone — 10px inside and 12px between measures fine twice and still
+reads as one cluster. One `gap` on a container makes every child a peer; wrap the group, then
+space the groups. Worst where both items are small grey glyphs on one line, because nothing but
+spacing distinguishes them.
+
+→ [composition.md](./composition.md) §"Touch & whitespace".
+
+### 5. State diff
+**Collect** each control at rest, hover, focus, pressed and editing, then diff the boxes.
+
+- A control is meant to change **paint** across its states and never **geometry**. So
+  `border`/`background`/`box-shadow` differing is the design; the box or the text moving is the
+  defect. Text that shifts, a border that thickens, a ring drawn twice, a tint on one path only —
+  two pieces of code own one property and happened to agree at rest. Every other probe reads a
+  RESTING screen, so all of them pass on a control that jumps 8px on focus. **Fix by giving the
+  property ONE owner** — a shared surface helper, a single frame kept across the mode swap — never
+  by nudging the second owner into agreement.
+- **A themeable control must derive every state from its token.** Signature: correct at rest, a
+  fixed neighbouring shade under the pointer. Watch for an opaque overlay hiding a themed ground.
+- **A prop's EFFECT must match its claim** — render each value and diff what actually moved
+  against what the prop says it changes. The fix is in the component, never the caller.
+- **Measure a component against ITSELF under each optional prop** that should not change size — a
+  file row measured 37px static and 49px with an `onPress`, because only the pressable variant
+  carried the padding its wash needed. Same for a slot that may be empty.
+
+→ [composition.md](./composition.md) §"Typography" (the `size` law), §"Hover grammar".
+
+### 6. Alignment and drift
+- **One left edge — the whole page, then the whole APP.** Headings, detail labels, prose, a
+  table's first column, a footer's totals, a dialog's title. Then measure the screen this one
+  OPENS: a list and its record 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 wash instead of bleeding it — fix the row, then delete the compensators, which
+  become double-corrections the moment the row is right. Two exceptions are legitimate: a
+  self-contained overlay has nothing to align with, and an indent something VISIBLE occupies (a
+  checkbox, an ordinal, a mark) is explained.
+- **A CENTRED child hides its own drift.** Centring puts a child's top at `(container − child)/2`,
+  so a child whose size varies with DATA moves its own first line between instances while the
+  container measures identical every time. It takes a container with SLACK to bite. Wherever a
+  container centres repeated children (table cells, list rows, toolbar controls, grid tiles),
+  collect the child's FIRST-line offset per instance; a constant container with a spread of
+  offsets is the signature. Fix by bounding the child that varies — never with a cross-axis knob
+  (it moves the content and leaves the chrome), and never by resizing the CONTAINER, which changes
+  both terms and leaves the spread.
+- **A slot holding another component's part must be sized by that component's constant** — a
+  24px mark in an 18px column sits 3px outside the surface.
+- **A row beat belongs to the PAGE** — collect every row primitive's height on one screen before
+  calling any of them right.
+
+→ [composition.md](./composition.md) §"Canvas & content column", §"No dead rows", §"The register's own craft".
+
+### 7. Surface walk — open it, press it, read it
+A resting register is the cheapest thing to screenshot and the least likely to hold the defect.
+
+- **Open what the row opens** and measure where the actionable field LANDS. An UNBOUNDED section
+  (a feed, a thread) above a bounded one buries it, and the burial deepens with use.
+- **Press every control** and look at the state you land in. Commonest miss: a value rendering as
+  a coloured chip in a register and as bare grey text in its own EDITOR.
+- **Diff a promoted field against where it came from.** Promoting means MOVING; a copy left behind
+  gives one field two editors.
+- **Read every string in its SETTLED state**, not the streaming one.
+- **Every state designed** — skeleton mirroring the final layout, empty, empty-SEARCH, error — and
+  no layout shift between them. → [catalog.md](./catalog.md) §"Status / feedback".
+- **A comment stating a PRIORITY between two regions is a claim to VERIFY.** "When the two
+  compete, X gives way" is testable, and a region whose width is a CONSTANT cannot give way —
+  whatever sits beside it absorbs every squeeze, silently and in the opposite direction to the
+  stated intent. Find the rule in prose, then find the number implementing it.
+- **Read the document OUTLINE**, and again AFTER fixing the type. Content from stored markdown
+  carries the tags ITS writer chose, so a heading inside a value announces as a peer of the page's
+  sections; sizing it down fixes what the screen SHOWS and nothing about what it ANNOUNCES.
+
+### 8. Data probe — count what is really there
+- **Query the table before choosing a surface.** "Show thumbnails" is wrong for a corpus of nine
+  files and zero images. Images are identified by CONTENT (a grid), documents by NAME (a list) —
+  follow the majority.
+- **Read the stored value before blaming the renderer.** A grey generic file badge can be correct
+  (the stored mime is `application/octet-stream`); grey status pills can be correct (the field has
+  no option colours). The fix is often config or a write path, not CSS.
+- **The obvious column may be the empty one.** Reading only the field the composer writes ships a
+  feature empty on every row and correct in code review.
+- **A fixture can fail in the generous direction too**: an image tile pointed at a dead URL renders
+  nothing, so the chip designed to survive a photo was never tested against one.
+- **Grep rendered text for internal identifiers — first probe, every audit** —
+  `/\b(opt|fld|tbl|rec|wfl|mbr|app|wsp)_[A-Za-z0-9]{6,}/`. It renders, measures, typechecks and
+  passes every test, because the value IS a valid string, and no other probe looks for it. The
+  usual cause is one field serving two consumers: a select decoded to its option KEY because a
+  picker's `value` needs the key, then the same variable printed at the reader. **Fix by decoding
+  BOTH** — the key for the control, the label for the sentence — never with a local key→label map,
+  which is a second copy of the field's own options and drifts the first time one is renamed. The
+  kit's `optionPicker` exists for this; see [data_entry.md](./data_entry.md).
+- **For every value, name its AUTHOR — then check that author can change it.** No measurement
+  finds a MISSING affordance. Prose a person typed is always editable; a transcript or a file
+  never is.
+- **Ask of every value: could this exist in the data?** Name the column. No answer means the block
+  goes.
+
+### 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*;
+this converges on *distinctive*.
+
+- **Type range** (probe 1) — under 2× is flat regardless of colour.
+- **Chromatic count** — one or two hues used many times reads calm; zero reads like a spreadsheet;
+  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.
+- **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?** Where there is no photography — most work software —
+  the data is the imagery: identity marks, status colour, file-type badges, sparklines, proportion
+  bars, tabular figures.
+- **What makes this belong to THIS product?** Default typeface, default greys, default accent,
+  default control shapes is a well-built generic screen, and no polish changes that. The fix is a
+  theme, not another treatment pass.
+
+→ [composition.md](./composition.md) §"Identity marks", §"Character comes from the DATA", §"Where the accent goes".
+
+### 10. Microcopy
+- **No punctuation doing a word's job.** ` · ` is banned outright — it claims a relationship while
+  refusing to name it, and it is the loudest templated-metadata tell there is. If a mark cannot be
+  read aloud as the relation it stands for, write the relation or split the line.
+- **One job per element.** A label labels, an example demonstrates, a caption qualifies. Nothing
+  does double duty.
+- **A shortened element still has to justify existing** — trimming makes it pass every length
+  probe, so re-ask gate 1 on the trimmed thing.
+- **Structure must encode something true.** A rule, an eyebrow, a number, a badge, a colour each
+  assert that something is separate / labelled / ordered / status. A false assertion is decoration
+  that costs more than it gives.
+
+→ [composition.md](./composition.md) §"Microcopy".
+
+---
+
+## Reviewing an AI surface
+
+An AI feature proposes and a person decides. These ask whether that is decidable. The full
+contract is [ai_patterns.md](./ai_patterns.md); these are the ones a rendered screen can be
+measured against.
+
+- **Show the WHOLE thing with the change marked in place.** A proposal in its own card is
+  context-free; a figure is judgeable only beside the others it sits with. `DiffValue`/`DiffMark`
+  drop into any container.
+- **Both values stay on screen** — the old one is the only evidence the correction is the right
+  SIZE.
+- **UNKNOWN is not zero.** An unanswered figure must not share its treatment with an answered one,
+  and a removal's placeholder must not share the labels' muted tone.
+- **A value the system supplied must say where it came from** — what evidence, from which source,
+  and that a model produced it. Two failure shapes: a filled control with no adjacent explanation,
+  and an explanation restating the value instead of the EVIDENCE for it. Corollary: deterministic
+  and probabilistic answers must not look alike.
+- **Nothing auto-applies**, the commit names the outcome and count, and the count is re-checked
+  against the surface after every block you add.
+- **Never pre-select a conflict candidate** — that is a decision the system made and attributed to
+  the person.
+- **A change that is not to the VALUE must diff the thing that did change** — a document refiled
+  under a new type is the same bytes; put the diff on the classification.
+- **A mark over an arbitrary ground needs its own ground** — a tint that reads on white is a smudge
+  on a photo, and the fixture has to contain the photo.
+
+---
+
+## Extraction snippets
+
+Run each at 1280 and 375. The tables ARE the findings.
+
+### Type inventory — every run of language, in document order
+
+Walks TEXT NODES rather than elements, so a run-in label and its sentence are separate rows
+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' };
+  const out = [];
+  const walk = (n) => {
+    if (n.nodeType === 3 && n.textContent.trim()) {
+      const cs = getComputedStyle(n.parentElement);
+      const rg = document.createRange(); rg.selectNode(n); const r = rg.getBoundingClientRect();
+      if (r.height) out.push({
+        t: n.textContent.trim().slice(0, 34),
+        y: Math.round(r.y), x: Math.round(r.x),
+        rung: SZ[cs.fontSize] || cs.fontSize, w: cs.fontWeight,
+        ink: INK[cs.color] || cs.color,
+      });
+    }
+    n.childNodes.forEach(walk);
+  };
+  walk(document.body);
+  return out.sort((a, b) => a.y - b.y);
+}
+```
+
+Then **count the treatments**: collapse to `rung/weight/ink` and tally. A combination with one
+member is a singleton. Two combinations doing the same job is the inconsistency you were sent to
+find.
+
+**Skip `SCRIPT`/`STYLE`/`TITLE`/`META`/`LINK`/`NOSCRIPT` and check `checkVisibility()`** in any
+variant that walks ELEMENTS rather than text nodes. Those tags hold text nodes the reader never
+sees, and counting them produces confident nonsense — a page "with eight nodes in Times New Roman"
+that has none, or a clean tally on a screen with an untracked component still on it.
+
+### Separator beats — is the biggest boundary the widest?
+
+```js
+() => {
+  const rules = [...new Set([...document.querySelectorAll('div')]
+    .filter(e => { const r = e.getBoundingClientRect(); return r.height <= 1.5 && r.width > 200; })
+    .map(e => Math.round(e.getBoundingClientRect().y)))].sort((a, b) => a - b);
+  const blocks = [...document.querySelectorAll('*')]
+    .filter(e => e.children.length === 0 && e.textContent.trim())
+    .map(e => { const r = e.getBoundingClientRect(); return { y: Math.round(r.y), b: Math.round(r.bottom) }; });
+  return rules.map(y => ({
+    rule: y,
+    above: y - Math.max(...blocks.filter(o => o.b <= y).map(o => o.b), -Infinity),
+    below: Math.min(...blocks.filter(o => o.y >= y).map(o => o.y), Infinity) - y,
+  }));
+}
+```
+
+Unequal `above`/`below` on one rule, or a rule with a visibly tighter beat than its neighbours, is
+the finding. A hand-rolled `Divider` sitting in a parent's uniform `gap` next to a `SectionStack`
+is the usual cause.
+
+### Clipping, overflow, collision
+
+```js
+() => ({
+  pageOverflowsX: document.documentElement.scrollWidth > window.innerWidth,
+  clipped: [...document.querySelectorAll('*')]
+    .filter(e => e.scrollWidth > e.clientWidth + 1 && getComputedStyle(e).overflow !== 'visible')
+    .map(e => ({ t: e.textContent.trim().slice(0, 40), w: e.clientWidth, needs: e.scrollWidth,
+                 ellipsis: getComputedStyle(e).textOverflow })),
+})
+```
+
+`ellipsis: "clip"` on a clipped element means the text ends mid-word with nothing marking the cut.
+Note the RN-Web trap: once a `Text` contains a nested pressable, `numberOfLines` degrades to bare
+`overflow: hidden` and loses the ellipsis.
+
+### Grouping — is one `gap` flattening the hierarchy?
+
+```js
+(sel) => [...document.querySelector(sel).children].map(c => {
+  const r = c.getBoundingClientRect();
+  return { t: c.textContent.trim().slice(0, 40), y: Math.round(r.y), h: Math.round(r.height) };
+})
+```
+
+List a stack's direct children and ask which BELONG together. If the answer is not "all of them",
+one gap is serving several relationships and the screen will read as blended.
+
+### Interaction states — does the control move when you touch it?
+
+Snapshot the SAME selector four times — at rest, hovered, focused, and while editing — then diff.
+
+```js
+(sel) => [...document.querySelectorAll(sel)].map(e => {
+  const r = e.getBoundingClientRect(), cs = getComputedStyle(e);
+  const inner = e.querySelector('input, textarea, [contenteditable]') || e;
+  const ir = inner.getBoundingClientRect();
+  return {
+    box: [Math.round(r.x), Math.round(r.y), Math.round(r.width), Math.round(r.height)],
+    text: [Math.round(ir.x), Math.round(ir.y)],
+    border: `${cs.borderTopWidth} ${cs.borderTopColor}`,
+    bg: cs.backgroundColor,
+    shadow: cs.boxShadow,
+  };
+})
+```
+
+`border`/`bg`/`shadow` differing is the design; `box`/`text` differing is the defect. The usual
+cause is two components spending the same inset or the same padding — a wrapper AND the input both
+paying `CONTROL_TEXT_INSET`, a focus ring owned by both a shell and a nested pressable.
+
+RN-Web trap: a frame REBUILT on the mode swap (view node unmounted, edit node mounted) never
+receives `mouseenter`, because the pointer is already stationary over it — so hover state silently
+dies at the moment of the swap and reads as a flash. Keep one node across the swap rather than
+restoring the state by hand.
+
+Driving the kit's own anatomies — a `PressDoor` row, a portalled overlay, a custom pointer drag —
+has three gotchas of its own: [testing.md](./testing.md).
+
+---
+
+## What measurement cannot see
+
+A screenshot shows *that* something is wrong when every number looks defensible. But it will not
+show you a disclosure you did not expand, or copy that only lies in its terminal state (a settled
+row still saying "Loading…" measures perfectly). Nor a flattering fixture — compare the preview
+data's SHAPE against what the real source emits before trusting any of it.
+
+---
+
+## When you find something
+
+- **Fix the CLASS, not the instance — and grep by the JOB, not the styling.** Two controls with
+  different labels, different call sites and no shared string can be the same species doing the
+  same job. Name the job in one phrase ("names a column", "commits the row", "opens a peek") and
+  search for everything else doing it. Fixing the tab in front of you is what leaves the same
+  field rendering two ways on two tabs — the inconsistency users actually report.
+- **Three fixes in one spot means the ARRANGEMENT is the defect.** Count repairs, not their
+  difficulty; the third is the signal they were never independent.
+- **Prefer changing the SHAPE over changing the weight.** Restructuring states a difference;
+  nudging a weight whispers it, and a whisper reads as a slip.
+- **When the kit is the offender, fix the kit.** An app-local override is a fork, and a component
+  built beside one that nearly fits is a fork that drifts. Kit fixes land in `src/` plus the owning
+  `docs/<area>.md`, the `AGENTS.md` index line, and a version bump — docs reach apps only on
+  publish.
+- **Never resolve a finding with "the docs say X."** Resolve it with what makes the screen better,
+  then push the answer back into the docs. A written rule cannot report that it produces a bad
+  screen, so a person has to. Where the docs ARE load-bearing is IDENTITY: the fonts, the type
+  ramp, the `Icon` set, one accent per screen — inventing a palette or a typeface is the defect,
+  not the craft.

package/docs/templates.md

@@ -197,8 +197,11 @@ The one work-execution list shape; it subsumes approvals, dispatch, batch-buildi
 screens — register, per-row action, gated selection, and act-on-many in one. The page:
 
 - **One toolbar row** — search + a status `Select` + facet `FilterChip`s LEFT, the New CTA
-  RIGHT; a light `SummaryLine` of the filtered view below.
-- **A sortable, `Divider`-separated `Table`** where the record's SUBJECT is the first column —
+  RIGHT; then a light `SummaryLine` of the filtered view BELOW it, above the rows — the counts are what the toolbar just produced, so they read after it, not before.
+- **A sortable `Table`** — rows separated by their own height and the hover wash, with the one
+  hairline under the column band. It sets no row height: the register's rhythm is the kit's,
+  and a template that overrode it would teach the override. → [composition.md](./composition.md)
+  §"The register's rhythm". The record's SUBJECT is the first column —
   who or what the record is FOR, because that is what a reader scans for and what they say out
   loud ("the Harbor Freight one", never "RC-2026-0041"). The KEY is how the SYSTEM refers to the
   record, so it rides the identity cell's supporting line, muted, where the other supporting
@@ -208,14 +211,14 @@ screens — register, per-row action, gated selection, and act-on-many in one. T
   itself the same way, or the two disagree about what a record is called. Every row carries a
   leading checkbox; a row that can't take the bulk action gets a
   **disabled** checkbox (the same gating as any blocked line). A row's status is
-  `Badge variant="dot"` — never the tonal `Badge` (that's the drawer/header twin; → [composition
-  grammar §"Status indicators have a WEIGHT"](./composition.md)) — and the SAME dot vocabulary
+  `Badge variant="dot"` — never the tonal `Badge` (that's the drawer/header twin; → [composition.md](./composition.md)
+  §"`Badge` is for STATUS only") — and the SAME dot vocabulary
   drives the status facet. A cell that carries supporting detail is a HIERARCHY, not two peers:
   the identity on top (`size="sm"`, `weight="medium"` when it IS the row's name), its supporting
   value beneath as `size="xs" color="muted"`, `gap: 2` — and a category / type / attribute goes
   on THAT line, never a second chip beside the name (which reads as its peer, or louder when
-  colored, inverting what the row is scanned by; → [composition grammar §`Badge` is for STATUS
-  only](./composition.md)). Every value in a row is SELECTABLE, so a reader copies any of them
+  colored, inverting what the row is scanned by; → [composition.md](./composition.md)
+  §"`Badge` is for STATUS only"). Every value in a row is SELECTABLE, so a reader copies any of them
   without chrome; the supporting phone additionally carries a **`CopyButton`** as the worked
   example of a verb riding its value — the one value copied often enough to earn a control, and
   in its own cell rather than the trailing gutter, which two values in a cell give nothing to

package/examples/tpl_attendance.tsx

@@ -135,7 +135,6 @@ function HomNayRow({ nv, selected, onPress }: { nv: NhanVien; selected: boolean;
     <TableRow
       onPress={onPress}
       selected={selected}
-      minHeight={64}
       accessibilityLabel={`Open ${nv.ten}'s day`}
       trailing={<HomNayMenu nv={nv} />}
     >