diff --git a/docs/branch-review-records/1233fbf36b5160345976009075cd18f47201a1635e459105ba8fb0cda19d332a.record.md b/docs/branch-review-records/1233fbf36b5160345976009075cd18f47201a1635e459105ba8fb0cda19d332a.record.md new file mode 100644 index 0000000000..1e352a1cb2 --- /dev/null +++ b/docs/branch-review-records/1233fbf36b5160345976009075cd18f47201a1635e459105ba8fb0cda19d332a.record.md @@ -0,0 +1 @@ +| 2026-08-22 | work | a26747b1e8c7ac5a705b1beee94b61aaeddef74e | PR 1 clinical status semantics and baseline provenance | status semantics implemented with zero contract debt; no high-confidence diff findings; human screenshot provenance disposition remains approval-gated | focused status contract; design-system contract; desktop and forced-colour phone browser proof; production readiness; lint; typecheck; build; full unit suite has unrelated jq-less hook timeouts | diff --git a/docs/branch-review-records/66988d5ef89875ea4478e969fa246f6e84d36fdfaaf2afa95923f8ee8857522b.record.md b/docs/branch-review-records/66988d5ef89875ea4478e969fa246f6e84d36fdfaaf2afa95923f8ee8857522b.record.md new file mode 100644 index 0000000000..343d116610 --- /dev/null +++ b/docs/branch-review-records/66988d5ef89875ea4478e969fa246f6e84d36fdfaaf2afa95923f8ee8857522b.record.md @@ -0,0 +1 @@ +| 2026-08-22 | work | 4c06617a4bac40dbafb9c07dc7468ea62adb559c | design-system live convergence programme plan and local handoff | No P0-P2 defect in the plan. Six independently revertible tranches, adversarial gates, Cloud/local boundaries, clinical stop conditions, and an operator handoff packet are specified. | flightplan docsOnly; clinical-proof docsOnly; docs links passed; docs script refs passed; focused Prettier passed; diff check passed | diff --git a/docs/branch-review-records/76e5eff45d022253b5017e75703fa591adbb9c5f76c5632f1bd44c923f39569b.record.md b/docs/branch-review-records/76e5eff45d022253b5017e75703fa591adbb9c5f76c5632f1bd44c923f39569b.record.md new file mode 100644 index 0000000000..18a4da3114 --- /dev/null +++ b/docs/branch-review-records/76e5eff45d022253b5017e75703fa591adbb9c5f76c5632f1bd44c923f39569b.record.md @@ -0,0 +1 @@ +| 2026-08-22 | codex/review-design-system-and-live-design | c22b3ec5cd78e119bdd7764abdde4ce8123e3000 | pr-ci-fix | green | merge-conflict-resolved(GATES.md), focused-tests(status-semantics-contract+shared-home-metadata: 13/13), phone-chrome-dry-run(focused-ownership-sufficient), doc-fix(design-system-live-convergence-plan.md:270) | diff --git a/docs/branch-review-records/99b9ea02fd5f93288c57c502619ad01fda97f2253fd6da239fd6bde1ca6c0a28.record.md b/docs/branch-review-records/99b9ea02fd5f93288c57c502619ad01fda97f2253fd6da239fd6bde1ca6c0a28.record.md new file mode 100644 index 0000000000..a148ca5970 --- /dev/null +++ b/docs/branch-review-records/99b9ea02fd5f93288c57c502619ad01fda97f2253fd6da239fd6bde1ca6c0a28.record.md @@ -0,0 +1 @@ +| 2026-08-22 | work | b158b93532511db8077e226f00bdabeaa0c3ea85 | cloud design-status semantics implementation prompt | no high-confidence findings; bounded offline-first PR1 prompt with truthful provenance and local handoff gates | workflow:flightplan; docs:check-links; docs:check-scripts; format; git diff --check | diff --git a/docs/design-system/GATES.md b/docs/design-system/GATES.md index 57c38541bc..e1e4fc4cae 100644 --- a/docs/design-system/GATES.md +++ b/docs/design-system/GATES.md @@ -75,7 +75,7 @@ because it contributed nothing. | 1 | Contrast ≥4.5:1 for every text/background pair, both themes, live **and** v2; `--decoration-soft` asserted below 4.5 and never on a text node | **implemented-blocking** | v2 pairs + `--text-placeholder` + `--decoration-soft` tier + recipe AST (`decoration-on-text.contract.test.ts`); live full matrix remains follow-on. | | 2 | Tap targets ≥48px interactive; static pills never carry `min-h-tap`; no production target reduced | **implemented-blocking for new use** | Enforced today: `--spacing-tap` is 48px and pinned from both sides (`ckb-v2-token-contract` asserts the `@theme` knob is ≥48 and that `--tap-min` is its alias), `ui-style-contract` measures the rendered floor for declared `min-height` carriers in Chromium, and the legacy-class / literal ratchets still run. **Still open for the `h-10` case, and 9 Aug 2026 measured why.** An enumeration of _rendered interactive_ elements was written, shown to find genuine defects, and then **reverted rather than landed**: it is not deterministic on this route. Six runs against one production build returned 6, 5, 4, 3, 3 and 9 distinct sub-floor shapes, largely disjoint — one run saw the answer-suggestion chips and a sort band, another the settled results list. `waitForLoadState("networkidle")` plus deduplication to distinct shapes did not fix it, and two consecutive agreeing runs turned out to be coincidence. This spec runs in the required `Production UI` job, so an intermittent version of it would block every merge in the repo; that is a worse outcome than the gap it closes. Path to blocking: give the audit a deterministic surface — a static route or a fixed seeded state — before re-attempting it. **What the enumeration did establish, in every one of the six runs, is a live defect:** controls that carry `min-h-tap` compute `min-height: 0px` and render at 16–36px, six distinct shapes in total. The declared-carrier audit cannot report them by construction — it only measures elements already computing at or above the floor, so a floor overridden downward is skipped rather than flagged. Tracked as `#293`. **Correction, same date — "`test:e2e:style-contract` is not part of `verify:cheap`" was true and badly misleading, and it sent one session looking for a wiring bug that does not exist.** The npm script is only a convenience alias for running this one spec; the spec matches `productionSpecPattern` in `playwright.config.ts` and is listed explicitly in `scripts/playwright-pr-shards.mjs`, so it already runs in the `Production UI` job that `pr-required` demands on any UI-scoped PR. It must **not** be added to `verify:cheap:internal`: `check:gate-manifest` requires every gate in that chain to also run in `static-pr`, which has no browser and no server. Per-surface geometry stays in the held visual harness. **Both named gaps are now closed, 15 Aug 2026.** The rendered enumeration landed first: `885c613` (PR #1962) added the deterministic phone-viewport `min-h-tap` audit this row was waiting on — `/forms`'s fixed-array home rather than a live-search route, polled until three consecutive reads agree, explicitly sorted, and asserted identical across three full navigate-and-enumerate cycles. The `h-10` case is closed here by `interactiveTapFloorDeclarations` in `check:design-system-contract`: an interactive element (`a`, `button`, `input`, `select`, `summary`, `textarea`) declaring its own **unprefixed** `min-h-*` below the 48px token. Comparable arbitrary lengths and mutually exclusive/composed class branches are evaluated independently, so one safe branch cannot hide a sub-floor runtime path. Ratcheted at **33** across 14 files with per-path pins, so a new sub-floor control anywhere in `src/**` fails today. Mutation-verified: lowering one shortlist button to `min-h-9` produces both the total and matching per-path regression. **Deliberately scoped to `min-h-*`, not `h-*`/`size-*`:** a short `h-4` on an interactive element is routinely the visible box of a control whose hit area is owned by a tap-sized wrapper (`SelectionCheckbox` in `differentials-home.tsx`, whose label `ui-smoke` asserts still meets the floor), so flagging those would pad the baseline with non-defects — the §5 failure mode. **One known limit, recorded rather than hidden:** the walker sees intrinsic lowercase tags only, so a floor declared on `` or another component wrapper is invisible to it (the pre-existing `legacyTapClasses` check has the same blind spot). The 33 recorded sites are real debt still owed, tracked in `#265`. | | 3 | Focus outline present, `--focus`, no companion ring | **planned** | Corrected 6 Aug 2026: the previous evidence ("`--focus` is referenced nowhere in the DS export", finding N3) was false — **[verified: grep]** 4 declarations (2 theme, 2 forced-colours) against **273** `var(--focus)` consumers, 260 of them in `.tsx`. The token is adopted; the check is what is missing. Path to blocking: assert a visible focus outline on every interactive role and reject a `ring-*` companion on the same node. A row that understates shipped work costs the document its authority as surely as one that overstates it, and nobody files a bug against pessimism. | -| 4 | Non-colour encoding on every status indicator | **implemented-blocking for new use** | Blocked today by `ui-v2-answer-safety.dom.test.tsx`: an overdue `DoseLine` row is asserted to carry all three channels (amber inset rule **plus** the words "Source review overdue" **plus** a `StatusMark` shape), `MissingValue` is asserted never to contract to a dash at any density, `FieldError` is asserted to pair its text with an icon, and `RetrievalStateBanner` is asserted to carry its state in the headline text rather than the tone alone. Off-vocabulary status still degrades to a phrase (`source-badges-off-vocab.dom.test.tsx`, Gate 6). **Not blocked today:** there is no repository-wide enumeration of status indicators, so a _new_ colour-only indicator elsewhere in `src/components/**` — the bare `statusDot*` recipes are the obvious candidates — would not fail anything. **Closed 9 Aug 2026 — the repository-wide enumeration now ships.** `colourOnlyStatusIndicators` (`check:design-system-contract`) flags a status hue on a box that says nothing: no children, no `aria-label`/`aria-labelledby`/`title` on it or any ancestor, no text sibling, and not a `StatusMark`. It also flags shared _swatch recipes_ — a status hue plus a tiny round box and no text utility — because the analyzer is per-file and cannot follow an imported `statusDotReady` to its call sites, so the recipe is where the defect is catchable. Ratcheted at **4** with per-path pins: the two bare `statusDot*` recipes GATES.md named, plus a calculator risk band and a therapy meter fill. A _new_ colour-only indicator anywhere in `src/**` now fails. Still partial: those 4 recorded sites, and `--decoration-soft` is deliberately out of scope (it carries no state). | +| 4 | Non-colour encoding on every status indicator | **implemented-blocking** | `colourOnlyStatusIndicators` scans production class roots and shared swatch recipes. The remaining calculator spectrum and shared status-marker debt was retired on 22 Aug 2026: severity bands now add distinct neutral edge patterns, ready/review/muted markers differ by outline/fill/geometry, and visible labels remain at call sites. The metric and per-path baseline are pinned at **0**; `StatusMark`, persistent text, and decoration-only `--decoration-soft` retain their documented roles. | | 5 | Tables: semantic caption, associated headers, `aria-controls` on the expander | **implemented-blocking** | `AccessibleTableProps.caption` is required; DOM and alignment tests prove the semantic ``, associated headers, and expander relationship. | | 6 | Enum resilience — neutral fallback, never throws | **implemented-blocking** | `source-badges-off-vocab.dom.test.tsx`. | | 7 | Elevation monotonicity — no child heavier than its parent | **implemented-partial** | Token-ramp monotonicity is tested; the per-surface child/parent rule is planned (needs a render-tree check). | @@ -107,7 +107,7 @@ theme-list parity, and remote design-project publication remain separate concern | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 | `check:design-system-contract` — `statusColouredNumerals` + `colourOnlyStatusIndicators` | **implemented-blocking** (9 Aug 2026) — ratcheted at 1 and 4 with per-path pins; see §5 | +| Paint a numeral with a status colour; use amber/red decoratively | `check:design-system-contract` — `statusColouredNumerals` + `colourOnlyStatusIndicators` | **implemented-blocking** — both metrics and their per-path baselines are pinned at **0**; see §5 | | Put `--decoration-soft`/`--text-soft` on a text node | Tier pinned both sides in the token contract; recipe AST (`decoration-on-text.contract.test.ts`) | implemented-blocking (recipes); broader AST follow-on | | Uppercase a dose unit | `Quantity` pins `normal-case` + unit test | implemented-blocking (branch) | | Invert a PDF, diagram or clinical image in any theme | `check:design-system-contract` — `imageInversions`, pinned at **zero**, not ratcheted | **implemented-blocking** (9 Aug 2026) — CSS `filter`/`backdrop-filter` plus the Tailwind `invert`/`hue-rotate` utilities; see §5 | @@ -240,15 +240,14 @@ ceiling the same edit passed. The remaining 224 aliases are `#262`'s cleanup, no **Three new checks:** - `statusColouredNumerals` — a `text-*` status hue on an element whose children are all - figures. Ratcheted at **2**: a rank badge painted `--danger` for emphasis - (`differentials-home.tsx:401`) and an amber warning index (`visual-evidence.tsx:495`). -- `colourOnlyStatusIndicators` — described in the Gate 4 row above. Ratcheted at **4**. + figures. Pinned at **zero** after the evidence-gap ordinal was made semantically neutral. +- `colourOnlyStatusIndicators` — described in the Gate 4 row above. Pinned at **zero** after + the calculator spectrum and shared status-marker recipes gained non-colour channels. - `imageInversions` — pinned at **zero**, not ratcheted, because production carries none. Covers CSS `filter`/`backdrop-filter` and the Tailwind `invert`/`hue-rotate` utilities. -All three are mutation-verified: a probe component carrying one of each failed with -`statusColouredNumerals increased from 2 to 3`, `colourOnlyStatusIndicators increased from 4 -to 5`, and `inversion filters would recolour clinical imagery`, each with its per-path line. +All three are mutation-verified: a probe component carrying one of each fails from the zero +baseline, and each status finding includes its per-path line. **The two status metrics were re-measured three times before the baseline was written**, and that is the part worth keeping. The first draft found 19 colour-only indicators and 3 diff --git a/docs/plans/design-system-live-convergence-plan.md b/docs/plans/design-system-live-convergence-plan.md new file mode 100644 index 0000000000..a5f4d2a5fc --- /dev/null +++ b/docs/plans/design-system-live-convergence-plan.md @@ -0,0 +1,366 @@ +# Design-system live convergence programme + +**Status:** execution-ready plan + +**Prepared:** 22 August 2026 + +**Starting point:** `work` at `4c06617a4bac40dbafb9c07dc7468ea62adb559c` + +**Objective:** bring the production interface into measurable agreement with the Clinical KB design system without weakening clinical-state semantics, accessibility, privacy, source provenance, or conservative failure behaviour. + +## 1. Outcome and non-goals + +The programme is complete only when the executable design-system baseline is reduced deliberately, the corresponding browser behaviour is proved, and every accepted visual baseline has honest human provenance. + +This is **not** a visual rewrite. It must not: + +- change clinical meaning, search/retrieval, answer generation, permissions, tenancy, storage, or provider configuration; +- add decorative clinical-state colours; +- hide publisher, review, extraction, validation, or source-status information; +- trade phone accessibility for desktop density; +- self-approve screenshots produced by the implementing agent; +- combine all debt into one unreviewable pull request; +- call Supabase, OpenAI, Railway, Figma, hosted CI, or production services without a separate explicit authorization. + +## 2. Sources of truth and enabled workflows + +Apply sources in this order: + +1. `AGENTS.md` and repository safety rules. +2. `src/app/ckb-v2-tokens.css`, `src/app/globals.css`, and committed contract tests. +3. `docs/design-system/SPEC.md`, `TOKENS.md`, `COMPONENTS.md`, `GATES.md`, and `ADOPTION.md`. +4. `scripts/design-system-contract-baseline.json` for the current measured debt. + +Use the smallest applicable skills rather than treating “all skills” as permission to run unrelated workflows: + +| Skill | When it applies | Required output | +| ------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | +| `plan` | Before every tranche | Path-scoped flightplan, risk class, verification ladder, approval boundary | +| `ui` | Every production UI change | Verified local URL, responsive/keyboard/focus/motion/forced-colour evidence | +| `clinical` | Status, answer, source, dose, trust, missing-value, or degraded-state changes | Conservative-failure and clinical-governance evidence | +| `test` | Every behavioural tranche | Smallest deterministic regression first, broader gate only for distinct risk | +| `review` | Before handoff of each tranche | Severity-ranked final-diff review and immutable review record | +| `privacy` | Only when privacy copy, logging, auth state, or user data exposure changes | Data-flow and client-exposure proof | +| `sources` | Only when provenance/status/source rendering changes | Source-label and governance proof | +| `performance` | When density, motion, shared chrome, or bundle-owning components change materially | Layout/bundle/interaction evidence scoped to the change | +| `handover` | At the end of every tranche | Clean-state, checks, risks, rollback, and exact next-action record | + +Do not invoke database, migration, ingestion, RAG, dependency, deploy, recovery, or provider workflows unless a tranche actually crosses that boundary. + +## 3. Current measured gap + +Treat `scripts/design-system-contract-baseline.json` as executable truth and re-read it at the start of every tranche. The starting debt is: + +- 3 colour-only status indicators and 1 status-coloured numeral; +- 33 sub-floor interactive minimum-height declarations; +- 18 border/ring edge conflicts and 2 one-pixel shadow spreads; +- 41 hardcoded CSS motion durations and 11 layout-transition exceptions; +- 89 legacy shadow aliases; +- 52 padding, 20 radius, 25 gap, 74 margin, and 3 line-height literals; +- 8 raw CSS z-index declarations; +- 6 canonical visual baselines, with human-provenance ambiguity still requiring disposition. + +Before editing, save the exact baseline counts in the tranche evidence. After editing, require both the global count and the intended per-path count to fall. A count moving to another file is not progress. + +## 4. Delivery architecture + +Use six bounded pull requests. Each PR must be independently safe to merge and independently revertible. + +### PR 1 — clinical status semantics and baseline provenance + +**Execution status (22 Aug 2026):** the production status-semantics work is implemented and the +two contract metrics are pinned at zero. Canonical screenshot provenance remains open: the current +schema requires a genuinely human-approved disposition, which an automated Cloud session cannot +truthfully supply. Do not weaken that gate; complete it through the documented human baseline-review +workflow. + +**Goal:** remove all colour-only clinical/status meaning and correct screenshot approval truth. + +**Primary files** + +- `src/components/calculators/calculator-ui.tsx` +- `src/components/ui-primitives.tsx` +- `src/components/clinical-dashboard/visual-evidence.tsx` +- the smallest directly affected DOM/browser tests +- `tests/__screenshots__/linux/provenance.json` only after a real reviewer disposition +- `scripts/design-system-contract-baseline.json` via the repository’s normal contract update path + +**Implementation rules** + +1. Classify each flagged use as clinical state, category identity, decoration, or false positive. +2. For real state, add persistent text plus a non-colour channel such as icon shape, border style, or pattern. +3. Do not use `aria-label` as the only repair when sighted users would still see colour alone. +4. Do not recolour numerals with warning/success roles; put status beside the value. +5. If baseline provenance is not genuinely human-approved, mark it pending. If reviewed, record the actual human reviewer and review time. + +**Adversarial proof** + +- default, dark, forced-colours, monochrome screenshot, print, and screen-reader name; +- state remains distinguishable after all authored colours are removed; +- no false “safe/current” impression when data is missing or stale. + +**Exit criteria** + +- `colourOnlyStatusIndicators = 0`; +- `statusColouredNumerals = 0`; +- provenance makes no contradictory human/automated claim; +- no clinical-state wording or source governance is weakened. + +### PR 2 — interaction geometry + +**Goal:** retire the 33 existing sub-floor interactive declarations without bloating static content. + +**Order** + +1. Document management: `DocumentManagerPanel.tsx`, `document-admin.tsx`, `DocumentTagCloud.tsx`. +2. Calculators: bedside sheet, calculator UI, clinical console, directory grid. +3. Settings, favourites, forms, answer content, then Chip. + +**Implementation rules** + +- Prefer a 48px hit area around compact visible content where density matters. +- Preserve table/row alignment and prevent hit-area overlap. +- Static badges and pills must not inherit interactive tap sizing. +- Do not lower the canonical tap token or add per-component replacement knobs. +- Treat keyboard focus area and pointer hit area as the same owned control. + +**Adversarial proof** + +- 320, 390, 639, 768, 1440, and 1920px; +- coarse pointer and fine pointer; +- keyboard-only focus order; +- 200% and 400% zoom; +- long labels, disabled, busy, error, and empty states; +- no horizontal overflow or overlapping adjacent controls. + +**Exit criteria** + +- `interactiveTapFloorDeclarations = 0`; +- deterministic rendered audit reports every applicable target at or above the token floor; +- no phone or desktop density regression accepted without explicit product review. + +### PR 3 — edge ownership and elevation + +**Goal:** make each surface own exactly one edge treatment and converge elevation. + +**Primary order** + +1. `master-search-header.tsx` +2. `DocumentTagCloud.tsx` +3. formulation/specifier builders and compare pages +4. shared navigation and primitives +5. the two spread shadows in `globals.css` + +**Implementation rules** + +- Separation: border **or** elevation. +- Keyboard focus: outline, not a permanent companion ring. +- No shadow may carry a 1px spread that recreates a border. +- A child must not look more elevated than the overlay or card that contains it. +- Migrate shadow aliases only after identifying their semantic role: inset, card, floating control, overlay, or modal. + +**Exit criteria** + +- `edgeOwnershipConflicts = 0`; +- `onePixelShadowSpreads = 0`; +- a documented reduction target for `legacyShadowAliases`, ideally zero for all files touched by this tranche; +- normal and forced-colour focus remains visible. + +### PR 4 — motion, spacing, and z ownership + +**Goal:** remove systemic literal drift without manufacturing unnecessary tokens. + +**Implementation rules** + +- Cluster repeated values before creating a token. Require a semantic role and at least two genuine consumers. +- Convert repeated durations/easings to existing motion tokens first. +- Keep only layout transitions that communicate a necessary state change; use transform/opacity for decorative motion. +- Preserve reduced-motion behaviour and eliminate animation that blocks interaction. +- Replace raw z-index declarations with named layer rungs, beginning with dialogs, sheets, sidebars, toast, and phone composer layers. + +**Exit criteria** + +- hardcoded duration and raw z-index counts decrease to zero or to an explicitly justified, per-path exception set; +- layout-transition exceptions contain only reviewed functional transitions; +- touched spacing/radius paths reach zero literal debt; +- no cumulative layout shift, scroll-ownership, or overlay-order regression. + +### PR 5 — deterministic adversarial design fixtures + +**Goal:** prove dangerous states, not only polished defaults. + +Add deterministic fixture coverage for: + +- grounded answer; +- stale evidence; +- partial retrieval; +- ungrounded/source-only answer; +- missing numeric value and unverified numeric value; +- loading, slow loading, empty, error, retry, disabled, and pending states; +- longest realistic page, dialog, medicine, source, and review-warning labels; +- source publisher/version/review/extraction/approver block; +- print and 400% zoom. + +The fixture must use offline deterministic data. It must not call OpenAI, Supabase, or live APIs. Add focused browser assertions for semantic state, then screenshots only where pixels are the actual contract. + +**Exit criteria** + +- every clinically dangerous state has text and structural differentiation from the confident state; +- default, dark, forced-colours, reduced-motion, print, phone, and desktop coverage is explicit; +- failures identify a named owner rather than producing an undiagnosable full-page pixel diff. + +### PR 6 — live density and workflow polish + +**Goal:** improve scan efficiency only after safety and system debt are controlled. + +Candidate changes requiring product judgment: + +- compact desktop Services results while preserving 48px actions and status wording; +- one restrained shared-home resume region (recent work, recent sources, or source-health summary); +- explicit loading language alongside skeletons; +- consistent permanent source-provenance blocks. + +Prototype or measure alternatives before production edits. Do not fill whitespace for its own sake. This PR may be split if Services, shared home, and provenance cross different owners. + +## 5. Verification ladder per tranche + +Run commands sequentially; do not stack broad gates when a focused check already proves the same failure class. + +### Before editing + +```bash +git status --short --branch +git worktree list +npm run workflow:flightplan -- --write-evidence --files +npm run workflow:design-sweep -- --write-evidence +npm run ensure +``` + +Use the printed URL and require `/api/local-project-id` to identify Clinical KB before browser work. + +### During iteration + +```bash +npm run check:design-system-contract +npm test -- --run +node scripts/run-playwright.mjs --project=chromium --grep +``` + +Add `npm run workflow:clinical-proof -- --write-evidence --files ` for PR 1, PR 5, and any source/trust/degraded-output change. + +### Handoff gate + +```bash +npm run format +npm run verify:pr-local -- --dry-run --files +npm run verify:pr-local +npm run workflow:lifecycle -- --phase handoff --write-evidence +``` + +Use `npm run verify:ui` only when shared UI foundations changed or the PR-local selector requires it. Use `npm run verify:phone-chrome` first for phone-chrome owners. Do not run release/provider gates without explicit approval. + +## 6. Cloud/local boundary + +### Safe in offline Cloud + +- source, CSS, test, fixture, and documentation edits; +- deterministic demo-mode browser checks; +- design-system, adoption, design-sync, lint, type, unit, and local production-build checks; +- screenshot candidate generation; +- feature-branch commits only; branch or pull-request publication requires separate explicit user authorization. + +### Local operator or human required + +- explicit human visual-baseline approval; +- physical Safari and installed-PWA acceptance; +- production-connected health or authenticated tests; +- any Figma, Supabase, OpenAI, Railway, Sentry, or hosted-CI action not separately authorized; +- final product choice between density/resume-region alternatives. + +Never copy provider credentials into Cloud. A `make_pr` metadata response is not proof of publication; verify the remote branch and PR URL through native controls. + +## 7. Rollback and change isolation + +- One coherent commit or small commit stack per PR; never mix tranches. +- Do not update baseline counts until the associated code and proof are in the same commit. +- Revert a tranche as a unit if clinical meaning, source status, focus, or responsive geometry regresses. +- Screenshot refreshes must be separate from behavioural fixes unless the pixel change is the intended, reviewed output. +- Never weaken a ratchet to make a regression pass. If a current count is wrong, repair the analyzer or evidence before changing the ceiling. + +## 8. Local handoff packet + +At the end of each Cloud tranche, leave the local operator this exact packet: + +### Identity + +- repository path and project ID; +- branch name, upstream, base ref, full HEAD SHA, and commit list; +- clean/dirty status and every untracked artifact; +- PR URL if genuinely published, otherwise state “not published”. + +### Change inventory + +- objective and non-goals; +- files changed grouped by product owner; +- before/after executable debt counts, globally and per path; +- clinical/state semantics changed or explicitly unchanged; +- screenshots added/changed, with provenance and whether human approval is pending. + +### Verification evidence + +- exact command, exit code, decisive output line, and evidence path; +- routes, viewports, states, keyboard interactions, motion preference, forced colours, zoom, and print covered; +- checks deliberately not run and the failure class left open; +- provider-backed checks skipped and the authorization needed. + +### Local acceptance sequence + +```bash +git status --short --branch +git show --stat --oneline HEAD +npm run check:installed-lock-parity +npm run check:design-system-contract +npm run ensure +``` + +Then, against the printed verified URL: + +1. confirm `/api/local-project-id`; +2. inspect the changed route at 320, 390, 639, 768, 1440, and 1920px; +3. check keyboard order and visible focus; +4. check reduced motion and forced colours; +5. inspect loading, empty, error, success, disabled, and pending states relevant to the tranche; +6. inspect 200%/400% zoom and print where clinical content is involved; +7. perform physical Safari/PWA checks when phone chrome, safe areas, keyboard, or installation behaviour changed; +8. human-review screenshot candidates and update provenance honestly; +9. record pass/fail and the exact follow-up owner. + +### Stop conditions + +Stop and return the tranche rather than approving it if: + +- a clinical state becomes colour-only or less explicit; +- a dose, unit, source status, warning, or missing value truncates or changes meaning; +- an interactive target overlaps another control or falls below the tap floor; +- keyboard focus is lost, trapped, or invisible; +- a phone or zoom viewport gains horizontal overflow; +- a degraded/partial state looks equivalent to a confident state; +- screenshot provenance claims human approval that did not occur; +- a baseline count falls only because the violation moved or the analyzer weakened. + +## 9. Completion definition + +The programme is complete when: + +- colour-only indicators, status-coloured numerals, sub-floor targets, edge conflicts, and shadow spreads are zero; +- motion, z-index, shadow-alias, and spacing debt are zero or documented as narrow functional exceptions with deterministic proofs; +- dangerous answer/source states have offline semantic and visual fixtures; +- shared focus, contrast, forced-colour, reduced-motion, zoom, and print contracts are deterministic; +- baseline provenance is honestly human-approved; +- Cloud evidence and the local/device acceptance packet are both complete; +- every tranche is independently reviewed, committed, published, and revertible; +- no provider, production, privacy, source-governance, or clinical-safety boundary was weakened. + +## 10. First action + +Start PR 1 only. Re-read the four flagged status sites, classify their meaning, and produce a path-scoped flightplan before editing. Do not begin tap-target or visual-density work in the same branch. diff --git a/docs/prompts/codex-cloud-design-status-semantics.md b/docs/prompts/codex-cloud-design-status-semantics.md new file mode 100644 index 0000000000..fa3e9345fd --- /dev/null +++ b/docs/prompts/codex-cloud-design-status-semantics.md @@ -0,0 +1,282 @@ +# Codex Cloud prompt — design-system clinical status semantics + +Copy the complete prompt below into a new Codex Cloud task for the **Database / Clinical KB** +repository. This task is deliberately limited to PR 1 of the +[design-system/live-design convergence programme](../plans/design-system-live-convergence-plan.md#pr-1--clinical-status-semantics-and-baseline-provenance). +Do not combine it with the later interaction, edge, motion, density, or shared-home tranches. + +--- + +## Perfected prompt + +You are the implementation owner for **PR 1 — clinical status semantics and baseline provenance** +in the Database / Clinical KB repository. Complete the smallest safe, independently revertible +change that removes the currently recorded colour-only status meaning and status-coloured numeral. +Also resolve the screenshot-provenance contradiction without ever representing automated review as +human approval. + +### Required outcomes + +1. Classify every currently flagged occurrence as clinical state, category identity, decoration, or + false positive, based on the rendered behavior and source context—not on the detector name alone. +2. For every real state, provide persistent visible text and a second non-colour visual channel such + as icon shape, border style, or pattern. An `aria-label` alone is not a repair for sighted users. +3. Keep numerals semantically neutral; show warning/success/state meaning beside the value rather + than by colouring the number. +4. Reduce both design-contract metrics to zero without moving the same debt elsewhere: + `colourOnlyStatusIndicators: 3 → 0` and `statusColouredNumerals: 1 → 0`. +5. Make screenshot provenance truthful. Never invent a reviewer, review time, approval, or evidence. + If no genuine human disposition is available, use only a schema-supported pending state. If the + schema or gate cannot represent that truth safely, do not change provenance; report the exact + blocker in the handoff for a human reviewer. +6. Preserve clinical wording, source governance, conservative missing/stale-data behavior, existing + component contracts, responsive behavior, and assistive-technology names. + +### Authoritative starting evidence + +Read these before editing: + +- Repository rules: [`AGENTS.md`](../../AGENTS.md) and [`CLAUDE.md`](../../CLAUDE.md). +- Cloud safety and browser readiness: [`docs/codex-cloud.md`](../codex-cloud.md). +- The bounded programme and PR 1 exit criteria: + [`docs/plans/design-system-live-convergence-plan.md`](../plans/design-system-live-convergence-plan.md). +- Design-system entry point and contracts: + [`docs/design-system/README.md`](../design-system/README.md), + [`SPEC.md`](../design-system/SPEC.md), [`TOKENS.md`](../design-system/TOKENS.md), + [`COMPONENTS.md`](../design-system/COMPONENTS.md), + [`ADOPTION.md`](../design-system/ADOPTION.md), and [`GATES.md`](../design-system/GATES.md). +- Current machine-readable debt: + [`scripts/design-system-contract-baseline.json`](../../scripts/design-system-contract-baseline.json). +- Current flagged owners: + [`src/components/calculators/calculator-ui.tsx`](../../src/components/calculators/calculator-ui.tsx), + [`src/components/ui-primitives.tsx`](../../src/components/ui-primitives.tsx), and + [`src/components/clinical-dashboard/visual-evidence.tsx`](../../src/components/clinical-dashboard/visual-evidence.tsx). +- Screenshot contract and current provenance: + [`docs/design-system/adoption-contract.json`](../design-system/adoption-contract.json) and + [`tests/__screenshots__/linux/provenance.json`](../../tests/__screenshots__/linux/provenance.json). +- Likely proof owners: + [`tests/ckb-v2-token-contract.test.ts`](../../tests/ckb-v2-token-contract.test.ts), + [`tests/design-token-contract.test.ts`](../../tests/design-token-contract.test.ts), + [`tests/design-system-adoption.test.ts`](../../tests/design-system-adoption.test.ts), and + [`tests/ui-accessibility.spec.ts`](../../tests/ui-accessibility.spec.ts). +- Review and PR policy: [`docs/codex-review-protocol.md`](../codex-review-protocol.md) and + [`.github/pull_request_template.md`](../../.github/pull_request_template.md). + +Treat the paths and counts above as starting evidence, not immutable truth. Re-measure at the task +HEAD before editing. Inspect actual definitions, consumers, tests, detector logic, and generated-file +ownership. Do not manually edit a generated baseline if a repository update command owns it. + +### Authority and hard safety boundaries + +- Work in the repository's **offline Cloud profile**. Require `CODEX_CLOUD=1`, + `CODEX_CLOUD_ACCESS_PROFILE=offline`, `RAG_PROVIDER_MODE=offline`, + `NEXT_PUBLIC_DEMO_MODE=true`, and `PLAYWRIGHT_OFFLINE_MODE=true`. +- Do not call OpenAI, Supabase, Railway, GitHub/GitLab APIs, hosted CI, analytics, email, or any other + provider. Do not access production/staging systems or live data. Do not deploy, migrate, reindex, + rotate credentials, print secrets, or create `.env*` files. +- Do not install or update dependencies, switch package managers, loosen engines, or create a new + lockfile. Use the installed Node 24/npm 11 toolchain and the existing `package-lock.json`. +- Do not reset, clean, stash, rebase, force-push, delete branches, overwrite unrelated work, or + weaken tests/contracts to make a check pass. +- You may edit only the three flagged owners, the smallest directly affected tests, and generated + design-contract artifacts that the repository's normal update path demonstrably owns. + `tests/__screenshots__/linux/provenance.json` is permitted only under the truthfulness rule above. + Stop before touching unrelated routes or broad shared foundations. +- A local task commit is authorized after verification. A push or pull request is **not** authorized + by this prompt. Use native Cloud publication controls only if a separate current-task instruction + explicitly authorizes publication; never introduce shell tokens as a workaround. + +### Phase 0 — prove Cloud isolation before any write + +1. Inspect `git status --short --branch`, `git rev-parse HEAD`, upstream/ahead/behind state, relevant + recent commits, and `git worktree list --porcelain`. Check for an active merge, rebase, cherry-pick, + or revert and for repo-owned install/test/build/server processes that could race this work. +2. The checkout must be clean. If it contains any staged, unstaged, or untracked content, stop and + report it; do not absorb, move, stash, delete, or overwrite it. +3. If detached or on `main`, `master`, `develop`, or `release/*`, create + `codex/cloud-design-status-semantics`. Otherwise retain the supplied task branch. +4. Run the repository isolation verifier exactly as documented by + [Prompt Perfector's repository workflow](../../.agents/skills/prompt-perfector/references/repository-workflow.md): + + ```bash + test "${CODEX_CLOUD:-}" = "1" + test -z "$(git status --porcelain --untracked-files=all)" + branch="$(git branch --show-current)" + repo="$(git rev-parse --show-toplevel)" + head="$(git rev-parse HEAD)" + node .agents/skills/prompt-perfector/scripts/verify-repository-isolation.mjs \ + --cloud --expected-repo "$repo" --expected-branch "$branch" --expected-head "$head" + ``` + + Proceed only if it emits `SAFE_TO_EDIT=true` and `PRECHECK_RESULT=SAFE`. Re-run it immediately + before the first edit. This verifies repository workflow isolation, not an OS-level sandbox. + +5. Confirm runtime/install/browser readiness without mutating dependencies: + + ```bash + node --version + npm --version + npm run check:codex-cloud + npm run check:installed-lock-parity + npm run check:playwright-browser-revision + ``` + + A browser-revision mismatch is an environment limitation, not permission to substitute a random + browser executable. Continue with static/DOM proof and hand browser evidence to matching CI/local + infrastructure as documented in `docs/codex-cloud.md`. + +### Phase 1 — inspect, classify, and lock the plan + +State one line before planning: **plan effort high; build effort medium-high; the risk is changing +clinical state meaning or falsely certifying visual evidence.** + +1. Read the repository skills for `plan`, `ui`, `clinical`, `test`, `review`, and `handover`; apply + only their relevant steps. Do not install new skills or invent a parallel workflow. +2. Because this is a review-sensitive task, run: + + ```bash + npm run ledger:lookup -- HEAD --scope "PR 1 clinical status semantics and baseline provenance" + ``` + + Follow the verdict and `docs/codex-review-protocol.md`. Do not hand-edit ledger records. + +3. Read the relevant installed Next.js 16 guide under `node_modules/next/dist/docs/` before changing + framework-facing UI behavior. Training-data assumptions are not evidence. +4. Run the repository workflows in evidence mode for the exact candidate paths: + + ```bash + npm run workflow:flightplan -- --write-evidence --files \ + src/components/calculators/calculator-ui.tsx,src/components/ui-primitives.tsx,src/components/clinical-dashboard/visual-evidence.tsx,scripts/design-system-contract-baseline.json,tests/__screenshots__/linux/provenance.json + npm run workflow:design-sweep -- --write-evidence + npm run workflow:clinical-proof -- --write-evidence + ``` + +5. Record the measured global counts and per-path counts before editing. Inspect the contract scanner + that produces them. For each of the four flagged occurrences, write a compact classification table: + owner/symbol, rendered state, user-visible meaning, clinical risk, classification, proposed + non-colour channel, and proof owner. +6. Inspect empty, missing, stale, loading, error, and success variants. Specifically try to disprove + that a visually positive state could imply “safe/current” when evidence is absent or stale. +7. Inspect the provenance schema, validation scripts, Git history for the record, and candidate hashes. + The current text may be contradictory; it is not proof that a human reviewed the images. +8. Before implementation, produce a short executable plan naming exact symbols, tests, generated + artifacts, commands, and rollback. If classification requires a clinical/product decision, or the + safe repair exceeds this tranche, stop with the evidence and one concise blocking question. + +### Phase 2 — implement the smallest complete repair + +1. Add or adjust the smallest regression tests first where practical. Tests must prove visible + non-colour differentiation and accessible names; they must not merely snapshot implementation + classes. +2. Prefer existing design-system primitives, semantic tokens, icons, and copy conventions. Do not add + new dependencies, raw palette values, one-off token aliases, decorative motion, or broad component + abstractions. +3. For each real status: + - keep explicit persistent text; + - add a second visual channel that survives authored-colour removal and forced colours; + - keep icon-only decoration hidden from assistive technology when adjacent text already names it; + - preserve keyboard/focus behavior and at least the existing hit target; + - preserve conservative wording for unknown/missing/stale data. +4. For the flagged numeral, remove status semantics from the number itself and render the state beside + it. Ensure reading order and the accessible name remain natural. +5. For a detector false positive, improve detector/test precision only with a focused proof that the + rendered UI never conveys state by colour. Do not add an allowlist merely to hit zero. +6. Update generated contract artifacts only through the existing repository generator/update path + identified during discovery. Confirm both the global count and each original owner's count fall; + search the full diff for relocated equivalents. +7. For provenance, choose exactly one truthful path: + - if genuine human review evidence is supplied in the task context, record only that real identity, + timestamp, source HEAD, and schema-valid disposition; + - otherwise, change the record to a schema-valid pending/non-human state only if repository + contracts explicitly support it and tests prove it; + - otherwise leave the file unchanged and make human disposition an explicit local handoff gate. + Never regenerate or adopt images merely to resolve metadata wording. +8. Reinspect the entire task diff for clinical copy drift, false reassurance, token bypasses, secrets, + unrelated formatting, generated noise, and unintended public contract changes. + +### Phase 3 — adversarial UI proof + +For browser work, first run `npm run ensure`, use only the printed URL, and verify +`/api/local-project-id` identifies this repository. Do not assume a port or attach to an unknown +server. Do not leave a watcher or server running after the task. + +Exercise every changed state at the smallest relevant desktop and phone viewport, including default, +dark, forced-colours, reduced-motion, monochrome (authored colours removed/grayscale), and print. +Check keyboard navigation, visible focus, screen-reader names/reading order, 200% zoom/reflow, loading, +empty, error, stale, and success states where the component supports them. The status must remain +distinguishable when all authored colours are removed, and the UI must not imply that missing or stale +clinical evidence is safe/current. + +Capture candidate evidence only when it helps review. Do not overwrite canonical screenshots or mark +them human-approved. If browser readiness fails, preserve the exact diagnostic and create a precise +local/CI handoff rather than weakening the matrix. + +### Phase 4 — risk-scaled verification + +Run heavy commands sequentially. Start narrowly and add a gate only when it covers a distinct plausible +failure. Determine exact focused selectors from the repository rather than inventing script names. + +Minimum expected ladder: + +1. Directly affected unit/DOM tests for the changed owners and contract scanner. +2. `npm run check:design-system-contract` — proves metric and adoption/design-sync contracts. +3. The focused accessibility/browser journey from `tests/ui-accessibility.spec.ts`, if the matching + locked Chromium revision is available. +4. `npm run check:production-readiness` because the change affects clinical status presentation. +5. Inspect selection with: + + ```bash + npm run verify:pr-local -- --dry-run --files + ``` + + Then run non-dry-run `npm run verify:pr-local` once for PR-ready local handoff if selected policy + requires it. Escalate to `npm run verify:ui` only if shared UI foundations changed or the selector + requires it; do not stack it automatically after focused browser proof. + +6. Run `npm run format`, inspect its diff, include intended formatting, then run + `npm run docs:check-links`, `npm run docs:check-scripts`, and `git diff --check` when documentation + changed. + +When a check fails, reduce it to the smallest reproducer, classify it as change-caused, pre-existing, +flaky, environmental, or provider-blocked, fix only change-caused failures, and rerun the invalidated +proof. Never claim an unrun or receipt-reused check was fresh; identify receipt reuse explicitly. + +### Phase 5 — review, commit, and local handoff + +1. Review the final diff under `docs/codex-review-protocol.md`, findings first and severity-ranked. + Resolve all change-caused high-confidence findings. Append the review record only through + `npm run ledger:append` with the actual full 40-character HEAD, scope, outcome, and checks. +2. Confirm final status contains only coherent task files and allowed workflow/ledger evidence. Exclude + `.local`, caches, logs, browser output, dependencies, secrets, and unrelated artifacts. +3. Create one clear local commit. Do not push or publish unless separately authorized in the active + Cloud task. Report the commit SHA and whether the branch has an upstream. +4. Produce this handoff packet: + - outcome and changed symbols/files; + - before/after global and per-path contract counts; + - classification and repair for each original occurrence; + - adversarial matrix with pass/fail/not-run and evidence path for every state/mode; + - exact commands and decisive results, including reused receipts; + - provenance disposition, evidence basis, and any human-approval gate still open; + - branch, worktree, commit, push, and PR state; + - provider/live checks not run and why; + - remaining risks and the single smallest next action. + +For the **local handoff**, give a copy/paste command sequence that begins by checking out the reported +branch/commit, confirms Node 24/npm 11 and lock parity, runs `npm run ensure`, verifies the printed +project identity URL, and executes only the browser modes that Cloud could not prove. Name the exact +routes, viewports, states, and expected visible/non-colour outcomes. If human screenshot disposition is +still required, list candidate paths and hashes and instruct the human to approve or reject them through +the repository's documented adoption workflow—never by directly editing “approved” metadata. + +### Stop conditions + +Stop and report evidence instead of guessing if: the checkout is dirty or non-isolated; runtime or +lock parity is invalid; a provider/live action becomes necessary; a real clinical/product decision is +required; a genuine reviewer identity is unavailable; the provenance schema cannot represent the +truth; the required repair expands into another convergence tranche; the matching browser cannot be +made available without an install/environment change; or unrelated failures prevent meaningful proof. + +Completion means the bounded implementation is locally committed, all available risk-relevant checks +are honestly reported, both targeted metrics are zero without debt relocation, clinical meaning is +preserved under adversarial modes, and any inherently human or provider-backed gate is handed off +explicitly. It does **not** mean claiming perfection, human approval, deployment, or production proof. diff --git a/scripts/design-system-contract-baseline.json b/scripts/design-system-contract-baseline.json index 4ef06e0f47..d3fd634488 100644 --- a/scripts/design-system-contract-baseline.json +++ b/scripts/design-system-contract-baseline.json @@ -4,8 +4,8 @@ "literalShadowClasses": 0, "legacyTapClasses": 0, "interactiveTapFloorDeclarations": 33, - "colourOnlyStatusIndicators": 3, - "statusColouredNumerals": 1, + "colourOnlyStatusIndicators": 0, + "statusColouredNumerals": 0, "edgeOwnershipConflicts": 18, "onePixelShadowSpreads": 2, "hardcodedCssMotionDurations": 41, @@ -47,13 +47,8 @@ "src/components/forms/forms-search-results-page.tsx": 2, "src/components/ui/chip.tsx": 1 }, - "colourOnlyStatusIndicators": { - "src/components/calculators/calculator-ui.tsx": 1, - "src/components/ui-primitives.tsx": 2 - }, - "statusColouredNumerals": { - "src/components/clinical-dashboard/visual-evidence.tsx": 1 - }, + "colourOnlyStatusIndicators": {}, + "statusColouredNumerals": {}, "edgeOwnershipConflicts": { "src/components/DocumentTagCloud.tsx": 3, "src/components/clinical-dashboard/dashboard-nav.tsx": 1, diff --git a/src/components/calculators/calculator-ui.tsx b/src/components/calculators/calculator-ui.tsx index 41057af302..912cce3a59 100644 --- a/src/components/calculators/calculator-ui.tsx +++ b/src/components/calculators/calculator-ui.tsx @@ -183,6 +183,13 @@ export const toneBar: Record = { danger: "bg-[color:var(--danger)]", }; +const toneBandPattern: Record = { + success: "border-b-2 border-[color:var(--text-heading)]", + info: "border-t-2 border-[color:var(--text-heading)]", + warning: "border-y-2 border-[color:var(--text-heading)]", + danger: "border-2 border-[color:var(--text-heading)]", +}; + export function SeverityPill({ tone, label, className }: { tone: CalculatorTone; label: string; className?: string }) { return ( -
+
{calc.bands.map((band) => (
))} diff --git a/src/components/clinical-dashboard/visual-evidence.tsx b/src/components/clinical-dashboard/visual-evidence.tsx index 4b2b02a7e5..b4788da4cf 100644 --- a/src/components/clinical-dashboard/visual-evidence.tsx +++ b/src/components/clinical-dashboard/visual-evidence.tsx @@ -450,7 +450,7 @@ function EvidenceGapsPanel({ warnings }: { warnings: string[] }) { key={`${warning}:${index}`} className="grid grid-cols-[auto_minmax(0,1fr)] items-start gap-2 rounded-md border border-[color:var(--warning-border)] bg-[color:var(--warning-soft)]/45 px-2.5 py-2" > - + {index + 1}

{warning}

diff --git a/src/components/ui-primitives.tsx b/src/components/ui-primitives.tsx index 24b00b27f7..dec02a1140 100644 --- a/src/components/ui-primitives.tsx +++ b/src/components/ui-primitives.tsx @@ -171,10 +171,10 @@ export const tableCardHeader = export const tableMicroActionRow = "flex min-h-tap flex-wrap items-center gap-1 border-t border-[color:var(--border)] px-2 py-1.5 text-xs font-semibold text-[color:var(--text-muted)] sm:min-h-9"; export const sidebarItem = `flex min-h-tap min-w-0 w-full items-center gap-2 overflow-hidden rounded-lg px-2.5 text-sm font-semibold text-[color:var(--text-muted)] transition hover:bg-[color:var(--surface-subtle)] hover:text-[color:var(--text)] focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[color:var(--focus)] ${controlDisabled}`; -const statusDotBase = "inline-block h-2 w-2 shrink-0 rounded-full"; -export const statusDotReady = `${statusDotBase} bg-[color:var(--success)]`; -export const statusDotReview = `${statusDotBase} bg-[color:var(--warning)]`; -export const statusDotMuted = `${statusDotBase} bg-[color:var(--decoration-soft)]`; +const statusMarkerBase = "inline-block h-2 w-2 shrink-0"; +export const statusDotReady = `${statusMarkerBase} rounded-full border-2 border-[color:var(--text-heading)] bg-transparent`; +export const statusDotReview = `${statusMarkerBase} rotate-45 rounded-sm bg-[color:var(--warning)]`; +export const statusDotMuted = `${statusMarkerBase} rounded-full bg-[color:var(--decoration-soft)]`; export const toneSuccess = "border-[color:var(--success-border)] bg-[color:var(--success-soft)] text-[color:var(--success)]"; diff --git a/tests/status-semantics-contract.test.ts b/tests/status-semantics-contract.test.ts new file mode 100644 index 0000000000..d6c7dd7f5f --- /dev/null +++ b/tests/status-semantics-contract.test.ts @@ -0,0 +1,42 @@ +import { readFileSync } from "node:fs"; + +import { describe, expect, it } from "vitest"; + +import { + findColourOnlyStatusIndicatorsInSource, + findStatusColouredNumeralsInSource, +} from "../scripts/design-system-contract-utils.mjs"; + +const owners = [ + "src/components/calculators/calculator-ui.tsx", + "src/components/ui-primitives.tsx", + "src/components/clinical-dashboard/visual-evidence.tsx", +] as const; + +function source(path: (typeof owners)[number]) { + return readFileSync(new URL(`../${path}`, import.meta.url), "utf8"); +} + +describe("clinical status semantics", () => { + it.each(owners)("keeps %s free of colour-only status and status-coloured numerals", (path) => { + const contents = source(path); + expect(findColourOnlyStatusIndicatorsInSource(path, contents)).toEqual([]); + expect(findStatusColouredNumeralsInSource(path, contents)).toEqual([]); + }); + + it("gives every calculator severity tone a distinct non-colour edge pattern", () => { + const calculator = source("src/components/calculators/calculator-ui.tsx"); + expect(calculator).toContain('success: "border-b-2 border-[color:var(--text-heading)]"'); + expect(calculator).toContain('info: "border-t-2 border-[color:var(--text-heading)]"'); + expect(calculator).toContain('warning: "border-y-2 border-[color:var(--text-heading)]"'); + expect(calculator).toContain('danger: "border-2 border-[color:var(--text-heading)]"'); + expect(calculator).toContain("aria-label={`Score severity scale from ${calc.minScore} to ${calc.maxScore}`}"); + }); + + it("distinguishes ready, review, and muted markers by geometry as well as tone", () => { + const primitives = source("src/components/ui-primitives.tsx"); + expect(primitives).toContain("statusDotReady = `${statusMarkerBase} rounded-full border-2"); + expect(primitives).toContain("statusDotReview = `${statusMarkerBase} rotate-45 rounded-sm"); + expect(primitives).toContain("statusDotMuted = `${statusMarkerBase} rounded-full bg"); + }); +});