From c1b2e74b5b91dd01cc525e7a37b51ae4a13a100c Mon Sep 17 00:00:00 2001 From: BigSimmo <87357024+BigSimmo@users.noreply.github.com> Date: Sat, 8 Aug 2026 19:33:03 +0800 Subject: [PATCH 1/2] docs(design-system): stamp the 7 August handover superseded Nine open ledger rows (#261, #262, #264-#270) cite docs/design-system/HANDOVER-2026-08-07.md as their Source, and docs/design-system/README.md sent anyone picking the work up cold straight to it as "measured state, the ordered plan". Four of its figures have since been disproved, and the corrections were written into the ledger rows rather than the document, so the document still asserts the originals. A session scoping from it re-derives work that is already known wrong. Recorded as #277. A banner rather than a rewrite, which is what #277 asks for: the corrections already live in the rows, and duplicating them re-creates the drift this fixes. The banner names the four measured errors -- the "229 --shadow-tight aliases" that is really a seven-token total mislabelled as one token (100 sites across 55 files, 228 total), the 24-vs-23 unadopted count, the "baselines cannot be generated on Windows" conclusion that overlooked the ubuntu CI job now used under #118, and #270's 22-site premise that has zero same-variant pairs -- then points at the rows. The README now sends a cold start to docs/outstanding-issues.md and marks the handover superseded in the link text itself, where the misdirection was. Deliberately not done: the document is not deleted, moved, or corrected in place. The nine Source citations, the PR and commit record, and its verification and gotcha sections are provenance the ledger is meant to preserve, and silently correcting it would leave those rows citing a document that no longer says what they were derived from. Verified: npm run docs:check-links -- "docs link check passed: 1667 repo path references resolve"; npm run docs:check-inventory -- current; npm run format:check -- "All matched files use Prettier code style!". Refs #277 --- docs/design-system/HANDOVER-2026-08-07.md | 41 ++++++++++++++++++++--- docs/design-system/README.md | 12 +++++-- 2 files changed, 45 insertions(+), 8 deletions(-) diff --git a/docs/design-system/HANDOVER-2026-08-07.md b/docs/design-system/HANDOVER-2026-08-07.md index c2c9938ec1..cdb21c0803 100644 --- a/docs/design-system/HANDOVER-2026-08-07.md +++ b/docs/design-system/HANDOVER-2026-08-07.md @@ -1,10 +1,41 @@ # Design system — handover, 7 August 2026 -**Read `AGENTS.md` first — it is the highest-priority source of truth for rules and gates. -Then point a fresh session at this file.** It carries the measured state, the work that -landed, the places the previous backlog was **wrong**, and the ordered plan. It exists so -the next session does not re-derive any of it — several of the corrections below cost a -full session to establish. +> [!IMPORTANT] +> +> **SUPERSEDED — do not scope work from this document. The ledger rows in +> [`docs/outstanding-issues.md`](../outstanding-issues.md) are the current source of truth.** +> +> Nine open rows (`#261`, `#262`, `#264`–`#270`) cite this handover as their Source, and +> several of the figures they were derived from did not survive re-measurement. Those +> corrections live **in the rows**, not here; this file still asserts the originals. +> Recorded as `#277`. +> +> Measured wrong so far: +> +> - **"229 `--shadow-tight` aliases"** is the seven-token `legacyShadowAliases` total +> mislabelled as one token. The real figure is **100 sites across 55 files**, against a +> 228 total (tight 100, soft 72, elevated 17, hover 17, card 12, lux 8, lift 2). The +> regex has never included `focus`, so `#261`'s `--shadow-focus` does not appear in this +> metric at all — the two rows do not overlap. +> - **The adoption figure** was 24 unadopted against a measured **23**. +> - **"Visual baselines cannot be generated on Windows"** is half true and led to the wrong +> conclusion: the ubuntu CI job already produces the only ones that count. All six were +> adopted under `#118` from artifact `visual-baseline-31251091603`. +> - **`#270`'s "22 call sites pair a tap token with a dead numeric height"** does not +> survive re-measurement at all: **zero** same-variant pairs exist, and the 84 survivors +> are live cross-variant responsive step-downs rather than dead classes. The stated +> blocker on declaring `tap` was measurably false — tailwind-merge groups by variant. +> +> Kept rather than deleted or corrected in place: the nine Source citations, the PR/commit +> record, and the verification and gotcha sections are provenance the ledger is meant to +> preserve. Correcting it silently would leave those rows citing a document that no longer +> says what they were derived from. + +**Read `AGENTS.md` first — it is the highest-priority source of truth for rules and gates.** +This file carries the measured state, the work that landed, the places the previous backlog +was **wrong**, and the ordered plan — but read it as a record of what one session measured +on 7 August 2026, not as current instruction. Several of the corrections below cost a full +session to establish; several others have since been disproved, per the banner above. - **Companion documents:** [README.md](README.md) · [SPEC.md](SPEC.md) · [TOKENS.md](TOKENS.md) · [COMPONENTS.md](COMPONENTS.md) · [GATES.md](GATES.md) · diff --git a/docs/design-system/README.md b/docs/design-system/README.md index 05fa6b3bae..98140c8b97 100644 --- a/docs/design-system/README.md +++ b/docs/design-system/README.md @@ -6,9 +6,15 @@ committed tests → `.design-sync/conventions.md` → this set. Where this set c higher source, the higher source wins and the contradiction is a defect here. **Picking the work up cold?** Start at -[HANDOVER-2026-08-07.md](HANDOVER-2026-08-07.md) — measured state, the ordered plan, and the -six places the older design-system backlog is provably wrong. It exists so a fresh session -does not re-derive what a previous one already measured. +[`docs/outstanding-issues.md`](../outstanding-issues.md) — the ledger rows are the current +source of truth for what is open, in what order, and what has already been measured. + +[HANDOVER-2026-08-07.md](HANDOVER-2026-08-07.md) is **superseded and must not be used to +scope work** (`#277`). Nine open rows cite it as their Source, but four of its figures have +since been disproved and the corrections live in those rows rather than in the document, +which still asserts the originals. It is kept for provenance — the citations, the PR and +commit record, and its verification and gotcha sections — and carries a banner listing what +is known wrong. Reading order: From 395caef630dced7ca7a1c2ec1548be5e9cd45995 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sat, 8 Aug 2026 13:42:32 +0000 Subject: [PATCH 2/2] docs(design-system): drop false #118 baseline-adoption claim The superseded banner said all six visual baselines were adopted under #118, but the ledger still has #118 open and tests/__screenshots__/ holds only README.md. Keep the accurate Ubuntu-CI generation point without implying visual-regression protection exists yet. Co-authored-by: BigSimmo --- docs/design-system/HANDOVER-2026-08-07.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/design-system/HANDOVER-2026-08-07.md b/docs/design-system/HANDOVER-2026-08-07.md index cdb21c0803..910afb132e 100644 --- a/docs/design-system/HANDOVER-2026-08-07.md +++ b/docs/design-system/HANDOVER-2026-08-07.md @@ -19,8 +19,9 @@ > metric at all — the two rows do not overlap. > - **The adoption figure** was 24 unadopted against a measured **23**. > - **"Visual baselines cannot be generated on Windows"** is half true and led to the wrong -> conclusion: the ubuntu CI job already produces the only ones that count. All six were -> adopted under `#118` from artifact `visual-baseline-31251091603`. +> conclusion: the ubuntu CI job already produces the only ones that count. They are still +> uncommitted — `#118` remains open, and `tests/__screenshots__/` holds only `README.md` +> until reviewed Linux PNGs are adopted. > - **`#270`'s "22 call sites pair a tap token with a dead numeric height"** does not > survive re-measurement at all: **zero** same-variant pairs exist, and the 84 survivors > are live cross-variant responsive step-downs rather than dead classes. The stated