diff --git a/data/repo-awareness-snapshot.json b/data/repo-awareness-snapshot.json index eda565017d..5d9b7f11d9 100644 --- a/data/repo-awareness-snapshot.json +++ b/data/repo-awareness-snapshot.json @@ -1,8 +1,8 @@ { "version": "repo-awareness-snapshot-v1", "captured_revision": { - "sha": "59bb01b3e5c6b5c846053d2916d3e780ea38bbb1", - "committed_at": "2026-08-27T05:20:05+00:00" + "sha": "284454e511a503567e9e984dbc01ae0390c37153", + "committed_at": "2026-08-27T18:45:24+08:00" }, "routes": { "modes": [ @@ -2386,6 +2386,11 @@ "section": "design-system", "catalogued": true }, + { + "path": "docs/design-system/FIX-GUIDE.md", + "section": "design-system", + "catalogued": true + }, { "path": "docs/design-system/GATES.md", "section": "design-system", @@ -2399,7 +2404,7 @@ { "path": "docs/design-system/README.md", "section": "design-system", - "catalogued": false + "catalogued": true }, { "path": "docs/design-system/SPEC.md", @@ -3867,9 +3872,9 @@ } ], "counts": { - "documents": 480, - "catalogued": 106, - "uncatalogued": 374, + "documents": 481, + "catalogued": 108, + "uncatalogued": 373, "sections": 19 } }, diff --git a/docs/README.md b/docs/README.md index 6098437cc7..aa9dc406e3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -30,13 +30,15 @@ npm run docs:check-links - [search-results-bar-decisions.md](search-results-bar-decisions.md) — shared results-bar anatomy, why the filter shelf is scoped to two modes, and what is deliberately not done - [deployment-architecture.md](deployment-architecture.md) — app/worker/Supabase deployment topology - [ingestion-state-machine.md](ingestion-state-machine.md) — ingestion job lifecycle and states -- [design-system.md](design-system.md) — tokens, primitives, styling conventions +- [design-system/README.md](design-system/README.md) — front door for the v2 design system (tokens, components, gates) +- [design-system.md](design-system.md) — live-layer notes during the v1→v2 transition (superseded as spec) - [design-system/SPEC.md](design-system/SPEC.md) — the complete v2 design system: roles, rules, rationale (never values) - [design-system/TOKENS.md](design-system/TOKENS.md) — reconciled token inventory: every role, winning name, owner, and what it replaces - [design-system/COMPONENTS.md](design-system/COMPONENTS.md) — the eight safety-component specifications plus the maturity matrix - [design-system/DECISIONS.md](design-system/DECISIONS.md) — conflicts C1–C5 resolved, clinical Q&A record, assumptions, blocked items - [design-system/GATES.md](design-system/GATES.md) — every design-system rule paired with its enforcement status - [design-system/ADOPTION.md](design-system/ADOPTION.md) — PR 13 registration record: adoption order, per-surface file allowlists, exclusions, pins, proof shots +- [design-system/FIX-GUIDE.md](design-system/FIX-GUIDE.md) — Hazard 1–2 sweep dispositions (Fixed / Documented / Deferred / Out-of-scope) - [comparison-behaviour.md](comparison-behaviour.md) — shared selection, state, responsive, and accessibility contract for comparison surfaces - [clinical-chat-ui-component-map.md](clinical-chat-ui-component-map.md) — chat UI component inventory - [clinical-badge-system-guide.md](clinical-badge-system-guide.md) — clinical badge semantics diff --git a/docs/branch-review-records/be0d35ad96adbaa5219303ff8595fd560ba330b3fc03c79f10d2dabdf35b4921.record.md b/docs/branch-review-records/be0d35ad96adbaa5219303ff8595fd560ba330b3fc03c79f10d2dabdf35b4921.record.md new file mode 100644 index 0000000000..7fcbf174b9 --- /dev/null +++ b/docs/branch-review-records/be0d35ad96adbaa5219303ff8595fd560ba330b3fc03c79f10d2dabdf35b4921.record.md @@ -0,0 +1 @@ +| 2026-08-27 | ds-hazard-1-2-sweep | 19ee085b1cc952e8c40e893fb2fce99538415259 | design-system hazard 1-2 | P2 SPEC.md:217-218 still requires per-step -lh/-tr against gated deletion; P3 GATES evidence header still not-re-run; no P0/P1 | test:focused --files token,adoption,responsive,reachability: fail-closed exit 2 (tests/** unsafe); run-vitest same files blocked by exclusive coordinator (browser-test-gate-handoff-d5c1db); check:design-system-contract not run; verify:cheap/ui/pr-local and providers skipped | diff --git a/docs/codebase-index.md b/docs/codebase-index.md index 8b06bdefb1..72fe2f8b50 100644 --- a/docs/codebase-index.md +++ b/docs/codebase-index.md @@ -9,28 +9,28 @@ Structured map for AI agents and onboarding. For live routes, see `docs/site-map ## Quick start -| Step | Command | -| --------------------------------- | -------------------------------- | -| Confirm Supabase target | `npm run check:supabase-project` | -| Start app (project-specific port) | `npm run ensure` | -| Start ingestion worker | `npm run worker` | -| Cheap verification gate | `npm run verify:cheap` | -| UI verification gate | `npm run verify:ui` | +| Step | Command | +| --------------------------------- | -------------------------------------------------------------------------------- | +| Confirm Supabase target | `npm run check:supabase-project` (provider-backed — needs explicit confirmation) | +| Start app (project-specific port) | `npm run ensure` | +| Start ingestion worker | `npm run worker` | +| Cheap verification gate | `npm run verify:cheap` | +| UI verification gate | `npm run verify:ui` | --- ## Top-level layout -| Path | Purpose | -| ----------- | ---------------------------------------------------------------- | -| `src/` | Next.js App Router UI, API routes, shared lib, components | -| `supabase/` | SQL migrations, schema mirror, Edge Functions, CLI config | -| `worker/` | Local ingestion worker (parse, OCR, chunk, embed, DB writes) | -| `scripts/` | CLI ops: reindex, eval, backfill, governance, dev-server helpers | -| `tests/` | Vitest unit (`*.test.ts`) + Playwright E2E (`ui-*.spec.ts`) | -| `docs/` | Runbooks, governance, search/RAG plans, generated sitemap | -| `public/` | Static assets (`public/llms.txt`) | -| `.github/` | CI workflows, PR template (clinical governance preflight) | +| Path | Purpose | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `src/` | Next.js App Router UI, API routes, shared lib, components | +| `supabase/` | SQL migrations, schema mirror, Edge Functions, CLI config | +| `worker/` | Local ingestion worker (parse, OCR, chunk, embed, DB writes) | +| `scripts/` | CLI ops: reindex, eval, backfill, governance, dev-server helpers | +| `tests/` | Vitest unit (`*.test.ts`) + Playwright E2E (`ui-*.spec.ts`) | +| `docs/` | Runbooks, governance, search/RAG plans, generated sitemap; design-system system of record is [`docs/design-system/README.md`](design-system/README.md) | +| `public/` | Static assets (`public/llms.txt`) | +| `.github/` | CI workflows, PR template (clinical governance preflight) | Smaller top-level directories that are easy to miss: diff --git a/docs/design-system-contract.md b/docs/design-system-contract.md index ce96a3b554..aa7e2d9d73 100644 --- a/docs/design-system-contract.md +++ b/docs/design-system-contract.md @@ -25,11 +25,11 @@ npm run check:icon-scale - **Tokens Only**: Raw CSS hex codes (e.g. `#007a78`, `#ffffff`), RGB/RGBA, HSL, and un-tokenized Tailwind color classes (e.g. `bg-white`, `text-slate-900`, `border-red-200`) are prohibited in components. - **Variable Syntax**: All colors must use CSS custom properties defined in `src/app/globals.css` with semantic purpose: - **Brand & Clinical Accent**: `var(--clinical-accent)`, `var(--clinical-accent-hover)`, `var(--clinical-accent-soft)`, `var(--clinical-accent-border)` - - **Surfaces & Borders**: `var(--surface)`, `var(--surface-subtle)`, `var(--surface-wash)`, `var(--surface-lux)`, `var(--border)`, `var(--border-subtle)` - - **Text Roles**: `var(--text)`, `var(--text-muted)`, `var(--text-heading)`, `var(--text-soft)` + - **Surfaces & Borders**: `var(--surface)`, `var(--surface-subtle)`, `var(--surface-wash)`, `var(--surface-lux)`, `var(--border)`, `var(--border-strong)`, `var(--border-lux)` + - **Text Roles**: `var(--text)`, `var(--text-muted)`, `var(--text-heading)`. `--text-soft` is decoration (`--decoration-soft`), not a text role. - **Status & Safety Triads**: `--success-*`, `--warning-*`, `--danger-*`, `--info-*` (reserved exclusively for clinical/system status). - **Focus Ring & Outlines**: `var(--focus)` for all keyboard and visible focus rings. -- **Raw Color Exemptions**: Strict and enumerated in `RAW_COLOR_EXEMPTIONS` in `scripts/design-system-contract-utils.mjs` (e.g., globals token definitions, brand mark SVG builder, diagnostic visualizations, OpenGraph art, printable patient/factsheet paper). +- **Raw Color Exemptions**: Strict and enumerated in `RAW_COLOR_EXEMPTIONS` in `scripts/design-system-contract-utils.mjs` (e.g., globals token definitions, brand mark SVG builder, diagnostic visualizations, OpenGraph art, printable patient/factsheet paper). Medication record accent defaults (`#0f766e` in `src/lib/medications.ts` and `src/lib/medication-records.ts`) are a **scoped** exemption for the Postgres `accent` column default only — not a whole-file blank cheque, and not a mapping onto `--clinical-accent`. ### 2.2 Typography Scale @@ -47,7 +47,7 @@ npm run check:icon-scale - **Elevation**: Monotonic numeric scale `var(--e0)` through `var(--e4)`. No raw `box-shadow` values. - **Edge Ownership**: Prohibits simultaneous `border-*` and `ring-*` styling on the same surface to prevent clipped or competing boundaries. -- **Motion Durations**: Transitions and animations must use standardized duration tokens (`var(--duration-fast)`, `var(--duration-normal)`) and respect `motion-reduce:`. Layout-property animation (e.g., width, height, padding) is disallowed except for explicitly audited phone-chrome transitions. +- **Motion Durations**: Transitions and animations must use standardized duration tokens (`var(--duration-fast)`, `var(--duration-base)`) and respect `motion-reduce:`. Layout-property animation (e.g., width, height, padding) is disallowed except for explicitly audited phone-chrome transitions. --- diff --git a/docs/design-system/ADOPTION.md b/docs/design-system/ADOPTION.md index 48c1667001..1a5a3fcb67 100644 --- a/docs/design-system/ADOPTION.md +++ b/docs/design-system/ADOPTION.md @@ -5,7 +5,7 @@ of truth is `adoption-contract.json`; the generated manifest and marked tables i must match it exactly. - **Date:** 12 August 2026 -- **Current state:** 54 visual references are locally registered; all 51 production page routes +- **Current state:** 55 visual references are locally registered; all 51 production page routes are owned across 14 surface families, with 59 route/component roots scanned; every declared root uses the v2 shell and has declared proof with no committed visual baseline. - **Phase 1 blockers resolved first, in their own commits:** `#207` ungrounded `AnswerState`, diff --git a/docs/design-system/COMPONENTS.md b/docs/design-system/COMPONENTS.md index 9e79fed409..ee117a0394 100644 --- a/docs/design-system/COMPONENTS.md +++ b/docs/design-system/COMPONENTS.md @@ -20,7 +20,7 @@ derived from source, `.design-sync/config.json`, previews, direct contract cover production imports. It intentionally does not claim dark, forced-colours, 320px, print, remote publication, or product adoption without separate evidence. -### 0.1 Registered visual components (54 — local contract; remote status unverified) +### 0.1 Registered visual components (55 — local contract; remote status unverified) Every visual export has one source map entry, a source-derived public `*Props` contract (except the two zero-prop roots), a reference preview, and a direct static publication test. The generated @@ -37,7 +37,7 @@ table under **Generated maturity snapshot** is the canonical list and product-im _Remaining from the original eight in this document:_ `DocumentFrame` is built locally (`src/components/ui/document-frame.tsx`, shell-only in `DocumentViewer`) but is not yet among -the 54 design-sync registered visual exports — registration and full controls remain follow-up. +the 55 design-sync registered visual exports — registration and full controls remain follow-up. `OverlayRoot`, `SegmentedControl`, and the PR 6–8 components are built and represented by the local publication contract. The generated snapshot records their current product-import counts; @@ -47,8 +47,9 @@ design-project publication or browser acceptance. _P1 reusable (specified in outline only):_ `Menu`/`Popover` · `KeyValue` · `AppliedFilters`/`FilterSheet` · `ResponsiveActionGroup` · `ScrollableStrip`/ `ScrollAffordance` · `SourceLink` · `Banner` · `CopyButton`/`CopyField` · -state family (`ErrorState`, `OfflineState`, `PermissionDeniedState`, `NotFoundState`, -`UnavailableState`). +state family (`OfflineState`, `PermissionDeniedState`, `NotFoundState`, +`UnavailableState`). `ErrorState` is built (`src/components/ui/error-state.tsx`) and +locally registered — it is not outline-only. `FilterBar` and `DataTable` are retired names, not future component contracts. Use a surface-owned filter pattern or the canonical `AccessibleTable`; do not revive either name. @@ -86,7 +87,7 @@ print primitives (`PrintHeader`, `PrintFooter`, `CitationFootnote`, `PrintOnly`, | Progress/StageList | all four resolved: `scaleX`, the theme `animate-shimmer` in place of a hardcoded `1.4s`, a step index clamped to ≥1, and an sr-only `role="status"` sibling in place of `aria-live` on the whole `
    ` | **done** | | EmptyState | static live-off default with explicit polite/assertive opt-in | **done** (PR 8) | | AccessibleTable | semantic caption, `MissingValue` cells, dense headers (clipped header keeps its full string as `title`) and the expander (now the registered `Button`, off the local ring-focus recipe) landed; content-role widths remain | PR 6/PR 12 remainder | -| ui-primitives.tsx | 698-line module mixing recipes/actions/feedback/clinical — split. Re-measured 2026-08-12: **157** production files import it (202 including mockups), against the 54 registered components' **31** with product imports; this module, not the registry, is what the product actually runs on. Per-primitive breakdown added 2026-08-21: `Button` **12** importers against 157, with **112** production files still holding a raw ` {open ? ( @@ -346,9 +345,8 @@ function TherapyPicker() {