diff --git a/docs/design-system/HANDOVER-2026-08-07.md b/docs/design-system/HANDOVER-2026-08-07.md index c2c9938ec1..910afb132e 100644 --- a/docs/design-system/HANDOVER-2026-08-07.md +++ b/docs/design-system/HANDOVER-2026-08-07.md @@ -1,10 +1,42 @@ # 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. 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 +> 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: