design: record the owner walkthrough backlog and its three rulings (#176)

A page-by-page walkthrough of every rendered surface with the project owner,
conducted against production screenshots. `docs/design-walkthrough.md` carries
the findings as seven self-contained sessions so each is startable from a cold
context; this commit is session 0, the cross-cutting part the other six depend
on.

Three rulings, recorded in DESIGN.md so a later sweep does not undo them:

R1, hit targets. The 28px in-row grade is now scoped by the density reason
rather than by the tag it lands in, so a `Disclosure as="row"` drawer takes the
36px standalone grade despite rendering a literal `<tr>`. This resolves a
contradiction rather than reversing a decision: e2e/sync.spec.ts:1095 has been
pinning the /admin/sync drawer to the standalone grade all along, and
payouts/[id]/notes-form.tsx:90-95 reasons the same way for a panel field. Only
/admin/accounts read the settled-decisions row as forbidding it. That row is
marked AMENDED rather than deleted, per that file's own contract.

R2, rare destructive controls do not hold permanent width in a scanning table.
Records the existing reveal-on-arm constraint (#112) as a reason to move such
controls rather than to progressively disclose them where they sit.

R4, information may not live only in the assistive-tech channel. Two instances
found, both the inverse of the usual defect: a working role="status" save
confirmation marked .visually-hidden, and an affordance named in aria-label and
absent from the visible summary.

Copy: removes the four em dashes from rendered strings (the glyph stays as this
app's null-value marker, per error.tsx:239), and drops the /payouts lede's first
sentence, which restated its own table columns. The flat-pool note label changed
shape, so its 12 e2e assertions move with it.

The equivalent /account lede is deliberately left to session 3.
e2e/account.spec.ts:1583 uses it as the narrow-capped sibling proving the
manifest opts out of the cap, and finding 3.1 changes what that anchor should
be; deleting it here would mean editing that test twice.

Gates: typecheck, lint, format:check, 1290 unit tests across 83 files, 297 e2e,
production build, and check-node-version all pass.

Author: guarzo

DESIGN.md

@@ -291,6 +291,20 @@ configuration, the other two by overwriting the file.
   there and nowhere else. There are **two** sizes and no others: `quiet` is a colour
   grade, like `primary` and `default`, and does not carry a size of its own.
 
+  The `28px` grade is scoped by the *reason* for it, not by the tag it lands in:
+  it applies to rows that each carry a control set and are read many at a time.
+  A disclosure drawer is **not** in-row for this purpose even though
+  `Disclosure as="row"` renders a literal second `<tr>`. One drawer is open at
+  a time, it spans the full table width, and nothing is competing with it for
+  vertical space, so the density argument that buys the `28px` grade does not
+  apply and its controls take `36px`. This is not a new rule so much as the one
+  already in force: `e2e/sync.spec.ts:1095` pins the `/admin/sync` drawer's
+  Re-run control to the standalone grade and has been passing all along, and
+  `payouts/[id]/notes-form.tsx:90-95` reasons the same way for a field in an
+  operation's own panel. `/admin/accounts` is the surface that diverged.
+  (Owner walkthrough 2026-08-07, ruling R1. Supersedes the flat two-grade
+  reading recorded in `docs/settled-design-decisions.md`.)
+
   `.shell__nav a` used to be a third, undocumented size at ~33.05px — `padding:
   var(--s-2) var(--s-3)` plus the label register's line box, with no floor
   and no ceiling. It could not simply shrink to 28px or grow to 36px by
@@ -309,3 +323,26 @@ configuration, the other two by overwriting the file.
   worth of controls competing for space — the same case that puts `.btn` at
   36px rather than 28px. `e2e/shell.spec.ts` pins both the 36px box and a
   minimum label-to-underline gap.
+
+## Disclosure and parity
+
+From the owner walkthrough of 2026-08-07. Both rules exist because a reviewer
+reading the code cannot see the failure; only someone using the app can.
+
+- **Rare destructive controls do not hold permanent width in a scanning table.**
+  PRODUCT.md principle 3 makes scanning the primary act, and a control that is
+  pressed once a month should not cost a column on every row for the other
+  thirty days. Move it behind per-row disclosure. Two constraints on how: the
+  cost hint stays hidden-always rather than reveal-on-arm (`confirm-submit.tsx:89-98`
+  records why — the widening disarms the control it revealed for), and the
+  drawer that receives the control takes the `36px` grade above, not `28px`.
+  (Ruling R2.)
+
+- **Information may not live only in the assistive-tech channel.** Parity runs
+  in both directions. The usual failure is a control with no accessible name;
+  this codebase's failure is the inverse — a `role="status"` confirmation
+  marked `.visually-hidden`, or an affordance named in `aria-label` and absent
+  from the visible summary, so the sighted user is the one left guessing.
+  `.visually-hidden` is for text that is *redundant* on screen (a heading level,
+  a table caption already implied by layout), never for the only copy of a fact.
+  If assistive tech is told something, the screen says it too. (Ruling R4.)

docs/design-walkthrough.md

@@ -80,6 +80,7 @@ undiscovered.
 | `--signal-warn` hue moved from 70 to 50 | At 70 it sat 18° from `--gold`/`--tier-member` at near-identical chroma/lightness (0.057 apart in OKLab) — not enough to tell a gold Member badge from an amber CRYO token two columns away | `DESIGN.md:58` |
 | Disabled controls use an explicit `--ink-faint` colour, not an opacity fade | An opacity fade moves with whatever ground it lands on: measured 3.24:1 on `--void` but 2.88:1 on a hovered admin row — under the WCAG 3:1 floor exactly when the pointer is on the row | `DESIGN.md:222-226` |
 | Hit targets: 36px standalone (`.btn`), 28px in-row (`.btn--micro`/`.btn--quiet`/`.row-toggle`) — exactly two sizes | Both clear the 24px WCAG 2.5.8 AA minimum; the admin tables carry a control set on every row and cannot reach 44px AAA without growing past a screenful, so density wins there and nowhere else | `DESIGN.md:227-232` |
+| **AMENDED 2026-08-07 (owner walkthrough, ruling R1)** — still exactly two sizes, but "in-row" is scoped by the density reason, not by the tag. A `Disclosure as="row"` drawer renders a `<tr>` and is nonetheless **not** in-row: one is open at a time, it spans the full width, nothing competes for the space. Drawer controls take 36px | Resolves a contradiction rather than reversing a decision: `e2e/sync.spec.ts:1095` has been pinning the `/admin/sync` drawer to the standalone grade all along, and `payouts/[id]/notes-form.tsx:90-95` reasons the same way for a panel field. Only `/admin/accounts` read the row above as forbidding it, having inherited 28px by structural accident | `DESIGN.md` "Hit targets", `e2e/sync.spec.ts:1095-1121`, `src/app/_components/note-form.tsx` |
 
 ## 3. Controls and confirmation (cross-cutting patterns)
 

docs/settled-design-decisions.md

@@ -230,7 +230,7 @@ test("create, add a flat pool, paste a roster, finalize, mark paid", async ({
   // sit behind their own collapsed panel — open that first.
   await openFlatPoolPanel(page);
   await page.getByLabel("Total value (ISK)").fill("1000000");
-  await page.getByLabel("Note (required — why this number)").fill("sold privately");
+  await page.getByLabel("Note (required): why this number").fill("sold privately");
   await page.getByRole("button", { name: "Add flat pool" }).click();
   // Scoped to the pool row: with one pool, "1,000,000.00 ISK" also appears in
   // the operation's "Total loot" summary, so a bare getByText is ambiguous.
@@ -329,7 +329,7 @@ test("a successful flat pool add clears the form", async ({ page, context }) =>
   await page.goto(`/payouts/${op.id}`);
   await openFlatPoolPanel(page);
   await page.getByLabel("Total value (ISK)").fill("1000000");
-  await page.getByLabel("Note (required — why this number)").fill("sold privately");
+  await page.getByLabel("Note (required): why this number").fill("sold privately");
   await page.getByLabel("What was in it (optional)").fill("a stack of PLEX");
   await page.getByRole("button", { name: "Add flat pool" }).click();
 
@@ -341,7 +341,7 @@ test("a successful flat pool add clears the form", async ({ page, context }) =>
   // banked — the exact hazard the docblock names: a second press with the
   // same numbers still visible would have created a second pool.
   await expect(page.getByLabel("Total value (ISK)")).toHaveValue("");
-  await expect(page.getByLabel("Note (required — why this number)")).toHaveValue("");
+  await expect(page.getByLabel("Note (required): why this number")).toHaveValue("");
   await expect(page.getByLabel("What was in it (optional)")).toHaveValue("");
 });
 
@@ -380,7 +380,7 @@ test("a rejected flat pool submission keeps what was typed in all three fields",
   await page.goto(`/payouts/${op.id}`);
   await openFlatPoolPanel(page);
   await page.getByLabel("Total value (ISK)").fill("1e5");
-  await page.getByLabel("Note (required — why this number)").fill("sold privately");
+  await page.getByLabel("Note (required): why this number").fill("sold privately");
   await page.getByLabel("What was in it (optional)").fill("a stack of PLEX");
   await page.getByRole("button", { name: "Add flat pool" }).click();
 
@@ -392,7 +392,7 @@ test("a rejected flat pool submission keeps what was typed in all three fields",
   // All three fields still hold exactly what was typed — this is the fix the
   // conversion to controlled state must not have traded away.
   await expect(page.getByLabel("Total value (ISK)")).toHaveValue("1e5");
-  await expect(page.getByLabel("Note (required — why this number)")).toHaveValue(
+  await expect(page.getByLabel("Note (required): why this number")).toHaveValue(
     "sold privately",
   );
   await expect(page.getByLabel("What was in it (optional)")).toHaveValue(
@@ -423,7 +423,7 @@ test("pasting two alts of one account collapses them into one participant row",
 
   await openFlatPoolPanel(page);
   await page.getByLabel("Total value (ISK)").fill("200");
-  await page.getByLabel("Note (required — why this number)").fill("flat test value");
+  await page.getByLabel("Note (required): why this number").fill("flat test value");
   await page.getByRole("button", { name: "Add flat pool" }).click();
 
   // The pasted fleet has two names, one main and one of its own alts.
@@ -805,7 +805,7 @@ test("setting shares, excluding, and removing a participant each recompute exact
 
   await openFlatPoolPanel(page);
   await page.getByLabel("Total value (ISK)").fill("300");
-  await page.getByLabel("Note (required — why this number)").fill("even split test");
+  await page.getByLabel("Note (required): why this number").fill("even split test");
   await page.getByRole("button", { name: "Add flat pool" }).click();
 
   await page
@@ -1104,7 +1104,7 @@ test("finalizing hands focus to the operation heading", async ({ page, context }
 
   await openFlatPoolPanel(page);
   await page.getByLabel("Total value (ISK)").fill("1000000");
-  await page.getByLabel("Note (required — why this number)").fill("sold privately");
+  await page.getByLabel("Note (required): why this number").fill("sold privately");
   await page.getByRole("button", { name: "Add flat pool" }).click();
   await page.getByLabel("Paste (names separated by /)").fill("Brain Tartare");
   await page.getByRole("button", { name: "Set roster" }).click();
@@ -1396,7 +1396,7 @@ test("bad shares land on the page, not the error boundary", async ({ page, conte
 
   await openFlatPoolPanel(page);
   await page.getByLabel("Total value (ISK)").fill("100");
-  await page.getByLabel("Note (required — why this number)").fill("flat");
+  await page.getByLabel("Note (required): why this number").fill("flat");
   await page.getByRole("button", { name: "Add flat pool" }).click();
   await page.getByLabel("Paste (names separated by /)").fill("Alice Pilot");
   await page.getByRole("button", { name: "Set roster" }).click();
@@ -1882,7 +1882,7 @@ test("an admin deletes an operation, and the audit row outlives it", async ({
 
   await openFlatPoolPanel(page);
   await page.getByLabel("Total value (ISK)").fill("1000000");
-  await page.getByLabel("Note (required — why this number)").fill("sold privately");
+  await page.getByLabel("Note (required): why this number").fill("sold privately");
   await page.getByRole("button", { name: "Add flat pool" }).click();
   await page
     .getByLabel("Paste (names separated by /)")
@@ -1962,7 +1962,7 @@ test("deleting an operation with a paid participant is refused on the page", asy
 
   await openFlatPoolPanel(page);
   await page.getByLabel("Total value (ISK)").fill("1000000");
-  await page.getByLabel("Note (required — why this number)").fill("sold privately");
+  await page.getByLabel("Note (required): why this number").fill("sold privately");
   await page.getByRole("button", { name: "Add flat pool" }).click();
   await page.getByLabel("Paste (names separated by /)").fill("Brain Tartare");
   await page.getByRole("button", { name: "Set roster" }).click();
@@ -2183,7 +2183,7 @@ test("exactly one gold primary control renders in each draft state", async ({
 
   await openFlatPoolPanel(page);
   await page.getByLabel("Total value (ISK)").fill("100");
-  await page.getByLabel("Note (required — why this number)").fill("flat test");
+  await page.getByLabel("Note (required): why this number").fill("flat test");
   await page.getByRole("button", { name: "Add flat pool" }).click();
 
   // Stage 2: loot exists, no roster yet — Set roster is the one gold control.

e2e/payouts.spec.ts

@@ -1096,8 +1096,8 @@ function AccountRow({
           {r.tier !== "pending" && !r.tierLocked && (
             <p className="dim drawer__note" id={tierLockNoteId(r.accountId)}>
               Setting a tier here locks it: the membership job stops raising or lowering
-              it automatically — including moving it to {tierLabel("alumni")} if this
-              member leaves the alliance — until you press auto.
+              it automatically (including moving it to {tierLabel("alumni")} if this
+              member leaves the alliance) until you press auto.
             </p>
           )}
           {r.tierChangedByName && (

src/app/admin/accounts/page.tsx

@@ -53,7 +53,7 @@ function describeScope(scope: string, contactLabel: string): string {
     case "esi-location.read_online.v1":
       return "Checks whether your character is logged in right now, so a location left behind by a character who has since logged off is shown as where they were last seen rather than as where they are.";
     default:
-      return "This deployment requests this scope, but authGD has no description for it — ask whoever runs it what it is for before granting.";
+      return "This deployment requests this scope, but authGD has no description for it. Ask whoever runs it what it is for before granting.";
   }
 }
 

src/app/login/page.tsx

@@ -182,7 +182,7 @@ export function AppraiseForm({
       as="details"
       className="disc"
       summary="Add another paste"
-      ariaLabel="Add another paste — appraise more loot, or enter a flat value"
+      ariaLabel="Add another paste: appraise more loot, or enter a flat value"
     >
       <div className="form-stack">
         {form}

src/app/payouts/[id]/appraise-form.tsx

@@ -79,7 +79,7 @@ export function FlatPoolForm({ operationId }: { operationId: string }) {
         />
       </label>
       <label className="form-stack__field">
-        Note (required — why this number)
+        Note (required): why this number
         <input
           className="field"
           name="notes"

src/app/payouts/[id]/flat-pool-form.tsx

@@ -90,8 +90,7 @@ export default async function PayoutsPage({
             )}
           </div>
           <p className="page__lede">
-            Every fight operation authGD has recorded: what it was worth, who was in it,
-            and who has been paid. Your own share of each one is on{" "}
+            Your own share of each operation is on{" "}
             <Link href="/account">your account</Link>.
           </p>
         </div>