Completed boot loading to ECG, to name written

Ralph/refs/ref-design-system.md

@@ -1,87 +1,163 @@
 # Reference: Visual Design System
 
-> Extracted from goal.md — Visual System section. This is the SINGLE SOURCE OF TRUTH for colors, typography, spacing, borders, and motion throughout the Clinical Record PMR.
+> The SINGLE SOURCE OF TRUTH for colors, typography, spacing, surfaces, and motion throughout the Clinical Record PMR. Aligned with the **Clinical Luxury** direction defined in CLAUDE.md.
+
+---
+
+## Design Philosophy
+
+This is a **premium portfolio** that uses the structure and metaphor of a GP clinical system — not a faithful NHS software clone. Real clinical systems (EMIS Web, SystmOne) are dense, border-heavy, and purely functional. We keep their *structure* (patient banner, sidebar navigation, record sections, tables, status indicators) but elevate the *execution* with refined typography, atmospheric depth, and considered whitespace.
+
+The goal is contrast: clinical precision married to luxury refinement. The "wow" comes from recognizing the clinical metaphor while being surprised by how good it looks.
 
 ---
 
 ## Color Palette
 
-This design is **light-mode only**. Clinical record systems operate in light mode — high ambient lighting in consulting rooms demands white backgrounds and dark text. A dark mode would break the metaphor.
+**Light-mode only.** The metaphor demands it — clinical systems operate under bright consulting room lights. No dark mode.
 
 **Backgrounds:**
-- Main content area: `#F5F7FA` (cool light gray — the content background of EMIS/SystmOne)
-- Card/panel surfaces: `#FFFFFF` (white)
-- Sidebar: `#1E293B` (dark blue-gray — EMIS-style dark navigation panel)
-- Patient banner: `#334155` (lighter blue-gray with white text)
-- Login screen background: `#1E293B` (same as sidebar — institutional dark blue-gray)
+- Main content area: `#F5F7FA` — cool light gray base. Add atmospheric depth: a very faint noise/grain texture overlay, or a subtle warm tint, so it feels like quality paper rather than a flat spreadsheet. The content surface should have *presence*.
+- Card/panel surfaces: `#FFFFFF` — clean white. Cards float above the content surface via layered shadows (see Surfaces section).
+- Sidebar: `#1E293B` — dark blue-gray. The gravitas anchor. This dark chrome is what makes it feel like "serious software."
+- Patient banner: `#334155` — lighter blue-gray with white text. Subtle drop shadow below to separate from content.
+- Login screen background: `#1E293B` — same as sidebar. Carries through to PMR entrance seamlessly.
 
 **Text:**
-- Primary text: `#111827` (gray-900 — near-black for maximum readability)
-- Secondary text: `#6B7280` (gray-500)
-- On dark surfaces: `#FFFFFF` (white) and `#94A3B8` (slate-400 for secondary)
+- Primary: `#111827` (gray-900) — near-black for maximum readability
+- Secondary: `#6B7280` (gray-500) — labels, metadata, supporting text
+- Muted: `#94A3B8` (slate-400) — timestamps, tertiary info
+- On dark surfaces: `#FFFFFF` (white primary), `#94A3B8` (slate-400 secondary)
 
 **Accent and status colors:**
-- NHS blue: `#005EB8` — primary interactive color. Used for buttons, active nav states, links, column headers. This is the actual NHS brand blue and will be instantly recognized.
-- Green: `#22C55E` — active/resolved/current states. "Active" status dots, resolved problems, current role indicators.
-- Amber: `#F59E0B` — alerts, in-progress items, notable achievements. The clinical alert banner uses this as its background.
-- Red: `#EF4444` — urgent/critical markers. Used sparingly — only for genuinely important items (e.g., a "priority" flag on the referral form).
-- Gray: `#6B7280` — inactive/historical items. Past roles that are no longer current, historical "medications."
+- **NHS Blue `#005EB8`** — THE accent color. Buttons, active nav states, links, interactive elements. This is the actual NHS brand blue — it will be instantly recognized and is the strongest signal of the clinical metaphor. Use it confidently but not everywhere.
+- Green `#22C55E` — active/resolved/current states. Status dots, current role indicators.
+- Amber `#F59E0B` — alerts, in-progress items. The clinical alert banner background.
+- Red `#EF4444` — urgent/critical. Used very sparingly — only genuinely important items.
+- Gray `#6B7280` — inactive/historical items.
 
 **Traffic light system (used throughout):**
-- Green circle: Active / Resolved / Current
-- Amber circle: In progress / Alert / Notable
-- Red circle: Urgent / Critical (rare)
-- Gray circle: Inactive / Historical
+- Green dot: Active / Resolved / Current
+- Amber dot: In progress / Alert / Notable
+- Red dot: Urgent / Critical (rare)
+- Gray dot: Inactive / Historical
+- **Always paired with text labels.** Color is never the sole signifier (WCAG compliance).
+
+---
 
 ## Typography
 
-Clinical systems use system fonts — Inter or Segoe UI for general text, monospace for coded entries and data values. No decorative fonts, no variable tracking. Functional typography optimized for scanning dense tables.
+Typography is the primary vehicle for the premium feel. The font choice must feel *designed* — intentional and distinctive — while still reading cleanly at small clinical-system sizes (11-14px).
 
-- **Patient banner name:** Inter 600, 20px (not huge — clinical systems don't emphasize the patient name with large type)
-- **Patient banner details:** Inter 400, 14px
-- **Sidebar navigation labels:** Inter 500, 14px, white
-- **Section headings (within main area):** Inter 600, 18px
-- **Consultation entry titles:** Inter 600, 16px
-- **Body text / descriptions:** Inter 400, 14px, line-height 1.6
-- **Table headers:** Inter 600, 13px, uppercase, letter-spacing 0.03em, gray-500
-- **Table data cells:** Inter 400, 14px
-- **Coded entries / data values:** Geist Mono 400, 13px
-- **Clinical codes (SNOMED-style):** Geist Mono 400, 12px, gray-400
-- **Timestamps:** Geist Mono 400, 12px
-- **Alert banner text:** Inter 500, 14px
+**Font selection:**
+- **UI / Body font**: Choose a distinctive geometric or humanist sans-serif with character. **Do not use** Inter, Roboto, Arial, or system-ui defaults — these read as generic/AI-generated. Candidates: **Satoshi**, **General Sans**, **Outfit**, **DM Sans**, or similar. The chosen font should have personality at 13px. Whichever is selected, configure it as the primary `font-family` across all UI elements.
+- **Monospace / Data font**: **Geist Mono** — for timestamps, coded entries, registration numbers, NHS numbers, tabular data values. This monospace texture is what sells the "clinical software" feel. Falls back to Fira Code.
+- **Terminal phase**: **Fira Code** — locked, do not change.
+
+**Type scale (tight, clinical):**
+- Patient banner name: [UI font] 600, 20px
+- Patient banner details: [UI font] 400, 14px
+- Sidebar navigation labels: [UI font] 500, 14px, white
+- Section headings (main area): [UI font] 600, 15-18px
+- Consultation entry titles: [UI font] 600, 15-16px
+- Body text / descriptions: [UI font] 400, 13-14px, line-height 1.6
+- Table headers: [UI font] 600, 12-13px, uppercase, letter-spacing 0.03-0.05em
+- Table data cells: [UI font] 400, 13-14px
+- Labels / metadata: [UI font] 500, 11-12px
+- Coded entries / data values: Geist Mono 400, 12-13px
+- Clinical codes (SNOMED-style): Geist Mono 400, 11-12px, gray-400
+- Timestamps: Geist Mono 400, 11-12px
+- Alert banner text: [UI font] 500, 14px
+
+**Hierarchy through weight, not size.** Use 400/500/600/700 weight variations within a narrow size range. Bold section headers, medium labels, regular body. This keeps the clinical density while creating clear scannable hierarchy.
+
+---
 
 ## Spacing and Layout
 
+More generous than real clinical software. The clinical metaphor provides structure; the extra breathing room provides luxury.
+
 - **Sidebar width:** 220px (fixed, desktop). Collapses to 56px (icon-only) on tablet.
 - **Patient banner height:** 80px (full), 48px (condensed/sticky)
-- **Main content max-width:** No max-width — clinical systems fill available space. Content flows within the area between sidebar and viewport edge.
-- **Main content padding:** 24px
-- **Card padding:** 16px (clinical systems are more compact than marketing sites)
-- **Border radius:** 4px for cards and inputs (clinical systems use minimal rounding — 4px, not 12px or 16px)
+- **Main content max-width:** None — fills available space between sidebar and viewport edge.
+- **Main content padding:** 24px (desktop), 16px (mobile)
+- **Card padding:** 16-24px — more generous than real clinical systems. Content should breathe inside cards.
+- **Border radius:** 4px default for cards, inputs, buttons (clinical precision). 12px exception for the login card only.
 - **Table row height:** 40px
 - **Section spacing:** 24px between content blocks
-- **Base unit:** 4px — tighter spacing than typical, reflecting clinical system density
+- **Base unit:** 4px grid — but use it with more generosity than a real clinical system would
 
-## Borders and Surfaces
+---
 
-Borders are the dominant visual structuring element. Clinical systems do not rely on shadows or negative space — they use explicit borders to delineate every element.
+## Surfaces & Depth
 
-- **All cards:** `1px solid #E5E7EB` (gray-200) border, `4px` border-radius, no shadow (or at most `0 1px 2px rgba(0,0,0,0.03)`)
-- **Table cells:** `1px solid #E5E7EB` borders (all sides)
-- **Sidebar border:** `1px solid #334155` (subtle right border in a slightly lighter shade)
-- **Patient banner border:** `1px solid #475569` bottom border
-- **Input fields:** `1px solid #D1D5DB` border, `4px` radius, `#FFFFFF` background, `8px 12px` padding
-- **Active/selected rows:** `#EFF6FF` background (very subtle blue tint) — this is how EMIS highlights the selected row
+This is where we diverge most from real clinical software. Real systems are flat and border-heavy. This project uses **shadows and layering** to create premium depth — while keeping borders where they're authentically clinical (tables, input fields).
+
+**Cards:**
+- Border: `1px solid #E5E7EB` (keep the clinical border — it's authentic)
+- Shadow: Multi-layered — `0 1px 2px rgba(0,0,0,0.04), 0 4px 12px rgba(0,0,0,0.03)`. Gentle float, not Material Design dramatic.
+- Border-radius: `4px`
+- Hover: Cards may lift very slightly — 1-2px translateY + shadow deepens to `0 2px 4px rgba(0,0,0,0.06), 0 8px 16px rgba(0,0,0,0.04)`. Restrained, not bouncy.
+- Card headers: Light gray `#F9FAFB` background with `1px solid #E5E7EB` bottom border. Uppercase title in [UI font] 600, 12-13px. This is the most "clinical" element — keep it precise.
+
+**Tables:**
+- Full `<table>` markup with styled headers — this is where clinical authenticity lives.
+- Table headers: `#F9FAFB` background, `1px solid #E5E7EB` borders.
+- Alternating rows: `#FFFFFF` / `#F9FAFB` — subtle but scannable.
+- Row hover: `#EFF6FF` background (blue tint).
+- Cell borders: `1px solid #E5E7EB` — keep full borders on tables. This is authentic.
+
+**Sidebar:**
+- Background: `#1E293B`
+- Right edge: `1px solid #334155` + optional very subtle glow/shadow where it meets the content area.
+- The sidebar should feel solid and authoritative against the lighter content.
+
+**Patient banner:**
+- Background: `#334155`
+- Bottom: Subtle drop shadow `0 2px 8px rgba(0,0,0,0.12)` to separate from content below.
+- Bottom border: `1px solid #475569`
+
+**Input fields:**
+- Border: `1px solid #D1D5DB`, `4px` radius, `#FFFFFF` background, `8px 12px` padding
+- Focus: NHS blue border + `box-shadow: 0 0 0 3px rgba(0,94,184,0.15)` — refined focus ring.
+
+---
 
 ## Motion
 
-Clinical systems are fast and functional. Animations are minimal and purposeful — no spring physics, no bouncy transitions. Everything is immediate or uses simple ease-out.
+Motion should feel **considered and premium** — never flashy, never gratuitous. Every animation has a purpose: to orient the user, to reward interaction, or to create a moment of polish.
 
-- **Navigation switches:** Instant content swap. No crossfade, no slide. When you click a sidebar item, the main content area replaces immediately — just like clicking a tab in EMIS.
-- **Consultation expand/collapse:** Height animation, 200ms, `ease-out`. No opacity fade — the content simply grows/shrinks.
-- **Alert banner entrance:** Slide down from top, 250ms, with a subtle spring overshoot (this is the one exception — alerts are meant to demand attention).
-- **Alert acknowledge:** The alert shrinks in height to zero (200ms) with a small green checkmark that flashes briefly.
-- **Hover states:** Background-color transitions, 100ms. No transforms, no lifts. Just color.
-- **Login typing:** Character-by-character reveal using `setInterval` (30ms per character for username, 20ms per dot for password).
-- **Patient banner scroll condensation:** Smooth height transition (200ms) from full (80px) to condensed (48px) as user scrolls past the first 100px of content.
-- **`prefers-reduced-motion`:** Typing animation completes instantly (full text appears), alert slides are replaced with fade-in, expand/collapse is instant.
+**PMR entrance sequence (login → PMR transition):**
+- Patient banner slides down: 200ms, ease-out
+- Sidebar slides from left: 250ms, ease-out, 50ms delay
+- Content fades in: 300ms, 100ms delay after sidebar
+- This staggered materialization is the single most impactful animation moment.
+
+**Navigation switches:** Instant content swap. No crossfade, no slide. This preserves the "software application" feel — clinical systems switch tabs instantly.
+
+**Expandable content:** Height-only animation, 200ms, `ease-out`. Content grows/shrinks — no opacity fade.
+
+**Clinical alert entrance:** Spring animation (Framer Motion `type: "spring"`, moderate damping). This is the one element that *demands attention* — the spring overshoot is earned here.
+
+**Alert acknowledge:** Warning icon cross-fades to green checkmark (200ms) → hold 200ms → alert height collapses (200ms ease-out).
+
+**Hover states:** Subtle and immediate. Background-color transitions at 100ms. Card lifts are 1-2px max with shadow deepening. Think: OS-level responsiveness, not playful bouncing.
+
+**Login typing:** Character-by-character reveal: 30ms/char for username, 20ms/dot for password. Cursor blink at 530ms.
+
+**Patient banner condensation:** Smooth height transition (200ms) from 80px → 48px as user scrolls past 100px. Buttery smooth, no jank.
+
+**`prefers-reduced-motion`:** All animations skip to final state instantly. Typing completes immediately. Alert appears without slide. Expand/collapse is instant. No exceptions.
+
+---
+
+## What Makes This Design Distinctive
+
+The memorability comes from **contrasts**:
+- Dark, serious sidebar next to warm, airy content
+- Small, precise monospace data in generous whitespace fields
+- NHS blue punching through an otherwise muted, restrained palette
+- Clinical structure (tables, status dots, coded entries) executed with luxury refinement (shadows, spacing, typography)
+- The boot → ECG → login theatrical sequence, then suddenly: a premium application
+
+If any component could be dropped into a generic SaaS dashboard without looking out of place, it needs more character.