diff --git a/docs/clinical-badge-system-guide.md b/docs/clinical-badge-system-guide.md index d137102bf..9378f5376 100644 --- a/docs/clinical-badge-system-guide.md +++ b/docs/clinical-badge-system-guide.md @@ -39,14 +39,14 @@ Static badges must not look clickable. Interactive chips must use proper button Use six top-level tones only. Do not add more badge colours. -| Tone | Meaning | Examples | Do not use for | -| --------------- | -------------------------------------------- | --------------------------------------------------------------------------------- | ---------------------------------------- | -| Neutral / slate | Reference metadata and passive facts | `333 mg EC tablet`, `Item 8357W`, `Campral`, `p.4`, `PDF`, `Max 1,998 mg/day` | Urgent risks, actions, or trust state | -| Clinical / teal | Action to take | `666 mg TID`, `Monitor renal`, `Take with food`, `Check baseline` | Verified/current/source-backed state | -| Success / green | Confirmed, current, available, source-backed | `Reviewed`, `Current`, `Source-backed`, `PBS streamlined`, `Completed` | Clinical safety decisions | -| Warning / amber | Pause, check, adjust, uncertain, limited | `Reduce <60 kg`, `Review due`, `Partial support`, `Limited evidence`, `Avoid >65` | Hard stops or contraindications | -| Danger / red | Stop, avoid, failed, unsafe | `Cr >120 avoid`, `Contraindicated`, `Outdated`, `Failed`, `Do not use` | Routine adverse effects or mild cautions | -| Info / blue | System or process information | `Processing`, `Syncing`, `Pending`, `Importing` | Core clinical meaning | +| Tone | Meaning | Examples | Do not use for | +| ----------------- | -------------------------------------------- | --------------------------------------------------------------------------------- | ---------------------------------------- | +| Neutral / slate | Reference metadata and passive facts | `333 mg EC tablet`, `Item 8357W`, `Campral`, `p.4`, `PDF`, `Max 1,998 mg/day` | Urgent risks, actions, or trust state | +| Clinical / Aegean | Action to take | `666 mg TID`, `Monitor renal`, `Take with food`, `Check baseline` | Verified/current/source-backed state | +| Success / green | Confirmed, current, available, source-backed | `Reviewed`, `Current`, `Source-backed`, `PBS streamlined`, `Completed` | Clinical safety decisions | +| Warning / amber | Pause, check, adjust, uncertain, limited | `Reduce <60 kg`, `Review due`, `Partial support`, `Limited evidence`, `Avoid >65` | Hard stops or contraindications | +| Danger / red | Stop, avoid, failed, unsafe | `Cr >120 avoid`, `Contraindicated`, `Outdated`, `Failed`, `Do not use` | Routine adverse effects or mild cautions | +| Info / blue | System or process information | `Processing`, `Syncing`, `Pending`, `Importing` | Core clinical meaning | Do not add purple, pink, orange, cyan, or extra medication-specific badge colours. Orange collapses into amber. Purple should not be used for clinical badges because it reads as product or AI styling rather than clinical meaning. @@ -54,7 +54,7 @@ Do not add purple, pink, orange, cyan, or extra medication-specific badge colour Green means trusted, current, reviewed, available, or source-backed. It does not mean clinically safe. -Teal means a clinical action or instruction. It does not mean good, safe, or verified. +The clinical accent (Aegean blue-teal) means a clinical action or instruction. It does not mean good, safe, or verified. Amber means pause, check, adjust, review, or interpret with caution. @@ -402,14 +402,14 @@ Avoid code-facing colour names such as `green`, `red`, `amber`, or `slate` for n Map semantic tones to existing tokens: -| Semantic tone | Existing style direction | -| ------------- | ----------------------------------- | -| `neutral` | `toneNeutral` / metadata pill | -| `clinical` | clinical teal token | -| `success` | `toneSuccess` | -| `warning` | `toneWarning` or `toneWarningQuiet` | -| `danger` | `toneDanger` | -| `info` | `toneInfo` | +| Semantic tone | Existing style direction | +| ------------- | ------------------------------------------- | +| `neutral` | `toneNeutral` / metadata pill | +| `clinical` | clinical accent token (`--clinical-accent`) | +| `success` | `toneSuccess` | +| `warning` | `toneWarning` or `toneWarningQuiet` | +| `danger` | `toneDanger` | +| `info` | `toneInfo` | ## Accessibility Requirements @@ -476,7 +476,7 @@ Avoid: - badge every answer bullet - use green for "safe" - use red for routine side effects -- use teal for verified/current +- use the clinical accent for verified/current - use blue for clinical action - add purple for AI - add orange beside amber diff --git a/docs/clinical-chat-ui-component-map.md b/docs/clinical-chat-ui-component-map.md index 2657884e0..c95e81a16 100644 --- a/docs/clinical-chat-ui-component-map.md +++ b/docs/clinical-chat-ui-component-map.md @@ -2,6 +2,8 @@ Date: 2026-06-24 +> **Colour direction superseded (July 2026).** This Phase-2 mapping artifact is retained as history. Its colour aliases ("deep teal", "pale teal", "clinical sand", "document blue-grey") predate the **Clinical White / Aegean Graphite** role tokens now in `globals.css`; see [`redesign/02-design-direction.md`](redesign/02-design-direction.md) and [`redesign/permanent-colour-direction.md`](redesign/permanent-colour-direction.md). Read colour references as the role tokens `--command` (graphite), `--clinical-accent` (Aegean), and `--success` (green, success-only). + ## Purpose This document translates the approved clinical chat UI direction into a practical component-level implementation map. It identifies what each current UI area should become, which files are likely involved, what should be preserved, and what should be moved, collapsed, or restyled. diff --git a/docs/clinical-chat-ui-implementation-plan.md b/docs/clinical-chat-ui-implementation-plan.md index 8a1c69409..d0f045fce 100644 --- a/docs/clinical-chat-ui-implementation-plan.md +++ b/docs/clinical-chat-ui-implementation-plan.md @@ -2,6 +2,8 @@ Date: 2026-06-23 +> **Colour direction superseded (July 2026).** The layout, interaction, and answer-first plan below still stands, but its colour language predates the **Clinical White / Aegean Graphite** role-split; see [`redesign/02-design-direction.md`](redesign/02-design-direction.md) and [`redesign/permanent-colour-direction.md`](redesign/permanent-colour-direction.md). Where this doc says "teal", read the role tokens: `--command` (graphite) for primary actions and `--clinical-accent` (Aegean blue-teal) for evidence/selected/send/focus; green is success-only. + ## Purpose This document captures the agreed implementation plan for mapping the final ChatGPT-inspired clinical chatbot mockups into the application faithfully. It is intentionally written before code changes so implementation can proceed in controlled visual slices with clear acceptance criteria. diff --git a/docs/redesign/07-token-adoption-audit.md b/docs/redesign/07-token-adoption-audit.md new file mode 100644 index 000000000..bb7e6562d --- /dev/null +++ b/docs/redesign/07-token-adoption-audit.md @@ -0,0 +1,80 @@ +# Token Adoption Audit — Clinical KB (July 2026) + +## July 3 run — design-token adoption sweep across `src/components` + +This run audits **how consistently the codebase consumes the design tokens**, not the +token system itself. The token _foundation_ in `src/app/globals.css` is strong; the +findings below are all about call-site adoption drift — tokens that exist but are +reached past, defined-but-unused utilities, and hardcoded values that bypass the scale. + +Scope: `src/components` (50 `.tsx` files, ~40 className recipes in +`src/components/ui-primitives.tsx`) plus a repo-wide check for the `@theme inline` +bridge utilities. Two files carry most of the palette leaks +(`ClinicalDashboard.tsx`, `differentials/differential-presentation-workflow-page.tsx`) +and are both active mockup surfaces on `feature/tools-page-mockups` — treat their +findings as "clean before the pattern spreads," not shipped-primitive regressions. + +**Score: 78/100** — 0 critical · 3 medium · 6 low. + +## Summary + +| Area | State | Note | +| ------------------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------- | +| Token foundation | Keep | Full neutral + accent ramps, semantic triads, dark, forced-colors, reduced-motion, elevation, motion, safe-areas. Best-in-class. | +| Color discipline (hex) | Keep | 0 hardcoded hex in components (1 legit SVG logo fill). Palette leaks contained to 2 mockup files. | +| Token-access consistency | Fix | A defined-but-dead utility bridge means two ways to reach every color; the verbose form is used universally. | +| Type scale | Fix | Scale mostly followed, but ~295 hardcoded px font sizes; the `text-2xs` token is defined yet unadopted. | +| File naming | Polish | PascalCase vs kebab-case split, mixed inside the same folder. | +| Component docs | Polish | Recipe pattern is sound but has no documented state/variant contract. | + +## Findings + +### Naming consistency + +| Location | Finding | Class | Planned action | Tier | +| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | -------------------------------------------------------- | ---- | +| `src/components/*` file names | 11 PascalCase files (`ClinicalDashboard`, `ClinicalSidebar`, `DocumentManagerPanel`…) vs ~39 kebab-case, **mixed inside the same folder** (`clinical-dashboard/ClinicalSidebar.tsx` next to `dashboard-shell.tsx`). | Polish | Standardize on kebab-case (majority + newer convention). | 3 | +| `src/components/ServiceDetailPage.tsx` | 1-line re-export shim to `services/service-detail-page.tsx`; PascalCase shims keep the naming drift alive. | Polish | Track for removal once import paths are migrated. | 3 | + +### Token coverage + +| Location | Finding | Class | Planned action | Tier | +| --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | +| `globals.css:46-77` (`@theme inline` bridge) | **M1.** Defines `--color-surface`/`--color-muted`/`--color-heading`/`--color-clinical-accent`… → generates `bg-surface`/`text-muted`/`text-heading` utilities. **Repo-wide usage: 0.** All ~1374 call sites use the verbose `text-[color:var(--text-muted)]` form instead. The line-45 comment ("lets new/refactored code use bg-surface, text-muted") is aspirational — no code does. | Fix | Decide: adopt short utilities repo-wide (1374-site churn) **or** delete the dead bridge + fix the comment (small, safe — zero-usage confirmed across `src`). | 2 | +| `ClinicalDashboard.tsx:6052-6055`; `differential-presentation-workflow-page.tsx:47-72` | **M2.** Hand-rolled tone helpers re-implement the danger/info/warning/success triads with raw Tailwind palette classes (`border-red-200 bg-red-50 text-red-700`). They **don't respond to `.dark`** and are mutually inconsistent (differentials maps *warning*→`rose`; the `--warning-*` token is amber). 27 raw-palette instances, confined to these 2 mockup files. | ✅ Done | **Resolved on `feature/tools-page-mockups`.** All raw-palette instances routed through the `--danger`/`--info`/`--warning`/`--success` triads (+ `bg-white`→`--surface`); verified 0 raw-palette / `bg-white` remain, all tokens resolve in light + `.dark` + `forced-colors`. **Correction to the prescription:** differentials `warning` → `--danger` (red), **not** amber — that tone renders "Must-not-miss" red-flags (`src/lib/differentials.ts`); amber would understate a safety-critical signal. Amber `--warning` stays reserved for `status === "urgent"`. | 2 | +| `text-[11px]` ×142 (`text-2xs` ×2), `text-[10px]` ×58, `text-[15px]` ×45, `text-[13px]` ×30, +8/9px | **M3.** ~295 hardcoded px font sizes bypass the scale. `--text-2xs` (11px) is defined with its own line-height + letter-spacing yet almost unused. Sub-`xs` (8–10px) and "between" sizes (13px, 15px) have **no** scale tokens. Default scale is otherwise well followed (`text-xs` ×452, `text-sm` ×383). | Fix | Add tokens for 13/15px (optionally 8–10px). **Note:** `text-[11px]`→`text-2xs` is _not_ a pure swap — `text-2xs` adds `letter-spacing: 0.06em` + `line-height: 1rem`, so it changes rendering. Needs a visual pass, not a codemod. | 2 | +| `bg-white` ×7, `text-white`/`ring-white` ×35, `bg-black` ×1 | **L4.** Hardcoded white/black neutrals. `bg-white` is the real dark-mode risk (should be `--surface`); `text-white`/`ring-white` on accent buttons should use `--clinical-accent-contrast` / `--command-contrast`. | Polish | Swap `bg-white`→`--surface`; accent-button text→`*-contrast` tokens. | 2 | +| `ClinicalDashboard.tsx:6138` | **L5.** Hardcoded `border-blue-400` + arbitrary accent shadow bypasses `--clinical-accent` / `--glow-*`. | Polish | Use accent + glow tokens. | 3 | +| `min-h-[44px]`/`min-h-[48px]`/`min-w-[48px]`/`h-[44px]`/`w-[44px]` ~74× | **L6.** Repeated WCAG tap-target magic numbers with no token. Good that the minimums exist; bad that they're copy-pasted px. | ✅ Done | **Resolved by standardizing on the default `-11`/`-12` scale, not a new token.** The codebase already had two 44px conventions — arbitrary `[44px]` (69×) _and_ scale `-11` (164×, adopted by the design-review commit); `-11` is also used for decorative 44px, so a semantic `-tap` token would need per-site tap-vs-decorative judgment across ~200 sites. Swapped the 69 arbitrary `min-h-[44px]`→`min-h-11`, `[48px]`→`min-h-12`, `h/w-[44px]`→`h/w-11`, `min-w-[48px]`→`min-w-12` (output-identical) across 8 files; 0 arbitrary tap tokens remain repo-wide. | 3 | +| `rounded-[var(--radius-lg)]` ×4 | **L7.** Token reached the long way when the `rounded-lg` utility exists. | Polish | Replace with `rounded-lg`. | 3 | + +### Component layer + +| Location | Finding | Class | Planned action | Tier | +| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | +| `ui-primitives.tsx` (~40 recipes) | **L8.** The "component library" is ~40 className _recipes_ (`primaryControl`, `fieldControl`, `metadataPill`…) + `cn()`, plus one real React component (`ui/sheet.tsx`). Solid pattern, but no documented state contract (hover/active/disabled/loading) per recipe and no docs file. | ✅ Done | **Reference written: `09-ui-primitives-recipes.md`** — documents the pattern, the state/variant contract (tap-size / hover / active / focus-visible / disabled / loading), a full recipe catalog, and the React components. It also surfaces the contract **gaps** (e.g. `focus-visible` missing on the `controlBase` button family) as a11y follow-ups. | 3 | + +## Priority actions + +1. **M1 — ✅ DONE.** The dead `@theme inline` colour bridge + misleading comment were + deleted from `globals.css` (0 consumers across `src`, confirmed). Change lives in the + working tree; ensure it lands with the branch. +2. **M2 — ✅ DONE (`feature/tools-page-mockups`).** Both mockup files' tone helpers now + route through the semantic triads (dark-mode-safe). Correction: differentials + `warning` resolved to `--danger` (red), not amber — it renders "Must-not-miss" + red-flags. _(NB: this file was re-clobbered to raw `rose` once by concurrent WIP and + re-fixed — keep an eye on it until committed.)_ +3. **M3 — partly unblocked.** The missing scale tokens have since been **added** to + `@theme` (`--text-4xs` 8px, `--text-3xs` 10px, `--text-2xs` 11px [now tracking-free], + `--text-sm-minus` 13px, `--text-base-minus` 15px), and they are intentionally + **size-only** — so `text-[Npx]`→token is now a _pure_ swap for exact-match sizes + (8/10/11/13/15px), no longer the tracking-shifting hazard the original note warned + about. **Remaining:** adopt the tokens (~295 `text-[Npx]` sites); `text-[9px]` has no + exact token (snaps to 8px `--text-4xs`) so needs a per-site call, not a blind swap. + +## Method / reproduce + +- Hardcoded hex: `rg '#[0-9a-fA-F]{3,8}\b' src/components -g '*.tsx'` +- Raw palette: `rg '\b(bg|text|border|ring|from|to|via|fill|stroke)-(gray|slate|…|rose)-(50|…|950)\b' src/components -g '*.tsx'` +- Dead bridge: `rg '("|'"'"'| )(bg-surface|text-muted|text-heading|…)( |"|'"'"')' src` → 0 hits. +- Arbitrary values ranked: `rg -oN '…-\[[^]]+\]' src/components -g '*.tsx' | sort | uniq -c | sort -rn` diff --git a/docs/redesign/08-design-review-prompt.md b/docs/redesign/08-design-review-prompt.md new file mode 100644 index 000000000..ee4e1df6e --- /dev/null +++ b/docs/redesign/08-design-review-prompt.md @@ -0,0 +1,252 @@ +# Design Review Prompt — Clinical KB (July 2026) + +Two reusable prompts for reviewing design work on this product, tuned to its +context: a clinical knowledge-base used by clinicians under time pressure, built +on a tiered design-token system (primitive → semantic → component), a shared +`ui/` component layer, Next.js, and mobile bottom-sheet patterns. + +- **Full review (v2)** — a rigorous, end-to-end pass for a whole screen, flow, or + new pattern. Covers 25 dimensions plus formal heuristic and cognitive lenses. + Use it for redesigns, new surfaces, and pre-release confidence. +- **PR-pass checklist** — a fast, ~10-point gate for a single component or small + change in a pull request. Use it when the full review is too heavy. + +Paste the relevant block to a reviewer (human or AI) alongside the mockup, +screenshot, Figma link, or running screen. For clinical/answer/source/privacy +changes, pair the review with the governance preflight in +`.github/pull_request_template.md`. + +## Full review (v2) + +```markdown +# Design Review Prompt (v2) + +## Role + +You are a senior product designer running a rigorous, end-to-end design review +of the attached screen(s)/flow/component. The product is a clinical +knowledge-base used by clinicians, often under time pressure and sometimes at +the point of care. It uses a tiered design-token system (primitive → semantic → +component), a shared `ui/` component layer, Next.js, and mobile bottom-sheet +patterns. Optimize for clinical safety, clarity, speed, and consistency — +never novelty for its own sake. + +## Evaluation lenses (apply throughout) + +- Nielsen's 10 heuristics: visibility of system status; match to real world; + user control & freedom; consistency & standards; error prevention; + recognition over recall; flexibility & efficiency; aesthetic & minimalist + design; help users recognize/recover from errors; help & documentation. +- Cognitive principles: Gestalt grouping (proximity/similarity/closure); + Fitts's law (target size & distance); Hick's law (limit choices); + Miller's law (chunk information); recognition over recall; Jakob's law + (respect platform/web conventions users already know). + +## How to review + +For EVERY dimension below: + +1. Note briefly what works and should be preserved. +2. List problems, each as: **[Severity]** — location — why it hurts THIS user + in THIS context — a specific, testable fix (name the token/component). +3. Mark findings **Confirmed** (visible in the artifact) vs **Needs testing** + (requires the running app, a user, or a device to verify). +4. Write "N/A" for dimensions that don't apply, and say why. + +Severity: + +- **Blocker** — unsafe, broken, or blocks the core task / fails WCAG A. +- **High** — significant friction, confusion, or inconsistency; fails WCAG AA. +- **Medium** — noticeable but non-blocking; polish or consistency gap. +- **Low** — minor / subjective refinement. + +## Dimensions + +### A. Purpose & strategy + +Who is the user, in what context, trying to do what? Is the primary task the +clearest path and the primary action the most prominent element? Anything on +screen that doesn't serve the core job? + +### B. Information architecture & navigation + +Grouping/labeling match the user's mental model? Always clear where you are and +where you can go? Search/filter/sort discoverable and predictable? + +### C. Interaction & flow + +Walk the happy path + 2–3 edge paths; find dead-ends, extra steps, ambiguity. +Are ALL states designed and distinguishable: default, hover, focus, active, +disabled, selected, loading, empty, error? Is system status always visible? +Are destructive/irreversible actions confirmed or undoable? Is perceived +latency handled (skeletons, optimistic UI)? + +### D. Visual design + +Layout/grid/alignment/spacing rhythm consistent? Clear visual hierarchy? Type +scale, weight, line-height, and readable line length applied consistently and +semantically? Color: semantic roles correct, never the ONLY signal? Elevation, +radius, borders, shadows, and motion consistent and purposeful? + +### E. Forms & data entry + +Required vs optional clearly signaled? Validation timing sensible (not +prematurely aggressive)? Errors shown inline AND summarized, phrased as fixes? +Correct input types/keyboards/masks/autofill? Sensible defaults? Long-form and +partially-complete states handled? + +### F. Data-dense views & tables + +Sorting/filtering/pagination/bulk-actions clear? Column priority right on small +screens? Density appropriate (and a compact/comfortable option if needed)? +Scanning supported (alignment, zebra, sticky headers)? + +### G. Data visualization + +Chart type fits the question? No distortion (truncated axes, misleading area)? +Colorblind-safe with redundant encoding (not color alone)? Accessible +(labels/table fallback)? Legible at target sizes? + +### H. Overlays, layering & notifications + +Right container for the job (inline vs popover vs sheet vs modal)? Focus trap + +restore, and clear dismissal (Esc/backdrop/close)? Toast vs banner vs modal +used correctly by urgency/persistence? Coherent z-index/stacking system? + +### I. Search & autocomplete + +Zero-result, suggestion, recent-search, and scoped-search states designed? +Query correction / "did you mean" / synonyms? Result relevance and provenance +legible? Latency and empty-query states handled? + +### J. Content & UX writing + +Labels/buttons/microcopy specific and action-oriented? Error/empty/help copy +human and actionable? Terminology consistent and clinically accurate? Scannable? + +### K. Efficiency & power use + +Keyboard shortcuts / command palette for frequent actions? Smart defaults and +prefill reduce work? Bulk operations where volume warrants? Repeat tasks fast? + +### L. Onboarding, help & education + +First-run and empty states teach the feature? Contextual help/tooltips where +concepts are non-obvious? Path to fuller docs without leaving the task? + +### M. Design system & consistency + +Tokens used for color/space/type/radius/elevation (no hardcoded one-offs)? +Shared `ui/` components reused, not re-invented? Matches patterns elsewhere? +Internal, platform (Jakob's law), and real-world/clinical conventions honored? + +### N. Accessibility (audit explicitly — don't assume) + +Text & non-text contrast meet WCAG AA? Fully keyboard-operable, logical focus +order, visible focus? Correct semantics/ARIA, labeled icon-only controls? Touch +targets ≥44px with spacing? `prefers-reduced-motion` respected? `forced-colors` +/ Windows high-contrast keeps everything visible and usable? Works at 200% zoom +/ reflow without loss? + +### O. Responsive & cross-platform + +Holds up at mobile/tablet/desktop? Mobile patterns (bottom sheets, safe areas, +thumb reach) correct? Touch vs pointer affordances right? Orientation/reflow OK? + +### P. States & resilience + +Empty, first-run, loading, error, offline, permission-denied, and timeout states +designed? Behavior at 0 / 1 / many / very-many items and with very long text +(truncation, wrap, overflow)? + +### Q. Temporal & real-time + +Timeouts, session expiry, and auto-save handled gracefully? Real-time updates, +staleness, and "data as of