@lotics/ui 45.10.0 → 46.0.0

package/docs/reviewing.md

@@ -2,11 +2,8 @@
 
 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**.
+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).
@@ -15,15 +12,13 @@ Everything here is about a screen **that already renders**. Building one starts
 
 ## The method
 
-**"Looks off" is where a finding starts.** Trust the impression — it is the same reaction the
-reader will have — and use measurement to say precisely WHAT is off, so the fix can be aimed and
-re-checked. Numbers are how a finding is confirmed and communicated, never what makes it real.
+**"Looks off" is where a finding starts.** Trust the impression and use measurement to say
+precisely WHAT is off, so the fix can be aimed and re-checked. Numbers are how a finding is
+confirmed and communicated, never what makes it real.
 
-The failure this doc has caused more than once: a screen passes every probe, the auditor reports
-that it measures fine, and the person who called it ugly is still right. Defect-removal converges
-on *inoffensive*. When the probes come back clean and the screen is still wrong, the probes are
-not the answer — the form, the density, or the fact that nothing on screen belongs to this product
-is. Go and look at it.
+When the probes come back clean and the screen is still wrong, the probes are not the answer —
+the form, the density, or the fact that nothing on screen belongs to this product is. Go and look
+at it.
 
 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.
@@ -66,18 +61,15 @@ moving through ordered places is a rail. Work assigned to finite resources over
 A sequence of events is a timeline. A population whose point is its deviant minority is a queue
 sorted by deviation. A quantity across two dimensions is a matrix.
 
-This gate exists because **every probe below reads a screen that is already a register of fields**
-and measures its TREATMENT. So a screen that should have been a board or a rail passes the type
-inventory, the ground tally, the gaps, the rules and the alignment — all of them — and still reads
-as templated. No amount of treatment fixes it, and nothing else here can see it.
+**Every probe below reads a screen that is already a register of fields** and measures its
+TREATMENT. A screen that should have been a board or a rail passes all of them and still reads as
+templated. No amount of treatment fixes it, and nothing else here can see it.
 
 *The tell that it was skipped:* every screen in the product is a register with a summary line over
-it. That is what reuse-first produces when nothing asks the question — the catalog's most reachable
-parts are `Table`, `DetailRow`, `SummaryLine` and `Badge`, so a subject whose natural shape is not
-a table gets flattened into one and no probe fires. **Reuse-first is about not duplicating
-PRIMITIVES, not about the shape of a screen**: a one-off composition needs no new component, so
-"the catalog has no journey rail" is an argument for composing one out of `Stepper`, not for
-rendering a status column and moving on.
+it. That is what reuse-first produces when nothing asks the question. **Reuse-first is about not
+duplicating PRIMITIVES, not about the shape of a screen**: a one-off composition needs no new
+component, so "the catalog has no journey rail" is an argument for composing one out of `Stepper`,
+not for rendering a status column and moving on.
 
 *And check the form against what the data can FILL.* A rail with no stamped stops, a calendar with
 no durations, a map with no coordinates — each renders an empty device that measures perfectly.
@@ -131,13 +123,12 @@ rule behind it lives in the area doc named beside it; this file never restates o
   join an existing class. Pick the sibling set by STRUCTURAL ROLE, not visual resemblance.
 - **Count DISTINCT rungs on the surface, then name the role each one carries.** More rungs than
   roles means a role has been split across two sizes, and that is the defect a reader calls
-  "inconsistent" without being able to point at which element is wrong — because none of them is:
-  each was chosen defensibly, one at a time. This is the probe to re-run after EVERY fix, and the
-  reason is procedural rather than visual: a treatment fix aimed at the element someone pointed at
-  leaves its neighbours unaligned, so the next look finds a new mismatch and the surface never
-  converges. Fixing the SET is a different act from fixing an element, and only this count tells
-  the two apart. A small panel wants two or three rungs; if the tally exceeds the number of things
-  the surface has to SAY, the excess is the finding.
+  "inconsistent" without being able to point at which element is wrong. This is the probe to
+  re-run after EVERY fix: a treatment fix aimed at the element someone pointed at leaves its
+  neighbours unaligned, so the next look finds a new mismatch and the surface never converges.
+  Fixing the SET is a different act from fixing an element, and only this count tells the two
+  apart. A small panel wants two or three rungs; if the tally exceeds the number of things the
+  surface has to SAY, the excess is the finding.
 - **Pairs.** For every primary+supporting pair, divide. A spread in the RATIOS is the finding, not
   a spread in the sizes. **A ratio of 1.00 is the loudest version** — a subject and its supporting
   line on one rung are distinguishable only by ink, and if they also share a weight, only by ink.
@@ -260,9 +251,8 @@ spacing distinguishes them.
 - **A VARIABLE-width leading slot destroys the column behind it.** A row's lead is sized for an
   icon; put a chip, a badge or a name in it and every row's title starts at a different x. Collect
   one repeated cell's `left` down the rows — more than one distinct value and the column does not
-  exist, however aligned each row looks on its own. The spread is small enough to read as
-  sloppiness rather than as a defect, which is why it survives review; the fix is a fixed-width
-  lead, or a register, where columns make it impossible.
+  exist, however aligned each row looks on its own. The fix is a fixed-width lead, or a register,
+  where columns make it impossible.
 - **Every numeric column: is its unit named anywhere, and is it ONE unit?** Collect the leaf values
   sharing a right edge, with their size and weight. Identical treatment across values that are not
   the same KIND of thing — a count beside a currency — is the signature, and the labels beside them
@@ -299,11 +289,11 @@ A resting register is the cheapest thing to screenshot and the least likely to h
   a coloured chip in a register and as bare grey text in its own EDITOR.
 - **TAB through it, then diff what a keyboard reaches against what LOOKS pressable.** A pointer
   finds anything with an `onPress`; a keyboard finds only what carries a role and a tab stop, and
-  the two lists come apart silently — the screen looks identical either way, and the author
-  testing with a mouse never learns. The reliable producer is styled text: underline, a hover
-  wash, a "verb" colour applied to a plain container, which reads as a control to the eye while
-  announcing as prose. Anything the eye calls a control and the tab order omits is unreachable,
-  not merely awkward. Count both lists; a difference is the finding.
+  the two lists come apart silently — the screen looks identical either way. The reliable producer
+  is styled text: underline, a hover wash, a "verb" colour applied to a plain container, which
+  reads as a control to the eye while announcing as prose. Anything the eye calls a control and
+  the tab order omits is unreachable, not merely awkward. Count both lists; a difference is the
+  finding.
 - **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.
@@ -333,7 +323,7 @@ A resting register is the cheapest thing to screenshot and the least likely to h
   it. Pull the field list from the write path (a workflow's `set`, a mutation's payload), not
   from the screen, then confirm each one against the record's own DetailRow/Text tree; where one
   is missing, query the record directly to prove the value is really sitting there unseen before
-  calling it a fix. A screenshot cannot catch this — it only shows what already renders.
+  calling it a fix. A screenshot cannot catch this.
 - **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** —
@@ -476,10 +466,7 @@ that has none, or a clean tally on a screen with an untracked component still on
 
 **A rule is a painted LINE, and it is drawn two ways.** Selecting "thin and wide" alone gets both
 halves wrong, and both wrongs are silent: a transparent zero-height flex spacer matches it and is
-counted, while a border on a box of ordinary height does not and is missed. The second is the one
-that bites — a component that draws its column band as a `borderBottom` on a full-height header row
-then reports **zero rules on a surface that visibly has one**, and a count of `0` reads as a clean
-result rather than a blind probe.
+counted, while a border on a box of ordinary height does not and is missed.
 
 ```js
 () => {
@@ -519,14 +506,13 @@ result rather than a blind probe.
 }
 ```
 
-Read `separates` first — probe 3 asks what each rule DIVIDES, and a rule whose two neighbours are
-the same kind of thing is the one to delete however important the break feels.
+Read `separates` first — probe 3 asks what each rule DIVIDES.
 
 Unequal `above`/`below` on one rule, or a rule with a visibly tighter beat than its neighbours, is
-the other finding. A hand-rolled `Divider` sitting in a parent's uniform `gap` next to a
-`SectionStack` is the usual cause. Asymmetry is not automatically wrong: a rule that BELONGS to
-the element above it sits tight under it and loose before the next, and that gap is what says
-which side owns it — the finding is asymmetry nobody chose.
+the other finding. A hand-rolled `Divider` in a parent's uniform `gap` is the usual cause.
+Asymmetry is not automatically wrong: a rule that BELONGS to the element above it sits tight under
+it and loose before the next, and that gap is what says which side owns it — the finding is
+asymmetry nobody chose.
 
 ### Clipping, overflow, collision
 
@@ -637,8 +623,7 @@ has three gotchas of its own: [testing.md](./testing.md).
 
 Most of what makes a screen good, which is why the probes are a floor and not a target. They will
 not tell you the density is wrong for the job, that the register has no point of view, or that
-nothing on the page belongs to this product rather than to any product. Those are judgements, and
-they are the ones that decide whether the work reads as considered.
+nothing on the page belongs to this product rather than to any product. Those are judgements.
 
 Nor will they show a disclosure you did not expand, copy that only lies in its terminal state (a
 settled row still saying "Loading…" measures perfectly), or a flattering fixture — compare the
@@ -662,7 +647,6 @@ preview data's SHAPE against what the real source emits before trusting any of i
   `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.
+  then push the answer back into the docs. 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.