Skip to content

fix(design-system): critique fixes + post-merge truth sweep (bundled hygiene PR) #1541

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
BigSimmo merged 4 commits into from
Jul 31, 2026
Merged

fix(design-system): critique fixes + post-merge truth sweep (bundled hygiene PR) #1541

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7d95606
fix(design-system): critique fixes — fallback literals, test precisio…
BigSimmo Jul 31, 2026
269672c
docs(design-system): post-merge truth sweep - rolling status, dark-de…
BigSimmo Jul 31, 2026
001ad90
Merge branch 'main' into claude/design-system-hygiene
BigSimmo Jul 31, 2026
84cf772
fix(design-system): close DoseLine calc() and playbook status drift
cursoragent Jul 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions docs/design-system/DECISIONS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -242,3 +242,21 @@ Found while verifying, fixed in the same pass: `answer-card.tsx` used arbitrary
`leading-[var(--leading-prose,1.65)]` — a restated token value that failed the
design-token contract's no-arbitrary-leading rule on the branch tip. Now the named
`leading-prose` step. Both token-contract test files: **47 passed (47)**.

6. **Dark-ink cascade bug — found by adversarial self-review, fixed pre-merge.** The
cascade port made the light `.ckb-v2` block match inside dark subtrees, silently breaking
the documented fall-through: `--text`, `--text-heading`, `--disabled`, glows, backdrop and
the accent-soft trio resolved to their **light** values on the dark ramp. Fixed on the
PR #1538 head by re-declaring every light-declared colour role in the dark block
(mirroring the live `.dark` values previously inherited) plus a contract regression: dark
`--text`/`--text-heading` ≥4.5:1 on the dark surface. New standing rule: a colour role
added to the light block is added to the dark block in the same commit.
7. **Post-merge hygiene pass (this PR).** PR #1538 merged; single follow-up bundling: the
stale-state sweep (SHAs now pinned only in this log; all other docs state rolling
status) · literal `var()` fallback values stripped from the v2 components (the last
value-restatement channel; the one surviving fallback is role→role,
`var(--e2, var(--shadow-soft))`, which restates no value) · the contract test parses the
structural and light blocks separately · HCM `--overlay-backdrop` is transparent, not
opaque Canvas · the six now-landed paths removed from the docs-link allowlist per their
own remove-after-merge note. Remaining design-app step unchanged: one real
`/design-sync` run (guidelines index + `_ds_needs_recompile`).
54 changes: 27 additions & 27 deletions docs/design-system/GATES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,33 +68,33 @@ as design tokens · export/preview parity.

## 3 · The prohibition table

| Never do this | Gate | Status |
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Reintroduce `.ckb-v2:not(.dark)` | Cascade computed-style test (PR 1) + contract-test selector filter update | planned (port not landed; branch still ships the old form) |
| Add `prefers-color-scheme` rules to the v2 layer | — (users pin a theme against OS preference) | **manual** |
| Paint a numeral with a status colour; use amber/red decoratively | Colour-boundary lint | planned |
| Put `--decoration-soft`/`--text-soft` on a text node | Tier pinned both sides in the token contract; text-node AST check | implemented-partial |
| Uppercase a dose unit | `Quantity` pins `normal-case` + unit test | implemented-blocking (branch) |
| Invert a PDF, diagram or clinical image in any theme | `DocumentFrame` refuses transforms; CSS check | planned |
| Border **and** ring on one surface, or a 1px spread in a drop shadow | Gate 8 | implemented-partial |
| A child shadow heavier than its parent's | Gate 7 | implemented-partial |
| Use `--shadow-tight`/any alias in new code | PR 9 recipe cleanup, then lint | planned |
| Raw pixel size, padding, radius or line-height in markup | Contract ratchet | implemented-partial (colour/shadow/tap literals only) |
| Animate `width`, `height`, `grid-template-*`, `top`, `left`, `gap` | Gate 9 | planned |
| Hardcode a transition duration | Gate 9 | planned |
| A `z-` value outside the named rungs | `require-z-index-ladder` (ESLint) | implemented-blocking |
| Ship a registered component without a direct test | Gate 12 | implemented-partial |
| Lower a production tap target below 48px | Gate 2 + `ui-smoke` flake history + held visual probe | implemented-partial |
| Construct an enabled control with no action, destination or name | PR 4 discriminated unions + contract tests; `require-button-wiring` covers raw `<button>` today | implemented-partial |
| Render `AnswerCard` without a verification and answer state | PR 6 required props (type-level) | planned |
| Use a bare dash for a missing clinical value | `MissingValue` + review | planned |
| Render "0 matches" after a failed request | `ErrorState` adoption + check | planned |
| Hand-rolled rows replacing `AccessibleTable` without declaring it | — | **manual** (declaration convention) |
| Drop the AI verification disclaimer | PR 6 required prop | planned |
| Fix a collapsed column by nudging pixels | 320px snapshot | planned (held harness) |
| `dark:` colour override | Lint | planned (3 live instances to burn down) |
| Truncate a page title, dialog title, drug name or review warning | — | **manual** |
| Restate a token value in prose | — | **manual** (eleven divergences came from this; TOKENS.md is the only inventory) |
| Never do this | Gate | Status |
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| Reintroduce `.ckb-v2:not(.dark)` | Cascade computed-style test (PR 1) + contract-test selector filter update | implemented-blocking — landed #1538; contract parser + dark-ink regression guard |
| Add `prefers-color-scheme` rules to the v2 layer | — (users pin a theme against OS preference) | **manual** |
| Paint a numeral with a status colour; use amber/red decoratively | Colour-boundary lint | planned |
| Put `--decoration-soft`/`--text-soft` on a text node | Tier pinned both sides in the token contract; text-node AST check | implemented-partial |
| Uppercase a dose unit | `Quantity` pins `normal-case` + unit test | implemented-blocking (branch) |
| Invert a PDF, diagram or clinical image in any theme | `DocumentFrame` refuses transforms; CSS check | planned |
| Border **and** ring on one surface, or a 1px spread in a drop shadow | Gate 8 | implemented-partial |
| A child shadow heavier than its parent's | Gate 7 | implemented-partial |
| Use `--shadow-tight`/any alias in new code | PR 9 recipe cleanup, then lint | planned |
| Raw pixel size, padding, radius or line-height in markup | Contract ratchet | implemented-partial (colour/shadow/tap literals only) |
| Animate `width`, `height`, `grid-template-*`, `top`, `left`, `gap` | Gate 9 | planned |
| Hardcode a transition duration | Gate 9 | planned |
| A `z-` value outside the named rungs | `require-z-index-ladder` (ESLint) | implemented-blocking |
| Ship a registered component without a direct test | Gate 12 | implemented-partial |
| Lower a production tap target below 48px | Gate 2 + `ui-smoke` flake history + held visual probe | implemented-partial |
| Construct an enabled control with no action, destination or name | PR 4 discriminated unions + contract tests; `require-button-wiring` covers raw `<button>` today | implemented-partial |
| Render `AnswerCard` without a verification and answer state | PR 6 required props (type-level) | planned |
| Use a bare dash for a missing clinical value | `MissingValue` + review | planned |
| Render "0 matches" after a failed request | `ErrorState` adoption + check | planned |
| Hand-rolled rows replacing `AccessibleTable` without declaring it | — | **manual** (declaration convention) |
| Drop the AI verification disclaimer | PR 6 required prop | planned |
| Fix a collapsed column by nudging pixels | 320px snapshot | planned (held harness) |
| `dark:` colour override | Lint | planned (3 live instances to burn down) |
| Truncate a page title, dialog title, drug name or review warning | — | **manual** |
| Restate a token value in prose | — | **manual** (eleven divergences came from this; TOKENS.md is the only inventory) |

## 3a · Rules added by the perfection pass (31 July, second half)

Expand Down
5 changes: 2 additions & 3 deletions docs/design-system/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,6 @@ Reading order:
5. [GATES.md](GATES.md) — every rule paired with its enforcement status. A prohibition
with no row there is a suggestion.

Canonical code: branch `claude/clinical-kb-design-system-333a69` at `59e4c3dfc`
(`src/app/ckb-v2-tokens.css` is the single token file; nothing is adopted by product
surfaces yet). Design project `08d6f126-3fd0-4764-aedf-0062a467280a` conforms to the repo
Canonical code: `src/app/ckb-v2-tokens.css` on `main` (the single token file, merged via
PR #1538; nothing is adopted by product surfaces yet). Design project `08d6f126-3fd0-4764-aedf-0062a467280a` conforms to the repo
file. No visual change ships from this document set — it is the system and its rules.
Loading
Loading