` or `` with appropriate heading hierarchy. +- The breadcrumb uses `` with an `` of `` items. +- Detail sheets use `role="dialog"` with `aria-modal="true"` and `aria-labelledby` pointing to the sheet title. + +### Keyboard Navigation + +- **Tab:** Cycles through interactive elements within the active layer. +- **Enter/Space:** Activates buttons and links (pushes layers, opens sheets). +- **Escape:** Pops the current layer or closes the current detail sheet. At Level 0, Escape does nothing. +- **Arrow keys:** Navigate the section picker horizontally. + +### Focus Management + +- When a layer pushes, focus moves to the first heading or interactive element in the new layer. +- When a layer pops, focus returns to the element that triggered the push. +- Detail sheets trap focus within the sheet while open. Tab cycling wraps from last to first focusable element. +- On sheet dismiss, focus returns to the triggering element. + +### Screen Reader Support + +- Layer transitions are announced via an `aria-live="polite"` region: "Navigated to Experience section" / "Returned to Overview." +- Detail sheet open/close is announced: "Opened NHS Norfolk & Waveney ICB details" / "Closed details." +- Breadcrumb trail is read naturally as an ordered list. +- Statistics use `aria-label` for full context: `14,000`. + +### Motion Sensitivity + +When `prefers-reduced-motion: reduce` is active: +- Layer push/pop transitions change to immediate opacity crossfade (200ms). No translateX, no scale, no blur. +- Detail sheets appear/disappear via opacity fade (200ms). No slide. +- Copper thread lines appear immediately at full width (no draw animation). +- Content reveals are instant (no 600ms fade). +- All easing functions default to `linear` for the reduced durations. + +### Color Contrast + +All text combinations meet WCAG 2.1 AA standards: +- `#111111` on `#FFFFFF`: contrast ratio 18.9:1 (AAA) +- `#6E6E73` on `#FFFFFF`: contrast ratio 4.6:1 (AA) +- `#1A2B4A` on `#FFFFFF`: contrast ratio 12.5:1 (AAA) +- `#B87333` on `#FFFFFF`: contrast ratio 3.6:1 (AA for large text only; copper is only used on text >= 18px or 14px bold, or on decorative elements) +- `#111111` on `#F5F5F7`: contrast ratio 17.4:1 (AAA) + +--- + +## What Makes This Special + +The Depth Stack is the most **mature** design of all six. It communicates executive seniority through restraint -- luxury whitespace, deliberate pacing, copper accents on pure white. Where other designs demonstrate technical skill through animation complexity or information density, this design demonstrates it through *editorial confidence* and *structural thinking*. + +The z-axis navigation model mirrors how clinical data is structured: patient summary leads to medication history leads to individual prescription detail. It mirrors how Andy presents to executives: headline leads to evidence leads to methodology. Every transition says "there's substance beneath this surface." + +The Fraunces serif adds a warmth and personality that sans-serif-only designs cannot match. It's distinctive without being heavy, authoritative without being cold. The variable optical sizing means it performs beautifully from 14px metadata to 80px display headings, always looking intentionally designed for that specific size. + +The Copper Thread provides visual continuity without visual noise. It's the red thread of narrative (in copper) that ties the entire experience together -- from its birth in the ECG transition through every section divider, achievement callout, and interaction state. + +On mobile, this design has a structural advantage: while other portfolio sites become generic scroll-fests on small screens, the Depth Stack maps to native mobile navigation patterns. Users don't need to learn anything -- they already know how to tap deeper and swipe back. The portfolio feels like an app, not a web page. + +Someone managing a GBP220M budget should have a site that feels commensurate. The Depth Stack doesn't shout about its quality -- it demonstrates it through the precision of every typographic choice, the restraint of every whitespace decision, and the confidence to let content speak without visual crutches. + +**The design's thesis, in one sentence:** Depth is more impressive than breadth, and silence is more powerful than noise. diff --git a/designs/06-the-pipeline.md b/designs/06-the-pipeline.md new file mode 100644 index 0000000..1d47ca8 --- /dev/null +++ b/designs/06-the-pipeline.md @@ -0,0 +1,672 @@ +# Design 6: The Pipeline + +> A drag-to-explore data flow interface where the user IS the data, physically traveling through Andy's career as a glowing packet on a visible pipeline track. + +--- + +## Overview + +The Pipeline transforms the CV from a document into a spatial journey. After the ECG intro, a glowing pipeline track — born from the heartbeat trace itself — stretches across the viewport. The user drags a luminous data packet along this track. As the packet moves through each section, it triggers content reveals, animations, and transformations. The pipeline has branches, valves, and processing nodes. Each section of the CV is a processing stage. + +This is the most physically engaging of all six designs. Dragging activates proprioception — the bodily sense of effort and movement. It demands continuous intent, creating deeper engagement than passive scrolling. The data packet becomes the user's avatar, and its journey IS Andy's career narrative made tangible. + +The metaphor is literal: Andy builds data pipelines professionally. He takes raw prescribing data, processes it through SQL transformations and Python algorithms, and outputs actionable insights. On this site, the user IS the data. They don't read about data processing — they experience being processed. + +### Why This Design + +No portfolio site uses drag-along-a-track as its primary navigation. The mechanic is immediately novel — the moment a visitor realizes they're dragging a glowing orb along a pipeline, they're in uncharted territory. Novelty drives sharing. The "Run Algorithm" interaction at the Projects section (where the packet duplicates to process all paths simultaneously) is the kind of moment that gets screen-recorded and posted to Twitter/X. This is the design built for virality. + +--- + +## ECG Transition + +**Starting frame:** Andy's name, neon green (#00FF41), on pure black. Static. + +### Sequence (2.4 seconds total) + +1. **Lift** (400ms): Andy's name text gently floats upward ~60px from its current position. Simultaneously, it transitions from neon green canvas-rendered letterforms to DOM-rendered text in Plus Jakarta Sans 700, white (#F0F0F0) with a soft text-shadow glow (0 0 20px rgba(0, 255, 65, 0.3)). The glow fades over the next second — a ghost of the green, dissipating. This is the text handoff: the name is now "real" typography while the canvas layer remains active below it. + +2. **Trace reveal** (300ms): With the name lifted, the original horizontal trace line that the ECG drew — the baseline the heartbeat traveled along, the path the name was formed on — is now visible below the name. It's still neon green (#00FF41), still on black. A thin, glowing horizontal line spanning roughly 60% of the viewport width, centered. This line is the seed of the pipeline. + +3. **Straighten and extend** (800ms): Any remaining curvature or heartbeat waveform artifacts in the trace line smooth out. The line's path control points interpolate toward a perfectly horizontal target. It flattens with a satisfying ease — `cubic-bezier(0.16, 1, 0.3, 1)`. Simultaneously, the line begins extending in both directions, drawing itself outward from center toward the viewport edges. As it extends, its color shifts from neon green (#00FF41) to a teal-cyan gradient (#00897B at left → #22D1EE at right). The line develops a soft glow: a 4px gaussian blur at 50% opacity behind the main 2px stroke, creating a neon-tube effect. + +4. **Curve and route** (600ms): The line, now spanning the full viewport width, begins to bend. The right end curves downward, forming the first gentle arc of the pipeline's S-curve track. The left end develops a small rounded terminal (a circle, 12px diameter) — the starting node. The background transitions from pure black to a dark gradient (#0D1117 at top, #1A1A2E at bottom), giving the impression of depth without losing the dark aesthetic. Faint stars (actually tiny dot-grid points at 2% opacity) appear across the background. + +5. **Packet birth** (300ms): A bright orb materializes at the left terminal node — the data packet. It appears with a scale-from-zero spring animation (stiffness: 300, damping: 15). It pulses twice with a teal-white glow (expanding from 8px to 14px radius and back), echoing the heartbeat that started the entire sequence. A "drag to explore" label fades in 20px to the right of the packet, in IBM Plex Sans 400, 14px, slate (#94a3b8), with a subtle horizontal arrow animation (translating 5px right and back on a 2s loop). The pipeline is live. The user can begin. + +### Why This Transition Works + +The ECG heartbeat line IS the pipeline. Same visual element, new purpose. The user watches a biological signal (heartbeat trace) metamorphose into a technical structure (data pipeline) in real-time. This is the visual equivalent of Andy's career narrative — clinical pharmacist becoming data engineer. The straightening moment is the pivot: raw biological waveform becoming clean, purposeful infrastructure. The packet's double-pulse at the end is the heartbeat's final echo — a callback that ties the intro and the main experience into one continuous story. + +--- + +## Visual System + +### Color Palette + +The Pipeline maintains a dark theme throughout — no transition to light. The dark background serves both the aesthetic (pipeline glow effects need contrast) and the metaphor (data flowing through infrastructure, operations centers, server rooms). + +| Element | Color | Hex | Usage | +|---------|-------|-----|-------| +| Background (top) | Deep charcoal | #0D1117 | Primary background | +| Background (bottom) | Dark navy | #1A1A2E | Gradient terminus | +| Content surface | Elevated dark | #161B22 | Card backgrounds, content areas | +| Content surface hover | Lighter dark | #1C2128 | Hover states | +| Pipeline stroke | Teal | #00897B | Main pipeline track | +| Pipeline glow | Cyan | #22D1EE | Glow effect behind pipeline | +| Packet core | Bright white | #FFFFFF | Data packet center | +| Packet glow | Teal-white | #A0F0E0 | Data packet aura | +| Text primary | Off-white | #E6EDF3 | Headings, primary text | +| Text secondary | Slate | #8B949E | Secondary text, labels | +| Text tertiary | Dim slate | #6E7681 | Timestamps, metadata | +| Accent warm | Coral | #FF6B6B | Alert states, key metrics | +| Accent bright | Electric cyan | #00D4AA | Active states, highlights | +| Node inactive | Dim teal | #1A3A3A | Pipeline nodes before packet arrives | +| Node active | Bright teal | #00897B | Pipeline nodes after packet passes | + +### Typography + +- **Space Grotesk 500, 700** — Headings and section labels. 700 for primary headings (28-36px), 500 for subheadings and node labels (18-22px). White (#E6EDF3) or teal (#00897B) depending on hierarchy. + +- **IBM Plex Sans 400, 450** — Body text, role descriptions, bullet points. 16px/1.7 for body, 14px/1.6 for secondary. Off-white (#E6EDF3) for primary, slate (#8B949E) for secondary. Weight 450 for body text to maintain readability on dark backgrounds. + +- **IBM Plex Mono 400** — Metrics, numbers, data labels, code references. 14-18px. Electric cyan (#00D4AA) for active metrics, slate (#8B949E) for labels. All metric numbers use this face for visual consistency and the "data" connotation. + +### Pipeline Visual Language + +The pipeline is the site's skeleton — visible at all times, providing spatial orientation. + +- **Track stroke**: 2px solid teal (#00897B) with a 6px gaussian blur glow (#22D1EE at 30% opacity) behind it. The track is always visible, even before the packet reaches a section. +- **Track ahead** (sections not yet reached): Dimmed to 20% opacity with no glow. Visible enough to show the path, dim enough to create anticipation. +- **Track behind** (sections already passed): Full opacity with residual glow that slowly fades (10s decay). The path you've traveled stays lit. +- **Flow particles**: Tiny dots (2px) travel along the pipeline track in the packet's direction of movement, spaced ~40px apart, moving at a constant slow speed. These create the impression of continuous data flow even when the packet is stationary. Speed increases proportionally when the packet is being dragged. +- **Processing nodes**: Circles (16px diameter) at section entry points. Inactive: dim teal outline (#1A3A3A). Active (packet has arrived): solid teal fill (#00897B) with a radial pulse animation (one pulse, 400ms). Completed (packet has passed): solid teal at 60% opacity, no pulse. +- **Branch points**: Where the pipeline splits (Projects section), a diamond shape (12px, rotated 45deg) marks the fork. The diamond pulses when the packet reaches it. + +### Ambient Particle Layer + +Behind the SVG pipeline and all content, a lightweight canvas particle system provides atmospheric depth: + +- **Particle count**: 150-300 (based on viewport size and device performance) +- **Particle size**: 1-2px circles, teal at 5-15% opacity +- **Default behavior**: Slow brownian drift, random direction, ~0.2px/frame velocity +- **Packet proximity reaction**: Particles within 120px of the data packet accelerate in the pipeline's direction of flow at that point. They stream alongside the packet like current in a river. This creates a "wake" effect behind the moving packet. +- **Section transitions**: When the packet enters a new section, nearby particles briefly brighten (5% → 20% → 5% over 600ms) and swirl inward toward the packet, as if being "processed." +- **Performance**: Canvas renders at 30fps (not 60) to save resources. Particles are simple circles with no complex rendering. The canvas is behind all content (`z-index: 0`, `pointer-events: none`). + +### Texture + +- **Dot grid**: 2% opacity, 32px spacing, covering the entire viewport. Barely visible but provides subconscious structure to the dark space. Grid dots near the pipeline track are slightly brighter (4% opacity). +- **Vignette**: A subtle radial gradient darkens the viewport corners (black at 15% opacity), focusing attention on the center where the pipeline and content live. +- **Noise texture**: An extremely subtle (1% opacity) noise overlay on the background gradient prevents color banding on displays with limited color depth. Applied via CSS `background-image` with a tiny tiling SVG. + +--- + +## Section-by-Section Design + +### Hero / Entry Point + +**Pipeline position:** The far-left terminal node. This is where the journey begins. + +**Layout:** +- Andy's name (Space Grotesk 700, 36px, white) sits above the pipeline starting node, vertically centered in the viewport. +- Title: "Population Health & Data Analysis | NHS" (Space Grotesk 500, 18px, slate #8B949E) below the name. +- The pipeline track extends to the right from the starting node, curving gently downward. +- The data packet sits at the starting node, pulsing softly (scale oscillation 1.0 → 1.1 → 1.0, 3s period). +- "Drag to explore" label with animated arrow, positioned right of the packet. +- Below the pipeline, a brief profile summary in IBM Plex Sans 450, 16px, off-white. + +**Interaction:** +- The user clicks/touches the data packet and begins dragging it along the pipeline track. +- As the packet moves right from the starting node, the hero content fades (opacity 1 → 0 over the first 15% of the pipeline's total length). +- The pipeline track ahead brightens from 20% to 100% opacity as the packet approaches. +- If the user releases the packet, it coasts forward on momentum (spring physics), then decelerates and stops. It can also coast backward if released while dragging left. + +### Skills — The Processing Matrix + +**Pipeline position:** First major section, 15-35% along the pipeline's total length. + +**Pipeline behavior:** The pipeline enters a rectangular area (the "processing matrix"). Inside, the single track splits into a grid-like arrangement — horizontal parallel tracks stacked vertically, connected by short vertical segments. Each horizontal track passes through 2-3 skill nodes. The packet follows the path through this matrix, lighting up skills as it passes. + +**Layout:** +The processing matrix is a contained visual area (roughly 80% viewport width, centered). Skill nodes are arranged in a grid: + +``` +ROW 1 (Technical): [Python] ——— [SQL] ——— [Power BI] ——— [JS/TS] + | | +ROW 2 (Data): [Algorithm Design] — [Data Pipelines] — [Dashboard Dev] + | | +ROW 3 (Healthcare): [Medicines Opt.] — [Population Health] — [NICE Implementation] + | | +ROW 4 (Leadership): [Budget Mgmt] ——— [Stakeholder Eng.] —— [Team Dev] +``` + +**Node design:** +- Each skill is a node on the pipeline: a rounded rectangle (120px x 48px) with a dim teal border (#1A3A3A) and dark fill (#161B22). +- Skill name inside in IBM Plex Sans 450, 13px, slate (#8B949E). +- Below the name, a thin proficiency bar (60px wide, 3px tall, empty). + +**Interaction — Packet traversal:** +- As the packet passes through a skill node, the node activates in sequence: + 1. Border brightens to full teal (#00897B) (100ms) + 2. Fill lightens to elevated dark (#1C2128) (100ms) + 3. Skill name text brightens to white (#E6EDF3) (100ms) + 4. Proficiency bar fills left-to-right with a teal-to-cyan gradient (200ms) + 5. A brief particle absorption effect: 10-15 ambient particles rush inward toward the node and disappear, as if the packet is "absorbing" the skill (300ms) + 6. The packet itself briefly brightens and grows (radius 8px → 12px → 8px) — it's gaining capability + +- Skills are ordered by acquisition timeline: pharmacy domain skills first (bottom rows), then data skills, then technical skills. The user experiences Andy's learning journey chronologically — pharmacist → analyst → developer. + +- Once activated, skill nodes remain lit. If the user drags backward, nodes dim back to inactive state. + +**Ambient detail:** +- Faint data-flow particles travel along the matrix tracks at constant slow speed, even before the packet arrives. This signals that the matrix is "alive" and waiting. +- A section label "PROCESSING // SKILLS" appears at the top of the matrix area in IBM Plex Mono 400, 12px, dim slate (#6E7681), uppercase, tracking 0.15em. + +### Experience — The Branching Pipeline + +**Pipeline position:** 35-70% along the pipeline's total length. The longest section. + +**Pipeline behavior:** The pipeline exits the skills matrix and enters the experience section. Here, it branches: the main track splits into separate parallel tracks, one per role. Each branch contains a processing node (the role). Branches converge back to the main track after each role, creating a pattern of split → process → merge → split → process → merge. + +The branching order is chronological (earliest role first, most recent last), so the user processes Andy's career in order. + +**Branch layout (desktop):** + +``` +Main track ──┬── [Branch: Tesco Pharmacy Manager 2017-2022] ──┬── Main track + │ │ + └──────────────────────────────────────────────────┘ + │ + ┌──────────────────────┘ + │ +Main track ──┬── [Branch: HCD & Interface Pharmacist 2022-24] ─┬── Main track + │ │ + └───────────────────────────────────────────────────┘ + │ + ┌──────────────────────┘ + │ +Main track ──┬── [Branch: Deputy Head 2024-Present] ───────────┬── Main track + │ │ + └───────────────────────────────────────────────────┘ + │ + ┌──────────────────────┘ + │ +Main track ──┬── [Branch: Interim Head May-Nov 2025] ──────────┬── Main track +``` + +**Role card design:** +Each branch contains a role card that builds itself as the packet passes through: + +- **Container**: Rounded rectangle, dark surface (#161B22), subtle border (#1C2128), generous padding (24px 32px). +- **Left accent**: A 3px vertical line on the left side, teal (#00897B), extends from top to bottom of the card. Animates: draws top-to-bottom as the packet arrives. +- **Role title**: Space Grotesk 700, 22px, white (#E6EDF3). Types itself character-by-character as the packet enters the branch. +- **Company + date**: IBM Plex Sans 400, 14px, slate (#8B949E). Slides in from left after title. +- **Context line**: IBM Plex Sans 450, 15px, off-white (#E6EDF3). Fades in. +- **Bullet points**: IBM Plex Sans 400, 15px, off-white. Each fades in from below with 100ms stagger. +- **Key metrics**: Displayed in IBM Plex Mono 400, 18px, electric cyan (#00D4AA), with a subtle glow. Each metric has a small throughput indicator animation — a mini progress bar that fills as the packet passes the metric. + +**Throughput indicators:** +At each branch point, small counters display the role's key metrics: +- Tesco: `~£1M revenue` | `300 branches` | `60→6 hrs/month` +- HCD: `70% form reduction` | `200 hrs saved` | `7-8 hrs/week` +- Deputy Head: `£220M budget` | `£2.6M savings` | `14,000 patients` +- Interim Head: `£14.6M programme` | `3 days vs months` | `50% reduction` + +These counters are IBM Plex Mono 400, 14px, positioned along the branch track. They count up from zero as the packet passes, with the count rate proportional to drag velocity. + +**Interaction:** +- The packet enters a branch and the role card begins building. +- Dragging further through the branch reveals more content (bullets, metrics). +- At the merge point (where the branch rejoins the main track), the card is fully built and the packet continues to the next branch. +- If the user drags backward, the card deconstructs in reverse order. +- The ambient particles in the pipeline increase in density and speed within branches, suggesting "heavy processing." They slow back to normal on the main track between branches. + +### Education — The Research Lab + +**Pipeline position:** 70-82% along the pipeline's total length. + +**Pipeline behavior:** The pipeline enters a visually distinct zone. The background lightens slightly within this area (from #0D1117 to #111822), and a faint rectangular border (1px, #1C2128) delineates the "lab" space. The pipeline coils through education milestones — a tighter, more compact S-curve than the wide branching of the Experience section. + +**Section label:** "RESEARCH_LAB // EDUCATION" in IBM Plex Mono 400, 12px, dim slate, uppercase. + +**Milestone layout:** + +The pipeline passes through 4 milestone nodes, each triggering a content reveal: + +1. **A-Levels (2009-2011)** + - Node: Circle, 20px, with a graduation cap icon (Lucide `GraduationCap`, 12px) inside. + - Content card (appears when packet arrives): Highworth Grammar School. Mathematics A*, Chemistry B, Politics C. Compact card, single line of detail. + - Pipeline behavior: Straight horizontal track through this node. + +2. **MPharm (2011-2015)** + - Node: Circle, 24px (slightly larger — this is a major milestone), with a flask icon (Lucide `FlaskConical`, 14px). + - Content card: University of East Anglia. Master of Pharmacy, 2:1 Honours. More detailed card with 2-3 lines. + - **Branch**: At this node, the pipeline briefly splits into a short side branch that curves upward and terminates at a small terminal node labeled "Research Project." This branch card reads: "Drug delivery and cocrystals: 75.1% (Distinction)." The side branch represents the experimental methodology — a controlled divergence from the main path that produces a result, then merges back. The packet can optionally be dragged down the research branch (or it can auto-traverse with a small duplicate packet if the user continues on the main track). + +3. **GPhC Registration (2016)** + - Node: Circle, 20px, with a shield icon (Lucide `ShieldCheck`, 12px). + - Content card: General Pharmaceutical Council. Registered Pharmacist. Brief card — this is a credentialing milestone. + - Pipeline behavior: The track brightens momentarily as the packet passes this node (the "authorization" node), as if the pipeline has been certified. + +4. **Mary Seacole Programme (2018)** + - Node: Circle, 20px, with a star icon (Lucide `Star`, 12px). + - Content card: NHS Leadership Academy. 78%. Change management, healthcare leadership, system-level thinking. + - Pipeline behavior: Standard pass-through. After this node, the pipeline curves toward the Projects section. + +**Ambient detail:** +- The research lab zone has a slightly different particle behavior: particles drift more slowly and in more organized patterns (subtle grid-aligned movement rather than brownian), suggesting the structured environment of academic research. +- A faint molecule-like structure (3 interconnected circles, purely decorative, very low opacity) floats in the background of this zone — a nod to Andy's cocrystal research without being heavy-handed. + +### Projects — The Algorithm (Signature Interaction) + +**Pipeline position:** 82-95% along the pipeline's total length. The most interactive section. + +**Pipeline behavior:** The main track reaches a diamond-shaped branch point (the "decision node"). The pipeline splits into multiple parallel tracks — one per project. Each track leads to a project node, then terminates in a small endpoint. The main track continues straight through to the Contact section, but the user must choose which project branch to explore. + +**Branch layout (desktop):** + +``` + ┌── [Switching Algorithm] ── (endpoint) + │ +Main track ── ◆ ── ┼── [Blueteq Automation] ── (endpoint) + │ │ + │ ├── [Sankey Chart Tool] ── (endpoint) + │ │ + │ └── [CD Monitoring] ──── (endpoint) + │ + └──────────────────────────── Main track continues → Contact +``` + +**Manual exploration (default):** +The user drags the packet to the branch point. The diamond node activates and all four project branches illuminate at 40% opacity. The user can drag the packet down any branch to explore that project. At the project node, a project card builds itself (similar to experience cards): + +**Project card design:** +- **Header**: Project name (Space Grotesk 700, 20px, white) + technology tags (IBM Plex Mono 400, 12px, electric cyan, pill-shaped backgrounds). +- **Description**: IBM Plex Sans 450, 15px, off-white. 2-3 sentences. +- **Visualization**: Each project card contains a mini-visualization that animates as the packet arrives: + + - **Switching Algorithm**: A field of small dots (100-150) representing patients. As the card activates, dots stream through a funnel shape (two converging lines) and emerge organized into color-coded groups on the other side. Counter: `14,000 patients → £2.6M savings`. Duration: 2s auto-animation triggered by packet arrival. + + - **Blueteq Automation**: A stack of 10 small rectangle icons (representing forms). 7 of them slide off-screen with a smooth exit animation, leaving 3. Counter: `70% reduction | 200 hrs immediate savings`. Simple and devastating. + + - **Sankey Chart Tool**: A mini Sankey diagram (4 left nodes → 3 middle nodes → 3 right nodes) with colored flow paths that animate with flowing particles. The paths draw themselves over 1.5s. This is a live visualization of what Andy built. + + - **CD Monitoring**: A mini line chart that draws itself left-to-right. A horizontal threshold line is pre-drawn. When the data line crosses the threshold, the line and the area above it shift to coral (#FF6B6B) and pulse once. Counter: `Population-scale safety analysis`. + +- **Impact metric**: A large number in IBM Plex Mono 700, 28px, electric cyan, with glow. Positioned prominently in the card. + +After exploring a project, the user drags the packet back to the branch point and can choose another branch, or continue to Contact. + +**"Run Algorithm" interaction (signature moment):** + +At the branch point, a button appears: `[ ▶ RUN ALGORITHM ]` — styled as a pipeline control element (rounded rectangle, teal border, IBM Plex Mono 500, 14px, uppercase). The button pulses gently with a teal glow. + +When clicked: + +1. The data packet at the branch point duplicates — it splits into 4 identical orbs (300ms spring animation outward). +2. Each duplicate travels down a different project branch simultaneously. All 4 project cards build in parallel. +3. The ambient particles surge — increased density and speed along all 4 branches, creating visible "data flow" in every direction. +4. All 4 mini-visualizations animate simultaneously. +5. A label appears at the branch point: `PARALLEL PROCESSING // 4 THREADS` in IBM Plex Mono 400, 12px, electric cyan. +6. After all 4 packets reach their endpoints (2-3 seconds), they reverse — traveling back along the branches to the decision node, where they merge back into a single packet. The merge is accompanied by a bright flash and a brief particle burst. +7. The main track forward to Contact now illuminates fully. All project cards remain visible and explored. + +**Why this works:** This directly demonstrates what Andy's algorithms do — automated parallel processing versus manual single-track work. The user sees the difference viscerally. Processing one project at a time is slow and requires backtracking. Running the algorithm processes everything simultaneously. It's a live demo of the value proposition on Andy's CV. + +### Contact — The Output Terminal + +**Pipeline position:** 95-100% along the pipeline's total length. The endpoint. + +**Pipeline behavior:** The pipeline track approaches a final processing node — larger than the others (24px diameter), with a distinctive glow. The track terminates here with a rounded endpoint. This is the "output terminal." + +**Layout:** +- Section label: `OUTPUT_TERMINAL // CONTACT` in IBM Plex Mono 400, 12px, dim slate. +- A summary card appears above the contact form, pulling together key numbers: + +``` +PROCESSING COMPLETE + +£14.6M efficiency programme identified +14,000 patients flagged by algorithm +£2.6M annual savings on target +1.2M population served +``` + +Each number is IBM Plex Mono 700, 24px, electric cyan, with glow. They count up sequentially (staggered by 200ms) as the packet reaches the terminal node. + +- **Contact form**: Below the summary. Clean design on a dark surface (#161B22): + - Fields: Name, Email, Message. Each has a bottom border (1px, #1C2128) that brightens to teal on focus. Labels float above in slate. + - Submit button: Rounded rectangle, solid teal fill, white text, IBM Plex Sans 500, 15px. Hover: lighter teal + glow. + - Contact details alongside: email (andy@charlwood.xyz), phone, location (Norwich, UK). Each with a Lucide icon (Mail, Phone, MapPin) in teal. + +- **Form submission animation**: On successful submit, the data packet (which has settled in the terminal node) launches upward — it accelerates off the top of the viewport, leaving a trail of particles behind it. A "Message sent" confirmation appears at the terminal node. The packet slowly regenerates (fading back in at the terminal) after 3 seconds. The visual metaphor: data entered → processed → transmitted. + +**Pipeline completion state:** +Once the packet reaches the terminal, the entire pipeline track behind it achieves full brightness — every node is active, every branch is lit, flow particles are moving along the full length. The complete pipeline is visible as a glowing map of everything the user explored. This provides a satisfying sense of completion and a visual summary of the journey. + +--- + +## Interactions and Micro-interactions + +### Packet Drag Mechanics + +The data packet is the primary interactive element. Its behavior must feel physically satisfying: + +- **Grab**: Clicking/touching the packet scales it up (1.0 → 1.2) with a spring animation (stiffness: 400, damping: 20) and increases its glow radius. Cursor changes to `grabbing`. +- **Drag**: The packet follows the user's pointer along the pipeline track. It cannot leave the track — movement is constrained to the SVG path. The position is calculated as the nearest point on the path to the cursor position. +- **Velocity**: Drag velocity is tracked. Faster dragging increases ambient particle flow speed and throughput counter count-up rate. This creates a satisfying "the faster I go, the more data processes" feedback loop. +- **Release with momentum**: When released, the packet coasts in the direction of the last drag velocity. Deceleration follows spring physics (`dragMomentum: true`, damping: 0.8). The packet can coast through multiple nodes if released with enough velocity. This creates a playful "launch" interaction. +- **Release without momentum**: If released while stationary (no velocity), the packet stays in place. No auto-advancing. +- **Backward dragging**: Fully supported. Dragging backward reverses all animations — cards deconstruct, nodes deactivate, metrics count down. The experience is fully bidirectional. +- **Snap points**: At each processing node, the packet has a slight magnetic snap (subtle resistance when dragging past, requiring a small threshold of force to break free). This encourages the user to pause at each section. Snap force: 5px snap radius, breakaway at 15px drag distance. + +### Pipeline Glow Dynamics + +The pipeline's glow reacts to the packet's position and state: + +- **Proximity glow**: The pipeline track within 200px of the packet has enhanced glow (30% → 60% opacity). The glow falls off with distance using an ease-out curve. +- **Drag glow**: While the packet is being actively dragged, the glow intensifies further (to 80%) and the glow color shifts from teal toward brighter cyan. +- **Pulse on node activation**: When the packet crosses a processing node, the pipeline segment behind the node pulses (brightness spikes to 100%, then settles to the completed-segment baseline of 50%). +- **Idle glow**: If the packet sits idle for >5 seconds, it emits a gentle pulse (breathing glow, 3s period) to remind the user it's there and draggable. + +### Content Card Reveal Choreography + +All content cards (skills, experience, education, projects) follow a consistent build choreography: + +1. **Card surface appears** (100ms): Dark surface fades in from 0 → 100% opacity. +2. **Left accent draws** (200ms): The 3px teal left border draws top-to-bottom. +3. **Title types** (variable, 30ms per character): Characters appear left-to-right. +4. **Subtitle slides** (200ms): Company/date slides in from 20px left. +5. **Body fades** (200ms per element, 100ms stagger): Each line fades in from 10px below. +6. **Metrics count** (variable): Numbers count up at 30ms per digit. +7. **Visualization animates** (if applicable, 1-2s): Mini-viz plays after text is settled. + +Easing for all: `cubic-bezier(0.16, 1, 0.3, 1)`. + +Reverse: On backward drag, steps play in reverse order at 1.5x speed (deconstruction feels faster than construction, which is psychologically satisfying). + +### Ambient Particle Behaviors + +The particle system has contextual behaviors per section: + +| Section | Particle Behavior | Emotional Register | +|---------|-------------------|-------------------| +| Hero | Slow drift, random direction | Calm, waiting | +| Skills | Stream toward activated skill nodes | Learning, acquisition | +| Experience | Dense, fast along branches | Heavy processing | +| Education | Organized grid-aligned drift | Structured, academic | +| Projects | Surge along all active branches | High throughput | +| Contact | Converge toward terminal node | Resolution, completion | + +--- + +## Navigation + +### Pipeline as Navigation + +The pipeline itself IS the navigation. The user's position on the pipeline determines what content is visible. However, auxiliary navigation is needed for: + +1. **Direct section access**: Five small node icons arranged vertically on the right edge of the viewport. Each corresponds to a section (Skills, Experience, Education, Projects, Contact). Clicking a node animates the packet along the pipeline to that section's entry point (the packet travels the pipeline visually — it doesn't teleport). The travel animation takes 800ms regardless of distance. + +2. **Mini-map**: At the bottom of the viewport, a thin horizontal representation of the entire pipeline (height 4px, width 200px). The packet's current position is shown as a bright dot on this minimap. Section boundaries are marked with tiny notches. The minimap provides spatial orientation — "I'm halfway through the pipeline." Clicking a position on the minimap moves the packet there. + +3. **Pipeline overview** (optional): Double-clicking/double-tapping anywhere off the pipeline triggers a "zoom out" — the viewport smoothly scales down to show the entire pipeline at once (scale 0.3-0.4x), with all sections visible as labeled nodes. The user can click any section to zoom back in at that position. This provides a bird's-eye view of the journey. + +### Keyboard Navigation + +- **Arrow Right / Arrow Down**: Advance packet to next processing node (with travel animation). +- **Arrow Left / Arrow Up**: Move packet to previous processing node. +- **Tab**: Focus moves between interactive elements (project cards, contact form fields) in DOM order. +- **Enter**: At a branch point, Enter activates the "Run Algorithm" button. +- **Number keys 1-5**: Jump to sections (1=Skills, 2=Experience, 3=Education, 4=Projects, 5=Contact). +- **Home**: Return packet to start. +- **End**: Advance packet to Contact terminal. + +### Scroll Fallback + +A "scroll mode" toggle is available in the header (a small icon: pipeline icon → scroll icon). When activated: + +- The pipeline track becomes a decorative sidebar element (fixed on the left, thin) +- Content converts to traditional vertical scroll layout +- The packet still travels down the sidebar pipeline synchronized to scroll position +- All content is visible via standard scrolling +- This mode is automatically activated for keyboard-only users (detected via `keydown` without prior `pointerdown`) + +--- + +## Responsive Strategy + +### Desktop (>1024px) + +Full horizontal pipeline experience. The pipeline track winds across the full viewport width. Content cards appear beside the pipeline track (alternating left and right). The skills matrix is a wide grid. Experience branches spread horizontally. Drag is horizontal (left-to-right). Ambient particles at full density (300). Mini-map and side navigation are visible. + +Pipeline orientation: Horizontal S-curve spanning the viewport. + +### Tablet (768px - 1024px) + +Hybrid layout. The pipeline rotates to a diagonal — still primarily horizontal but with more vertical S-curves to fit the narrower viewport. Content cards appear below the pipeline track rather than beside it. Skills matrix reduces to 2 columns. Experience branches are shorter. Drag direction follows the pipeline (mixed horizontal/vertical). Ambient particles reduced to 200. Mini-map visible, side navigation collapsed to a hamburger. + +### Mobile (<768px) + +The pipeline rotates fully vertical. The track runs top-to-bottom, fitting naturally with the device's primary scroll direction. The drag gesture is vertical (up-to-down). + +Key mobile adaptations: + +- **Drag direction**: Vertical drag replaces horizontal. The pipeline S-curves become horizontal zigzags (left-to-right then right-to-left, repeating downward). +- **Content cards**: Full-width, appearing below each processing node. Single-column layout. +- **Skills matrix**: Single-column vertical list. Nodes activate as the packet descends through them. +- **Experience branches**: Simplified — instead of visual branching, the track passes through role nodes sequentially. Branch visualizations are implied through a slightly wider track at each role. +- **Projects**: The parallel branch split is replaced by a sequential layout with the "Run Algorithm" button still available (packet duplicates downward into parallel vertical tracks, then merges). +- **Ambient particles**: Reduced to 100. No particle proximity reactions (too CPU-intensive on mobile with touch tracking). +- **Packet size**: Slightly larger (12px radius vs 8px desktop) for easier touch targeting. Touch target area is 48x48px minimum. +- **Scroll fallback**: Active by default on very small screens (<480px). Pipeline is decorative, content scrolls normally. + +### Touch Interaction + +- **Grab**: Long-press (200ms) or single tap on the packet activates drag mode. The packet scales up and vibrates once (haptic feedback on supported devices). +- **Drag**: Touch move drags the packet along the pipeline. Drag is constrained to the track. +- **Release**: Lift finger. Momentum and coast physics apply. +- **Tap node**: Tapping a processing node on the pipeline (not the packet) animates the packet to that node. This provides an alternative to dragging on small screens. + +--- + +## Technical Implementation + +### Pipeline Track (SVG Path System) + +The pipeline is a single SVG `` element spanning the full layout dimensions: + +``` +Architecture: +- Pipeline track: SVG elements (one per segment/branch) +- Processing nodes: SVG elements at segment junctions +- Branch points: SVG (diamond shape) elements +- Flow particles: Small SVG elements animated along paths via getPointAtLength() +- Glow effect: Duplicate elements with SVG (feGaussianBlur) +- All pipeline elements have pointer-events: none (except nodes for click navigation) +``` + +Path coordinates are computed based on viewport dimensions and section positions. On resize, paths recompute (debounced, 200ms). The pipeline is responsive — it redraws its curves to fit the new viewport. + +### Packet Position System + +``` +Core: +- useMotionValue('packetProgress') — a 0-1 value representing position along total pipeline length +- Packet screen position: pathElement.getPointAtLength(progress * totalLength) +- Framer Motion drag event maps pointer movement to progress delta +- Constraints: progress clamped to [0, 1], packet cannot leave the pipeline + +Drag physics: +- dragMomentum: true +- dragElastic: 0.05 (very slight elasticity at endpoints) +- Custom velocity tracking: store last 5 position samples (16ms apart), compute average velocity +- On release: apply velocity as spring animation (stiffness: 80, damping: 25) +- Snap points: implemented as modulated spring stiffness at node positions + +Section mapping: +- Each section registers a progress range: { start: 0.15, end: 0.35 } +- Section's internal animation progress = (packetProgress - section.start) / (section.end - section.start) +- Clamped to [0, 1] — 0 = section hasn't started, 1 = section fully revealed +``` + +### Content Reveal System + +``` +Architecture: +- Each section component receives its animation progress (0-1) as a prop +- Internal elements map sub-ranges of this progress to their individual animations +- Example: Experience card bullets occupy progress 0.5-1.0 of the section + - Bullet 1: 0.5-0.6, Bullet 2: 0.6-0.7, Bullet 3: 0.7-0.8, etc. +- Framer Motion useTransform for all progress-to-style mappings +- All animated properties are transform/opacity only (GPU composited) + +Card assembly: +- Each card is a React component with sub-elements +- useTransform maps section progress to sub-element animations +- Sub-elements animate in sequence (see choreography above) +- Reverse animations are computed automatically (progress decreasing) +``` + +### Ambient Particle System + +``` +Implementation: +- HTML5 Canvas element, position: fixed, z-index: 0, pointer-events: none +- Particle class: { x, y, vx, vy, size, opacity, sectionBehavior } +- requestAnimationFrame loop at 30fps (16.67ms frame budget * 2 = 33ms interval) +- Per frame: + 1. Read packet position from shared ref (no React re-render) + 2. For each particle: apply section-specific behavior, apply packet proximity force, update position + 3. Clear canvas, draw all particles +- Particle count adapts to device: navigator.hardwareConcurrency > 4 ? 300 : 150 +- Canvas resolution: window.devicePixelRatio (retina support) capped at 2x +``` + +### "Run Algorithm" Implementation + +``` +Sequence: +1. User clicks "Run Algorithm" button +2. Create 4 additional useMotionValue instances (one per branch) +3. Animate all 4 from branch start to branch end simultaneously (spring animation, 2s duration) +4. Each branch's project component receives its packet progress and builds its card +5. On completion (all 4 reach endpoint), reverse-animate all 4 back to the branch point +6. Merge: scale all 4 packets to 0 while scaling the main packet back to 1 +7. Clean up: remove branch useMotionValue instances +8. Mark all projects as explored, illuminate main track forward + +State: +- algorithmRunning: boolean +- branchProgresses: MotionValue[] (created on demand) +- exploredProjects: Set +``` + +### Performance Budget + +- **Target**: 60fps for packet drag interaction, 30fps for ambient particles +- **SVG elements**: <100 total (paths, nodes, flow particles). No DOM-heavy rendering. +- **Canvas**: Single canvas for particles. 150-300 particles at 30fps is well within budget. +- **React renders**: Packet position uses useMotionValue (bypasses React render cycle). Section components only re-render when their progress crosses a threshold (not every frame). +- **Path calculations**: `getPointAtLength()` is called per frame for the packet — cached via lookup table (pre-compute 1000 points along the path at mount time, interpolate between them). +- **Bundle**: Framer Motion (~30kb gzip) + lightweight d3-path for SVG path math (~3kb gzip). Total JS: <80kb gzip. +- **will-change**: Applied to the packet element and all currently-animating card elements. Removed when animation completes. + +### Reduced Motion + +When `prefers-reduced-motion: reduce` is active: + +- Pipeline track is visible but static (no glow animation, no flow particles) +- Packet is replaced by a section indicator — clicking pipeline nodes reveals content directly +- Content cards appear with simple opacity fades (200ms) instead of assembly choreography +- No ambient particles +- "Run Algorithm" shows all project cards simultaneously without animation +- Navigation reverts to scroll mode with pipeline as decorative sidebar +- All metric numbers display final values immediately + +--- + +## Accessibility + +### ARIA Structure + +```html + + + + Skills + Experience + + + + + + + + + + + + + + + + + +``` + +### Screen Reader Experience + +Screen readers receive content in logical order regardless of pipeline state. All section content is present in the DOM (not dynamically loaded) — visual reveal is CSS-only (opacity, transform). This means screen readers can traverse the entire CV content immediately. + +The pipeline interaction is wrapped in `role="application"` with clear keyboard instructions. Screen reader users can also bypass the pipeline entirely via the section navigation buttons. + +### Keyboard Navigation + +Full keyboard support as detailed in the Navigation section: +- Arrow keys move the packet between nodes +- Number keys jump to sections +- Tab navigates interactive elements +- Enter activates the "Run Algorithm" button +- Home/End for start/finish + +### Focus Management + +- When the packet reaches a new section, focus is not automatically moved (this would be disorienting). Instead, the section navigation button for the current section receives an `aria-current="section"` attribute. +- Tab order follows logical CV structure: Hero → Skills → Experience → Education → Projects → Contact. +- All focusable elements have visible focus indicators (2px solid #22D1EE, 2px offset, 4px border-radius). + +### Color Contrast + +All text on dark backgrounds meets WCAG AA minimum: + +- Off-white (#E6EDF3) on deep charcoal (#0D1117) = contrast ratio 13.2:1 (AAA) +- Slate (#8B949E) on deep charcoal (#0D1117) = contrast ratio 5.1:1 (AA) +- Electric cyan (#00D4AA) on deep charcoal (#0D1117) = contrast ratio 8.9:1 (AAA) +- Teal (#00897B) on deep charcoal (#0D1117) = contrast ratio 5.3:1 (AA) +- White (#FFFFFF) on elevated dark (#161B22) = contrast ratio 15.4:1 (AAA) + +### Touch Targets + +All interactive elements meet minimum 48x48px touch target size: +- Data packet: 48x48px touch area (visually 16-24px, but touch target is expanded) +- Pipeline nodes (mobile tap navigation): 48x48px +- "Run Algorithm" button: minimum 48px height +- Side navigation nodes: 48x48px touch areas + +--- + +## What Makes This Special + +1. **It's the only portfolio site with drag-as-primary-navigation.** No one has seen this before. The moment a visitor realizes they're dragging a glowing orb through a pipeline, they know this isn't a template. Novelty is the strongest driver of link sharing. + +2. **The metaphor is literal.** Andy builds data pipelines. His CV IS a data pipeline. The user IS the data being processed. There's no metaphorical stretch — this is exactly what his work looks like, translated into an interactive experience. Every recruiter who asks "what do you actually DO?" gets their answer through the medium, not just the text. + +3. **"Run Algorithm" is the share moment.** Watching a single packet duplicate into four simultaneous parallel-processing streams, each building a project card in real-time, is the kind of interaction people screen-record. It directly demonstrates the value of automation versus manual work — the user has been doing it manually (one project at a time), then sees the algorithm do it all at once. That contrast IS Andy's professional pitch. + +4. **The transition is seamless.** The ECG heartbeat line literally straightens into the pipeline track. The heartbeat pulse echoes in the packet's birth. The biological becomes technical. The entire site is one continuous visual thread from the first terminal boot character to the contact form submission animation. No seam, no break, no "now the real site starts" moment. + +5. **It rewards exploration.** The momentum physics make dragging playful — you can launch the packet and watch it coast. The branch points create genuine choices. The ambient particles create a living environment. The snap points encourage pausing. The glow dynamics make movement feel powerful. The bidirectional animation means exploring backward is just as satisfying as going forward. + +6. **Dark theme serves the content.** A data analyst's portfolio should feel like a command center, not a brochure. The dark background with glowing pipeline and bright metrics creates immediate technical credibility. It says "this person works with data infrastructure" before you read a single word. diff --git a/designs/07-the-clinical-record.md b/designs/07-the-clinical-record.md new file mode 100644 index 0000000..4ec8003 --- /dev/null +++ b/designs/07-the-clinical-record.md @@ -0,0 +1,1127 @@ +# Design 7: The Clinical Record + +## Overview + +Andy's CV is presented as a **Patient Medical Record (PMR) system** — the kind of GP clinical software (EMIS Web, SystmOne, Vision) that Andy and every pharmacist in the UK interacts with daily. The "patient" is Andy's career. The user navigates the interface exactly as a clinician would navigate a patient record, and each section of the PMR reveals a different facet of Andy's professional life. + +This is NOT a handwritten prescription pad or a clinical "theme" loosely applied. This is a **faithful digital clinical information system** — structured, database-driven, tabular, with the distinctive UI patterns of actual NHS clinical software: patient banner at the top, tabbed clinical views, consultation history as a reverse-chronological journal, medications list with dosage columns, coded entries with SNOMED-style references, traffic-light status indicators, and action buttons styled as clinical system controls. + +The concept works on two levels simultaneously: + +1. **For clinicians and pharmacists**: Immediate recognition. They will see a system they use every day and understand the navigation instinctively. The joke lands because of its fidelity — this isn't a parody, it's a faithful reproduction repurposed for a CV. They'll smile. + +2. **For recruiters and hiring managers**: A novel, highly navigable interface. Clinical record systems are designed for rapid information retrieval under time pressure — exactly what a recruiter needs. The tabbed views, the structured data, the alert banners — all make it fast to find what matters. + +**Key characteristics:** +- Sidebar navigation with clinical record categories (Summary, Consultations, Medications, Problems, Investigations, Documents, Referrals) +- Patient banner with persistent demographic context +- Consultation-journal format for experience (History / Examination / Plan) +- Tabular medications list for skills with proficiency "dosages" +- Clinical alert system for standout achievements +- Light-mode only — clinical systems are light-mode by design +- Border-heavy, table-heavy, functional — zero decorative flourish + +--- + +## ECG Transition + +**Starting point:** "ANDREW CHARLWOOD" is on screen in neon green (`#00ff41`) on black. The heartbeat trace is complete. The name is fully formed and glowing. + +**Then...** + +### Phase 1: The Flatline (600ms) + +The neon green name holds for a beat (300ms). Then the glow around the letters begins to fade. Simultaneously, from the right edge of the name, a flatline trace extends rightward — a perfectly horizontal green line drawn at the baseline, extending across the remaining viewport width over 300ms. The visual reads as a patient monitor flatline. This is deliberate: the "patient" (the animation phase) is ending. A new record is about to open. + +The flatline has a subtle audio-visual implication without actual sound — the green line is steady and unbroken, the glow around the name letters reduces to zero. The entire canvas is now: a fading green name with a horizontal flatline extending to the right edge. All on black. + +### Phase 2: Screen Clear (400ms) + +The entire canvas fades to black over 200ms (the name and flatline dissolve into darkness). Then, from black, the background transitions to a dark blue-gray (`#1E293B`) over 200ms. This is the color of a clinical system login screen — the dark institutional background that every NHS worker recognizes from their Monday morning. + +### Phase 3: Login Sequence (1200ms) + +A login panel materializes center-screen: a white card (320px wide, 12px border-radius, subtle shadow) on the dark blue-gray background. The card contains: + +- A small NHS-blue shield icon or generic clinical system logo at the top +- **Username field**: Empty text input with label "Username". After 200ms, a cursor appears and types `A.CHARLWOOD` character by character (30ms per character, ~350ms total). The typing uses Geist Mono / monospace font. +- **Password field**: After a 150ms pause, dots fill the password field in rapid succession (8 dots, 20ms each, ~160ms total). +- **"Log In" button**: NHS blue (`#005EB8`), full width. After another 150ms pause, the button receives a subtle pressed state (darkens slightly, 100ms) as if clicked. + +The login card holds for 200ms in its "submitted" state, then... + +### Phase 4: Interface Materialization (500ms) + +The login card scales up slightly (103%) and fades out (200ms). As it fades, the full PMR interface fades in behind it: + +1. **Patient banner** slides down from the top edge (200ms, ease-out) +2. **Sidebar** slides in from the left edge (250ms, ease-out, starting 50ms after the banner) +3. **Main content area** (Summary view) fades in (300ms, starting 100ms after sidebar begins) +4. **Clinical alert banner** slides down from beneath the patient banner (250ms, spring easing, starting 200ms after main content appears) + +### Phase 5: Final State + +The full PMR interface is visible: patient banner at top, dark sidebar on left, Summary view in the main content area, and the clinical alert banner demanding attention. The user is now "logged in" to Andy's career record. + +**Total transition duration:** ~2.7 seconds + +**Why this works:** The login sequence is the most immersive transition of all six designs. Every NHS worker, every pharmacist, every GP has typed their credentials into a clinical system at 8am on a Monday. This transition puts them right there. It's specific, it's authentic, and it immediately establishes the metaphor: you are opening a patient record. The "patient" happens to be a career. + +--- + +## Visual System + +### 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. + +**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) + +**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) + +**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." + +**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 + +### 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. + +- **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 + +### Spacing and Layout + +- **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) +- **Table row height:** 40px +- **Section spacing:** 24px between content blocks +- **Base unit:** 4px — tighter spacing than the Dashboard design, reflecting clinical system density + +### 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. + +- **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 + +### 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. + +- **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. + +--- + +## Section-by-Section Design + +### Patient Banner (Persistent Top Chrome) + +The patient banner is the most recognizable element of any PMR system. It spans the full viewport width above the main content area and provides constant demographic context. + +**Full banner (80px height, visible at top of page):** + +``` ++---------------------------------------------------------------------------+ +| CHARLWOOD, Andrew (Mr) Active ● Open to opps. | +| DOB: 14/02/1993 | NHS No: 2211810 | Norwich, NR1 | +| 07795553088 | andy@charlwood.xyz [Download CV] [Email] [LinkedIn] | ++---------------------------------------------------------------------------+ +``` + +**Content mapping:** + +| PMR Field | Actual Content | Notes | +|-----------|---------------|-------| +| Patient name | CHARLWOOD, Andrew (Mr) | Surname first, comma-separated — exactly as in clinical systems | +| DOB | 14/02/1993 | DD/MM/YYYY format (UK clinical standard) | +| NHS Number | 221 181 0 | Andy's GPhC registration number formatted like an NHS number (with spaces). Hover tooltip: "GPhC Registration Number" | +| GP Practice | Self-Referred | Tongue-in-cheek — Andy referred himself to this record | +| Address | Norwich, NR1 | Abbreviated postcode area | +| Phone | 07795553088 | Clickable (tel: link) | +| Email | andy@charlwood.xyz | Clickable (mailto: link) | +| Status | Active (green dot) | Like the "registered" status in a PMR | +| Badge | Open to opportunities | Styled as a clinical banner tag (blue background, white text, small pill shape) | + +**Action buttons (top right of banner):** + +| Button | PMR Equivalent | Action | +|--------|---------------|--------| +| Download CV | Print Summary | Downloads PDF version of CV | +| Email | Send Letter | Opens mailto: link | +| LinkedIn | External Link | Opens LinkedIn profile in new tab | + +Buttons are styled as small outlined rectangles with NHS blue text and 1px NHS blue border, 4px radius. On hover: filled NHS blue background with white text. + +**Condensed banner (48px, sticky after scroll):** + +When the user scrolls past 100px of content, the banner smoothly condenses to show only the essential information on a single line: + +``` +CHARLWOOD, Andrew (Mr) | NHS No: 2211810 | Active ● [Download CV] [Email] +``` + +The condensed banner sticks to the top of the viewport (`position: sticky`) with a `z-index` above the content area but below modals/alerts. + +--- + +### Left Sidebar — Clinical Navigation + +The sidebar replicates the dark navigation panel found in EMIS Web and similar clinical systems. It provides category-based access to different "record views." + +**Width:** 220px (desktop), dark blue-gray (`#1E293B`) background. + +**Navigation items:** + +| Icon | Label | Maps To | Description | +|------|-------|---------|-------------| +| `ClipboardList` | Summary | Profile overview | Demographics, active problems, current meds, recent consultation | +| `FileText` | Consultations | Experience | Reverse-chronological journal of roles | +| `Pill` | Medications | Skills | Active medications list = skills with dosages | +| `AlertTriangle` | Problems | Achievements | Problem list = challenges resolved and ongoing | +| `FlaskConical` | Investigations | Projects | Investigation results = project outcomes | +| `FolderOpen` | Documents | Education | Attached documents = certificates and qualifications | +| `Send` | Referrals | Contact | Referral form = contact/message form | + +**Styling:** +- Each item: 44px height, 16px left padding, icon (18px, `lucide-react`) + label in Inter 500, 14px +- Default state: white text at 70% opacity, transparent background +- Hover state: white text at 100% opacity, background `rgba(255,255,255,0.08)` +- Active state: white text at 100%, NHS blue left border (3px), background `rgba(255,255,255,0.12)`, label in Inter 600 +- A thin horizontal separator line (`1px solid rgba(255,255,255,0.1)`) appears between "Summary" and "Consultations" (separating the overview from the detail views) + +**Sidebar footer:** +At the bottom of the sidebar, in small text (Inter 400, 11px, `#64748B`): +``` +Session: A.CHARLWOOD +Logged in: [current time] +``` +This updates with the actual current time on mount, reinforcing the "logged in" metaphor. + +**Sidebar header:** +At the top, above the navigation items, a small logo or system name: +``` +CareerRecord PMR +v1.0.0 +``` +In Inter 500, 13px, white at 50% opacity. Styled like the "EMIS Web" branding that appears in the top-left of the real system. + +--- + +### Summary View + +The landing view after login. This mimics the "Patient Summary" screen — the first screen a clinician sees when opening a patient record, showing the most important information at a glance. + +**Layout:** A grid of summary cards arranged in a 2-column layout on desktop, single column on mobile. Each card has a header bar with the card title in Inter 600, 14px, uppercase, on a `#F9FAFB` background with `1px solid #E5E7EB` bottom border. + +**Card 1: Patient Demographics (spans full width)** + +``` ++--[ Patient Demographics ]------------------------------------------+ +| Name: Andrew Charlwood Status: Active ● | +| DOB: 14 February 1993 Location: Norwich, UK | +| Registration: GPhC 2211810 Since: August 2016 | +| Qualification: MPharm (Hons) 2:1 University: UEA, 2015 | ++---------------------------------------------------------------------+ +``` + +A two-column key-value table. Labels in Inter 500, 13px, gray-500. Values in Inter 400, 14px, gray-900. Labels right-aligned, values left-aligned — mimicking clinical system demographics layout. + +**Card 2: Active Problems (left column)** + +``` ++--[ Active Problems ]-----------------------------------------------+ +| ● Deputy Head, Pop. Health & Data Analysis Jul 2024–Present | +| NHS Norfolk & Waveney ICB | +| ● £220M prescribing budget management Ongoing | +| ● Patient-level SQL analytics transformation In progress | ++---------------------------------------------------------------------+ +``` + +A list with green dots for active/current items, amber dots for in-progress items. Each entry has a title in Inter 500, 14px, and a date range or status in Geist Mono, 12px, right-aligned. Click an entry to navigate to the corresponding Consultation. + +**Card 3: Current Medications — Quick View (right column)** + +``` ++--[ Current Medications (Quick View) ]-------------------------------+ +| Python | 90% | Daily | Active ● | +| SQL | 88% | Daily | Active ● | +| Power BI | 92% | Daily | Active ● | +| Data Analysis | 95% | Daily | Active ● | +| JS / TypeScript | 70% | Weekly | Active ● | +| [View Full List →] | ++---------------------------------------------------------------------+ +``` + +A compact 4-column table showing the top 5 skills. "View Full List" links to the Medications view. Table headers are uppercase, 12px, gray-400. Table rows alternate between `#FFFFFF` and `#F9FAFB` backgrounds. + +**Card 4: Last Consultation (spans full width)** + +``` ++--[ Last Consultation ]----------------------------------------------+ +| Date: May 2025 Clinician: A. Charlwood Location: NHS N&W ICB | +| | +| Interim Head, Population Health & Data Analysis | +| Led strategic delivery of population health initiatives and | +| data-driven medicines optimisation across Norfolk & Waveney ICS... | +| [View Full Record →] | ++---------------------------------------------------------------------+ +``` + +A preview of the most recent role, truncated to 2-3 lines. "View Full Record" navigates to Consultations with that entry expanded. + +**Card 5: Alerts (full width, positioned above all other cards)** + +This is the **Clinical Alert** — see the dedicated section below. + +--- + +### Consultations View (= Experience) + +Each role is a "consultation entry" in a reverse-chronological journal. This is the core content view and the most detailed section. + +**Journal list layout:** + +Entries are stacked vertically, most recent at top. Each entry has a collapsed state and an expanded state. + +**Collapsed entry:** + +``` ++------------------------------------------------------------------+ +| ● 14 May 2025 | NHS Norfolk & Waveney ICB | +| Interim Head, Population Health & Data Analysis | +| Key: £14.6M efficiency programme identified and delivered | +| [▼ Expand] | ++------------------------------------------------------------------+ +``` + +- Date in Geist Mono, 13px, gray-500 (left-aligned) +- Organization in Inter 400, 13px, NHS blue +- Role title in Inter 600, 15px, gray-900 +- Key coded entry: a single-line summary of the most notable achievement, prefixed with "Key:" in Inter 500, gray-500 +- Expand chevron button (right-aligned) +- Status dot: green for current roles, gray for historical + +**Expanded entry (click to expand):** + +``` ++------------------------------------------------------------------+ +| ● 14 May 2025 | NHS Norfolk & Waveney ICB [▲ Close] | +| Interim Head, Population Health & Data Analysis | +| Duration: May 2025 — Nov 2025 | +| | +| HISTORY | +| Returned to substantive Deputy Head role following | +| commencement of ICB-wide organisational consultation. | +| Led strategic delivery of population health initiatives | +| and data-driven medicines optimisation across Norfolk & | +| Waveney ICS, reporting to Associate Director of Pharmacy. | +| | +| EXAMINATION | +| - Identified £14.6M efficiency programme through | +| comprehensive data analysis | +| - Built Python-based switching algorithm: 14,000 patients | +| identified, £2.6M annual savings | +| - Automated incentive scheme analysis: 50% reduction | +| in targeted prescribing within 2 months | +| | +| PLAN | +| - Achieved over-target performance by October 2025 | +| - £2M on target for delivery this financial year | +| - Presented to CMO bimonthly with evidence-based | +| recommendations | +| - Led transformation to patient-level SQL analytics | +| | +| CODED ENTRIES | +| [EFF001] Efficiency programme: £14.6M identified | +| [ALG001] Algorithm: 14,000 patients, £2.6M savings | +| [AUT001] Automation: 50% prescribing reduction in 2mo | +| [SQL001] Data transformation: practice→patient level | ++------------------------------------------------------------------+ +``` + +**The History / Examination / Plan structure:** + +This is a direct mapping from the clinical consultation format (SOAP notes: Subjective, Objective, Assessment, Plan) to career content: + +| Clinical Term | CV Mapping | What Goes Here | +|--------------|------------|----------------| +| **History** | Context / Background | Why this role existed, what situation Andy walked into, reporting lines | +| **Examination** | Analysis / Findings | What Andy discovered, built, or analyzed — the technical and analytical work | +| **Plan** | Outcomes / Delivery | What was achieved, what impact was measured, what's ongoing | + +Section headers ("HISTORY", "EXAMINATION", "PLAN") are styled in Inter 600, 12px, uppercase, letter-spacing 0.05em, gray-400 — exactly like the section dividers in a clinical consultation record. + +**Coded entries:** + +At the bottom of each expanded consultation, "coded entries" appear — short-form tagged achievements with bracket codes. These mimic SNOMED CT / Read codes used in clinical systems. The codes are fictional but consistent (EFF = efficiency, ALG = algorithm, AUT = automation, SQL = data, etc.). Styled in Geist Mono, 12px, gray-500, with the code in brackets and the description after. + +**Color coding by employer:** + +Each consultation entry has a subtle left border (3px) indicating the employer: +- NHS Norfolk & Waveney ICB: NHS blue (`#005EB8`) +- Tesco PLC: Teal (`#00897B`) + +This visual grouping helps the user quickly scan which organization each entry belongs to, without reading the text. + +**Full consultation journal (all roles mapped):** + +| Date | Organization | Role | Key Coded Entry | +|------|-------------|------|-----------------| +| May 2025 | NHS N&W ICB | Interim Head, Pop. Health & Data Analysis | [EFF001] £14.6M efficiency programme | +| Jul 2024 | NHS N&W ICB | Deputy Head, Pop. Health & Data Analysis | [BUD001] £220M budget management | +| May 2022 | NHS N&W ICB | High-Cost Drugs & Interface Pharmacist | [AUT002] Blueteq automation: 70% reduction | +| Nov 2017 | Tesco PLC | Pharmacy Manager | [INN001] Asthma screening: ~£1M national revenue | +| Aug 2016 | Tesco PLC | Duty Pharmacy Manager | [REG001] GPhC registration commenced | + +--- + +### Medications View (= Skills) + +Skills presented as an active medications list — the format every pharmacist and GP reads daily. + +**Full table layout:** + +``` ++--[ Active Medications ]-------------------------------------------------+ +| Drug Name | Dose | Frequency | Start | Status | +|--------------------+-------+------------+----------+-------------------| +| Python | 90% | Daily | 2017 | Active ● | +| SQL | 88% | Daily | 2017 | Active ● | +| Power BI | 92% | Daily | 2019 | Active ● | +| Data Analysis | 95% | Daily | 2016 | Active ● | +| JavaScript / TS | 70% | Weekly | 2020 | Active ● | +| Dashboard Dev | 88% | Weekly | 2019 | Active ● | +| Algorithm Design | 82% | Weekly | 2022 | Active ● | +| Data Pipelines | 80% | Weekly | 2022 | Active ● | ++-------------------------------------------------------------------------+ + ++--[ Clinical Medications ]-----------------------------------------------+ +| Drug Name | Dose | Frequency | Start | Status | +|-------------------------+-------+------------+--------+----------------| +| Medicines Optimisation | 95% | Daily | 2016 | Active ● | +| Pop. Health Analytics | 90% | Daily | 2022 | Active ● | +| NICE TA Implementation | 85% | Weekly | 2022 | Active ● | +| Health Economics | 80% | Monthly | 2023 | Active ● | +| Clinical Pathways | 82% | Weekly | 2022 | Active ● | +| CD Assurance | 88% | Weekly | 2024 | Active ● | ++-------------------------------------------------------------------------+ + ++--[ PRN (As Required) ]--------------------------------------------------+ +| Drug Name | Dose | Frequency | Start | Status | +|-------------------------+-------+------------+--------+----------------| +| Budget Management | 90% | As needed | 2024 | Active ● | +| Stakeholder Engagement | 88% | As needed | 2022 | Active ● | +| Pharma Negotiation | 85% | As needed | 2024 | Active ● | +| Team Development | 82% | As needed | 2017 | Active ● | ++-------------------------------------------------------------------------+ +``` + +**Column definitions:** + +| Column | PMR Meaning | CV Mapping | +|--------|------------|------------| +| Drug Name | Medication name | Skill name | +| Dose | Dosage strength | Proficiency percentage | +| Frequency | How often taken | How often the skill is used (Daily / Weekly / Monthly / As needed) | +| Start | Date prescribed | Year Andy started using this skill (approximate) | +| Status | Active / Stopped | Active (green dot) for current skills, Historical (gray dot) for deprecated skills | + +**Medication categories (tabs within the view):** + +Skills are grouped into three "medication types," mimicking how clinical systems separate regular, acute, and PRN medications: + +- **Active Medications** = Technical skills (the "regular medications" — taken daily, core to function) +- **Clinical Medications** = Healthcare domain skills (the specialist prescriptions) +- **PRN (As Required)** = Strategic & leadership skills (used situationally, not daily) + +**Table styling:** +- Table headers: Inter 600, 13px, uppercase, gray-400, `#F9FAFB` background +- Table rows: alternating `#FFFFFF` / `#F9FAFB` backgrounds +- Row height: 40px +- All borders: `1px solid #E5E7EB` +- Hover state: row background changes to `#EFF6FF` (subtle blue tint) +- Status dots: 6px circles, inline with status text + +**Interaction — Prescribing History:** + +Clicking any medication/skill row expands it downward to show a "prescribing history" — a mini-timeline of how the skill developed: + +``` +Python | 90% | Daily | 2017 | Active ● + └─ Prescribing History: + 2017 Started: Self-taught for data analysis automation + 2019 Increased: Dashboard development, data pipeline work + 2022 Specialist use: Blueteq automation, Sankey analysis tools + 2024 Advanced: Switching algorithm (14,000 patients), CD monitoring + 2025 Current: Population-level analytics, incentive scheme automation +``` + +The history entries are styled in Geist Mono, 12px, with year markers as bold anchors and descriptions in regular weight. This "prescribing history" shows skill progression in a format that clinicians understand intuitively. + +**Sortable columns:** + +Table columns are sortable by clicking the header. Clicking "Dose" sorts by proficiency descending. Clicking "Start" sorts chronologically. A small sort indicator arrow appears in the active sort column header. Default sort: by category grouping. + +--- + +### Problems View (= Achievements / Challenges) + +The "Problems" list in a clinical record tracks diagnoses — conditions that were identified, treated, and either resolved or require ongoing management. This maps perfectly to career achievements: challenges that Andy identified and resolved. + +**Two sections: Active Problems and Resolved Problems.** + +**Active Problems (current / ongoing):** + +``` ++--[ Active Problems ]----------------------------------------------------+ +| Status | Code | Problem | Since | +|--------+-----------+--------------------------------------+------------| +| ● AMB | [MGT001] | £220M prescribing budget oversight | Jul 2024 | +| ● GRN | [TRN001] | Patient-level SQL transformation | 2025 | +| ● AMB | [LEA001] | Team data literacy programme | Jul 2024 | ++-------------------------------------------------------------------------+ +``` + +**Resolved Problems (past achievements):** + +``` ++--[ Resolved Problems ]--------------------------------------------------+ +| Status | Code | Problem | Resolved | Outcome | +|--------+-----------+--------------------------------+-----------+------------------------------------------| +| ● GRN | [EFF001] | Manual prescribing analysis | Oct 2025 | Python algorithm: 14,000 pts, £2.6M/yr | +| | | inefficiency | | | +| ● GRN | [EFF002] | £14.6M efficiency target | Oct 2025 | Over-target performance achieved | +| ● GRN | [AUT001] | Blueteq form creation backlog | 2023 | 70% reduction, 200hrs saved | +| ● GRN | [INN001] | Asthma screening scalability | 2019 | National rollout: ~300 branches, ~£1M | +| ● GRN | [AUT002] | Incentive scheme manual calc. | 2025 | Automated: 50% Rx reduction in 2 months | +| ● GRN | [DAT001] | HCD spend tracking gaps | 2023 | Blueteq-secondary care data integration | +| ● GRN | [VIS001] | Patient pathway opacity | 2023 | Sankey chart analysis tool | +| ● GRN | [MON001] | Population opioid exposure | 2024 | CD monitoring system: OME tracking | +| | | monitoring | | | ++-------------------------------------------------------------------------+ +``` + +**Column definitions:** + +| Column | Meaning | +|--------|---------| +| Status | Traffic light: Green (resolved), Amber (in progress / active), Red (urgent — unused, reserved) | +| Code | SNOMED-style reference code. Fictional but internally consistent. Formatted in Geist Mono. | +| Problem | The challenge or opportunity Andy identified | +| Resolved | Date or year the problem was resolved | +| Outcome | Brief description of the resolution and its measurable impact | + +**Click to expand:** Each problem row can be expanded to show a full narrative: what the problem was, how Andy approached it, what tools/methods were used, and the quantified outcome. The expanded state also shows "linked consultations" — clicking a link navigates to the relevant entry in Consultations view. + +**Traffic light status indicators:** + +Traffic lights are 8px circles with the status colors (green, amber, red, gray). They appear inline before the code column. This is exactly how clinical systems indicate problem severity/status — it's an immediately scannable visual language. + +--- + +### Investigations View (= Projects) + +Projects presented as diagnostic investigations — tests that were ordered, performed, and returned results. + +**Investigation list:** + +``` ++--[ Investigation Results ]----------------------------------------------+ +| Test Name | Requested | Status | Result | +|------------------------------+-----------+----------+-------------------| +| PharMetrics Interactive | 2024 | Complete | Live ● | +| Platform | | | | +| Patient Switching Algorithm | 2025 | Complete | 14,000 pts found | +| Blueteq Generator | 2023 | Complete | 70% reduction | +| CD Monitoring System | 2024 | Complete | Population-scale | +| Sankey Chart Analysis Tool | 2023 | Complete | Pathway audit | +| Patient Pathway Analysis | 2024 | Ongoing | In development | ++-------------------------------------------------------------------------+ +``` + +**Status badges:** + +Styled like laboratory result status indicators: +- **Complete** (green dot): Investigation finished, results available +- **Ongoing** (amber dot): Investigation still in progress +- **Live** (pulsing green dot): Results are actively being used (for PharMetrics, which is a live URL) + +**Expanded investigation view:** + +Clicking an investigation row reveals a detailed "results panel" below the row: + +``` +PharMetrics Interactive Platform +├─ Date Requested: 2024 +├─ Date Reported: 2024 +├─ Status: Complete — Live at medicines.charlwood.xyz +├─ Requesting Clinician: A. Charlwood +├─ Methodology: +│ Real-time medicines expenditure dashboard providing +│ actionable analytics for NHS decision-makers. Built with +│ Power BI and SQL, tracking expenditure across the £220M +│ prescribing budget. +├─ Results: +│ - Real-time tracking of medicines expenditure +│ - Actionable analytics for budget holders +│ - Self-serve model for wider team +├─ Tech Stack: Power BI, SQL, DAX +└─ [View Results →] (external link to medicines.charlwood.xyz) +``` + +The expanded view uses a tree-like indented structure (with box-drawing characters in monospace) to present the investigation report. This mirrors how lab results and imaging reports appear in clinical systems — structured, indented, with labelled fields. + +**"View Results" link:** + +For PharMetrics (the only project with a live URL), a "View Results" button appears styled as an NHS blue action button. For internal projects, this button is absent. + +--- + +### Documents View (= Education & Certifications) + +Education and certifications presented as attached documents in the patient record — the scanned letters, certificates, and reports that get filed into a patient's record. + +**Document list:** + +``` ++--[ Attached Documents ]-------------------------------------------------+ +| Type | Document | Date | Source | +|----------------+----------------------------------+---------+------------| +| 📄 Certificate | MPharm (Hons) 2:1 | 2015 | UEA | +| 📄 Registration| GPhC Pharmacist Registration | 2016 | GPhC | +| 📄 Certificate | Mary Seacole Programme (78%) | 2018 | NHS LA | +| 📄 Results | A-Levels: Maths A*, Chem B, | 2011 | Highworth | +| | Politics C | | Grammar | +| 📄 Research | Drug Delivery & Cocrystals | 2015 | UEA | +| | (75.1% Distinction) | | | ++-------------------------------------------------------------------------+ +``` + +**Document type icons:** Small document icons (from Lucide: `FileText` for certificates, `Award` for registrations, `GraduationCap` for academic results, `FlaskConical` for research). These replace the generic emoji in the actual implementation. + +**Click to expand:** Each document reveals a "preview" panel: + +``` +MPharm (Hons) 2:1 — University of East Anglia +├─ Type: Academic Qualification +├─ Date Awarded: 2015 +├─ Institution: University of East Anglia, Norwich +├─ Classification: Upper Second-Class Honours (2:1) +├─ Duration: 2011 — 2015 (4 years) +├─ Research: Drug delivery and cocrystals +│ Grade: 75.1% (Distinction) +└─ Notes: MPharm is a 4-year integrated Master's degree + required for pharmacist registration in the UK. +``` + +The preview panel uses the same tree-indented structure as the Investigations expanded view, maintaining visual consistency across the PMR interface. + +--- + +### Referrals View (= Contact) + +Contact information presented as a clinical referral form — the mechanism for "referring" a patient (Andy) to another service. + +**Referral form layout:** + +``` ++--[ New Referral ]-------------------------------------------------------+ +| | +| Referring to: CHARLWOOD, Andrew (Mr) | +| NHS Number: 221 181 0 | +| | +| Priority: ○ Urgent ● Routine ○ Two-Week Wait | +| | +| Referrer Name: [________________________] | +| Referrer Email: [________________________] | +| Referrer Org: [________________________] (optional) | +| | +| Reason for Referral: | +| [ ] | +| [ ] | +| [ ] | +| | +| Contact Method: ○ Email ○ Phone ○ LinkedIn | +| | +| [ Cancel ] [ Send Referral ] | ++-------------------------------------------------------------------------+ +``` + +**Priority toggle (tongue-in-cheek):** + +Three radio options styled like clinical referral priorities: +- **Urgent**: Red label, red dot. Selectable but the tooltip reads "All enquiries are welcome, urgent or not." +- **Routine**: Blue label, blue dot. Default selected. +- **Two-Week Wait**: Amber label. Tooltip: "NHS cancer referral pathway — this isn't that, but the spirit of promptness applies." + +This is the design's main moment of humor. The priority options are visually authentic to clinical referral forms, and the tongue-in-cheek tooltips reward exploration without undermining the professional tone. + +**Form fields:** + +Standard clinical form inputs: `1px solid #D1D5DB` border, `4px` radius, `8px 12px` padding. Labels in Inter 500, 13px, gray-600, positioned above inputs. Focus state: border changes to NHS blue, subtle blue glow (`box-shadow: 0 0 0 3px rgba(0, 94, 184, 0.15)`). + +**Submit button:** + +"Send Referral" in NHS blue (`#005EB8`), white text, full width of the right half of the form. On hover: darkens to `#004494`. On click: brief loading state (spinner icon), then a success message: + +``` +✓ Referral sent successfully + Reference: REF-2026-0210-001 + Expected response time: 24-48 hours +``` + +The reference number is generated from the current date. The success state mimics the confirmation screen shown after submitting a clinical referral in EMIS. + +**Alternative contact methods (below the form):** + +``` ++--[ Direct Contact ]-----------------------------------------------------+ +| Email: andy@charlwood.xyz [Send Email →] | +| Phone: 07795553088 [Call →] | +| LinkedIn: linkedin.com/in/andycharlwood [View Profile →] | +| Location: Norwich, UK | ++-------------------------------------------------------------------------+ +``` + +Styled as a simple key-value table, same format as the Patient Demographics card in Summary view. + +--- + +### The Clinical Alert (Signature Interaction) + +When the user first loads the Summary view (immediately after the login transition), a clinical alert banner slides down from beneath the patient banner. + +**Alert styling:** + +``` ++--[ ⚠ CLINICAL ALERT ]--------------------------------------------------+ +| ⚠ ALERT: This patient has identified £14.6M in prescribing | +| efficiency savings across Norfolk & Waveney ICS. | +| [Acknowledge] | ++-------------------------------------------------------------------------+ +``` + +- Background: amber (`#FEF3C7` — amber-100, light amber) +- Left border: 4px solid `#F59E0B` (amber-500) +- Warning icon: `AlertTriangle` from Lucide, amber-600 +- Text: Inter 500, 14px, `#92400E` (amber-800) +- "Acknowledge" button: small outlined button, amber border and text + +**Behavior:** +1. The alert slides down from beneath the patient banner with a spring animation (250ms, slight overshoot) after the PMR interface finishes materializing. +2. It pushes the Summary content downward, so it's impossible to miss. +3. Clicking "Acknowledge" triggers a brief animation: a green checkmark replaces the warning icon (200ms), then the alert collapses upward (200ms, ease-out) and is gone. +4. The dismiss state is stored in React state (session-only) — refreshing the page shows the alert again. + +**Why this works:** Clinical alerts are the mechanism that clinical systems use to put critical information in front of clinicians before they do anything else. They are the highest-priority information in the system. By framing Andy's most impressive metric ("£14.6M") as a clinical alert, it gets the same treatment — it's the first thing the user reads, it demands acknowledgment, and its format gives the number institutional weight. This is not a boast in a paragraph; it's a system-generated alert based on data. The framing makes the achievement feel objective. + +**Second alert (optional, on Consultations view):** + +When the user first navigates to Consultations, a secondary alert could appear: + +``` +⚠ NOTE: Patient has developed a Python-based switching algorithm + identifying 14,000 patients for cost-effective medication alternatives. + £2.6M annual savings potential. Review recommended. +``` + +This second alert reinforces the key technical achievement in clinical language. It appears only once (on first navigation to Consultations) and is dismissible with the same "Acknowledge" interaction. + +--- + +## Interactions and Micro-interactions + +### Sidebar Navigation +- Clicking a sidebar item instantly swaps the main content area. No crossfade, no transition — just an immediate swap. This matches clinical system behavior exactly: navigation is instant. +- The active sidebar item updates its left border (3px, NHS blue) and background tint simultaneously, with no animation (instant state change). + +### Consultation Expand / Collapse +- Clicking a consultation entry toggles between collapsed (single-line summary) and expanded (full History/Examination/Plan) states. +- The expand animation: height grows from 0 to content height over 200ms, ease-out. Content opacity transitions from 0 to 1 over the same duration. +- Only one consultation can be expanded at a time. Expanding a new entry collapses the previous one. +- The expand chevron rotates 180 degrees (pointing up when expanded). + +### Medication Row Hover +- Hovering a medication table row changes its background to `#EFF6FF` (subtle blue tint) — exactly how EMIS highlights the hovered row. +- No transform, no elevation change. Just color. + +### Table Column Sorting +- Clicking a table column header sorts by that column. An arrow indicator (up/down) appears in the header. +- Clicking the same header again reverses sort direction. +- Sorting is instant (no animation on row reordering). + +### Patient Banner Scroll Condensation +- As the user scrolls past 100px of content, the patient banner smoothly transitions from full (80px) to condensed (48px) over 200ms. +- The condensed banner shows only: name, NHS number, status dot, and action buttons. +- Scrolling back to top restores the full banner. +- Uses `position: sticky` with an `IntersectionObserver` to trigger the condensation. + +### Alert Acknowledge +- Clicking "Acknowledge" on a clinical alert: + 1. The warning icon cross-fades to a green checkmark (200ms) + 2. After a 200ms hold, the alert's height animates to 0 (200ms, ease-out) + 3. Content below shifts upward to fill the space (same 200ms timing) + +### Search +- A search input in the sidebar header ("Search record...") provides fuzzy matching across all PMR sections. +- Typing shows a dropdown of results grouped by section (Consultations, Medications, Problems, etc.). +- Each result shows the section icon, the matching text, and a relevance indicator. +- Pressing Enter or clicking a result navigates to that section with the matching item highlighted/expanded. +- Implementation: fuse.js for fuzzy search across a pre-built index of all content. + +### Context Menus +- Right-clicking (desktop) or long-pressing (mobile) on certain elements reveals a context menu: + - On a consultation entry: "Expand", "Copy to clipboard", "View coded entries" + - On a medication row: "View prescribing history", "Copy to clipboard" + - On a problem entry: "View linked consultations", "Copy to clipboard" +- Context menus are implemented with Headless UI `Menu` component for accessibility. +- Styled: white background, `1px solid #E5E7EB` border, 4px radius, `box-shadow: 0 4px 12px rgba(0,0,0,0.1)`. Items in Inter 400, 14px, 36px row height. + +### Login Screen Typing +- The username types character-by-character (30ms per character). +- The password dots appear faster (20ms per dot). +- A blinking cursor appears in the active field (530ms blink interval). +- The "Log In" button shows a brief active/pressed state before the interface materializes. + +--- + +## Navigation + +### Primary Navigation: Left Sidebar + +The sidebar is always visible on desktop — this is how clinical systems work. There is no floating nav, no hamburger menu on desktop, and no scroll-based navigation. The sidebar provides persistent, direct access to any record section. + +**Navigation items and keyboard shortcuts:** + +| Sidebar Item | Section | Shortcut | +|-------------|---------|----------| +| Summary | Profile overview | `Alt+1` | +| Consultations | Experience | `Alt+2` | +| Medications | Skills | `Alt+3` | +| Problems | Achievements | `Alt+4` | +| Investigations | Projects | `Alt+5` | +| Documents | Education | `Alt+6` | +| Referrals | Contact | `Alt+7` | + +**URL hash routing:** Each sidebar item updates the URL hash (`#summary`, `#consultations`, `#medications`, etc.) for direct linking. On page load, the app reads the hash and navigates to the corresponding view. + +### Secondary Navigation: Within-View Interactions + +- **Summary:** Clicking "View Full List" or "View Full Record" links navigates to the corresponding sidebar section. +- **Consultations:** Expand/collapse individual entries. "Linked consultations" in Problems view can deep-link to specific consultation entries. +- **Medications:** Category tabs (Active, Clinical, PRN) within the view. Click to expand prescribing history. +- **Problems:** Click to expand. "Linked consultations" navigate to Consultations view. +- **Investigations:** Click to expand results. +- **Documents:** Click to expand preview. +- **Referrals:** No sub-navigation. + +### Breadcrumb + +A breadcrumb appears at the top of the main content area: + +``` +Patient Record > Consultations > Interim Head, Population Health +``` + +The breadcrumb updates as the user navigates deeper (e.g., expanding a consultation). Clicking "Patient Record" returns to Summary. Clicking "Consultations" collapses any expanded entries and shows the full journal list. The breadcrumb is styled in Inter 400, 13px, gray-400, with chevron separators. + +--- + +## Responsive Strategy + +### Desktop (>1024px) + +The full PMR experience. This is the design's primary target — clinical systems are desktop applications. + +- Sidebar: 220px, always visible, dark blue-gray +- Patient banner: full width, 80px height, condensing to 48px on scroll +- Main content: fills remaining width (no max-width constraint) +- Tables: full column display, alternating row colors, sort controls +- Consultations: full History/Examination/Plan expanded view +- Search: integrated in sidebar header + +### Tablet (768-1024px) + +Sidebar collapses to icon-only mode (56px width). Hovering (desktop) or tapping an icon shows the label as a tooltip. The sidebar can be expanded to full width by clicking a hamburger/expand button at its top. + +- Patient banner: condensed to single-line format always (no full/condensed toggle) +- Main content: nearly full width +- Tables: may horizontally scroll if columns exceed available width. A scroll indicator appears. +- Consultations: full expand/collapse behavior preserved +- Context menus: triggered by long-press instead of right-click + +### Mobile (<768px) + +The sidebar becomes a **bottom navigation bar** with 7 icon buttons. This mirrors mobile clinical apps (EMIS Mobile, the NHS App) where bottom tabs replace the sidebar. + +**Bottom nav layout:** + +``` +[Summary] [Consult] [Meds] [Problems] [Invest] [Docs] [Refer] +``` + +Each icon is from Lucide, 20px, with the active item highlighted in NHS blue with a label appearing below the icon. The bottom nav is 56px height with safe area padding. + +**Patient banner on mobile:** + +Minimal top bar: `CHARLWOOD, A (Mr) | 2211810 | ●` — just enough to maintain the PMR metaphor. Action buttons collapse into a "..." overflow menu. + +**Content adaptations:** + +- Tables switch to a **card layout**: each row becomes a small card with fields stacked vertically. This avoids horizontal scrolling on narrow screens while preserving all data. +- Consultation entries show the collapsed view with a tap-to-expand pattern (same as desktop but optimized for touch — larger tap targets, 48px minimum height). +- Medications: the table becomes a stacked card list. Each "medication" card shows: Drug Name (large), Dose / Frequency / Status on a single line below. +- Referral form: full-width inputs, generous touch targets. Priority radio buttons become larger tap areas. +- Search: moves to the top of each view as a search bar (not in the bottom nav). + +**Back navigation:** Each view has a back arrow in the top-left corner (beside the banner) that returns to Summary. This prevents the need for the bottom nav to have a dedicated "back" button. + +### Breakpoint Summary + +| Element | Desktop (>1024) | Tablet (768-1024) | Mobile (<768) | +|---------|-----------------|-------------------|---------------| +| Sidebar | 220px, full labels | 56px, icons only | Bottom nav bar | +| Patient banner | 80px full / 48px sticky | 48px always | Minimal top bar | +| Tables | Full columns, horizontal | Scroll if needed | Card layout (stacked) | +| Consultations | Expand inline | Expand inline | Expand inline (touch) | +| Search | Sidebar header | Sidebar header | Top of each view | +| Context menus | Right-click | Long-press | Long-press | +| Clinical alert | Full width banner | Full width banner | Full width banner | + +--- + +## Technical Implementation + +### Component Architecture + +``` +App.tsx + BootSequence.tsx + ECGAnimation.tsx (modified exit: flatline → login) + ClinicalRecord.tsx (replaces current content phase) + LoginScreen.tsx (animated login sequence) + PMRInterface.tsx (main PMR layout after login) + PatientBanner.tsx + PatientBannerFull.tsx + PatientBannerCondensed.tsx + BannerActionButtons.tsx + ClinicalAlert.tsx + ClinicalSidebar.tsx + SidebarItem.tsx + SidebarSearch.tsx + SidebarFooter.tsx + MainContent.tsx (renders active view) + SummaryView.tsx + DemographicsCard.tsx + ActiveProblemsCard.tsx + QuickMedsCard.tsx + LastConsultationCard.tsx + ConsultationsView.tsx + ConsultationEntry.tsx (expand/collapse) + CodedEntries.tsx + MedicationsView.tsx + MedicationTable.tsx + MedicationRow.tsx + PrescribingHistory.tsx + ProblemsView.tsx + ProblemEntry.tsx + TrafficLight.tsx + InvestigationsView.tsx + InvestigationEntry.tsx + InvestigationResults.tsx + DocumentsView.tsx + DocumentEntry.tsx + DocumentPreview.tsx + ReferralsView.tsx + ReferralForm.tsx + PriorityToggle.tsx + DirectContact.tsx + Breadcrumb.tsx + ContextMenu.tsx +``` + +### State Management + +- **Active sidebar view:** React `useState` in `PMRInterface.tsx`. Updated on sidebar click. Synced to URL hash via `useEffect`. +- **Expanded consultation ID:** `useState` — only one can be expanded at a time. Expanding a new entry sets its ID and implicitly collapses the previous. +- **Expanded medication ID:** Separate `useState` for the prescribing history expansion. +- **Alert dismissed:** `useState` (session-only, resets on reload). Array of dismissed alert IDs. +- **Patient banner condensed:** Boolean state driven by `IntersectionObserver` on a sentinel element near the top of the content area. +- **Medication sort:** `useState` holding `{ column: string, direction: 'asc' | 'desc' }`. +- **Search query and results:** `useState` for query string, `useMemo` for filtered results using fuse.js. +- **Login complete:** `useState` boolean. Once login animation finishes, the login component unmounts and the PMR interface mounts. + +### CSS Strategy + +- Tailwind CSS for utilities, consistent with the existing project setup +- CSS custom properties for the PMR-specific color tokens (NHS blue, traffic light colors, surface colors) defined in `index.css` under a `.pmr-theme` class +- No dark mode implementation — this design is light-mode only, which simplifies the CSS significantly +- Tables use native `` elements with Tailwind utilities for borders, padding, and alternating row colors (`even:bg-zinc-50`) +- Sidebar uses `position: fixed` with a defined width, main content uses `margin-left` to offset +- Patient banner uses `position: sticky` with dynamic height based on scroll state +- Bottom nav (mobile) uses `position: fixed` with `bottom: 0` and safe area insets via `env(safe-area-inset-bottom)` + +### Login Animation Implementation + +The login sequence is implemented as a separate component (`LoginScreen.tsx`) that runs before the PMR interface: + +1. Component mounts with dark blue-gray background +2. Login card fades in (Framer Motion, 200ms) +3. Username typing: `setInterval` adds one character per 30ms to a state string +4. Password dots: `setInterval` adds one dot per 20ms +5. Button press: state change triggers visual pressed state, then 200ms delay +6. `onComplete` callback fires, parent component swaps to `PMRInterface.tsx` + +The typing animation respects `prefers-reduced-motion` — with reduced motion, the full username appears instantly and the login completes in ~500ms total. + +### Search Implementation + +- **Index building:** On mount, a fuse.js index is built from all content data: consultation titles/bullets, medication names, problem descriptions, investigation names, document titles. +- **Search options:** `{ keys: ['title', 'description', 'bullets', 'name'], threshold: 0.3, includeScore: true }` +- **Results grouping:** Search results are grouped by section (Consultations, Medications, etc.) and displayed in a dropdown beneath the search input. +- **Navigation:** Clicking a result updates the active sidebar view and scrolls to / expands the matching item. + +### Data Architecture + +All PMR content is defined as typed data arrays in dedicated files: + +``` +src/data/ + consultations.ts — ExperienceEntry[] mapped to consultation format + medications.ts — Skill[] mapped to medication format + problems.ts — Achievement[] with status and coded entries + investigations.ts — Project[] with results and methodology + documents.ts — Education[] with document metadata +``` + +Each data file exports typed arrays that the corresponding view components consume. This separation keeps data out of component files and makes it easy to update CV content. + +### Performance Considerations + +- **View switching:** Only the active view renders. Inactive views are unmounted (not hidden). This keeps DOM weight low. +- **Table rendering:** For the Medications table (~18 rows), no virtualization is needed. If the data set grew significantly, `react-window` could be added. +- **Search index:** fuse.js index is built once on mount and memoized. Total content is small enough (~50 items) that search is effectively instant. +- **Login animation:** Uses `setInterval` for typing, cleaned up in the `useEffect` return. No memory leaks. +- **Scroll observer:** A single `IntersectionObserver` instance handles the patient banner condensation trigger. Created once, disconnected on unmount. + +--- + +## Accessibility + +### Semantic HTML + +- Sidebar: `` with `` and `` items. Active item uses `aria-current="page"`. +- Patient banner: `` containing patient demographics. +- Main content area: `` element with `aria-label` matching the current view name ("Summary", "Consultations", etc.). +- Tables: Proper ``, ``, ``, ``, ``, `` markup. Column headers use `scope="col"`. This is critical — medication and problem tables must be navigable by screen readers as proper data tables. +- Consultation entries: `` elements with `` for expand/collapse, `aria-expanded` attribute. + +### Keyboard Navigation + +- `Tab` moves between: sidebar items, patient banner buttons, main content interactive elements +- `ArrowUp` / `ArrowDown` within the sidebar moves between navigation items (roving tabindex) +- `Enter` / `Space` on sidebar items activates that view +- `Enter` / `Space` on consultation entries toggles expand/collapse +- `Alt+1` through `Alt+7` directly activates sidebar items (matches clinical system keyboard shortcuts) +- `Escape` closes expanded items, context menus, and search dropdown +- Search input is focusable with `/` key (common pattern) + +### Screen Reader Experience + +1. On page load, after login animation, the screen reader announces: "Patient Record for Charlwood, Andrew. Summary view." +2. The clinical alert is announced immediately via `role="alert"`: "Alert: This patient has identified fourteen point six million pounds in prescribing efficiency savings across Norfolk and Waveney ICS." +3. Sidebar navigation items are announced with their label and active state. +4. Tables are announced with column headers — e.g., "Medications table. Row 1: Drug Name: Python. Dose: 90 percent. Frequency: Daily. Start: 2017. Status: Active." +5. Expandable items announce their expanded/collapsed state. +6. Breadcrumb uses `` with `` and `aria-current="page"` on the last item. + +### Alert Accessibility + +- Clinical alert uses `role="alert"` and `aria-live="assertive"` — screen readers announce it immediately on appearance. +- The "Acknowledge" button is clearly labeled: `aria-label="Acknowledge clinical alert"`. +- After acknowledgment, the removal is smooth (no jarring DOM change for screen readers — the element simply removes itself from the accessibility tree). + +### Focus Management + +- After login completes, focus moves to the first sidebar item (Summary). +- After navigating to a new view, focus moves to the first heading in the main content area. +- After expanding a consultation, focus moves to the "HISTORY" heading within the expanded content. +- After closing a context menu, focus returns to the element that triggered it. +- After acknowledging an alert, focus moves to the main content area's first interactive element. + +### Color and Contrast + +- All text meets WCAG 2.1 AA contrast requirements against its background. +- Traffic light indicators are never the sole communicator of state — they always accompany text labels ("Active", "Resolved", "In Progress"). +- NHS blue (`#005EB8`) on white provides a contrast ratio of ~7.3:1 (exceeds AA). +- The amber alert text (`#92400E`) on amber background (`#FEF3C7`) provides a contrast ratio of ~5.8:1 (meets AA). + +### Motion Preferences + +When `prefers-reduced-motion: reduce` is active: +- Login typing animation completes instantly (full text appears at once) +- Clinical alert appears without slide animation (instant render) +- Consultation expand/collapse is instant (no height animation) +- Patient banner condensation is instant (no smooth transition) +- All hover background-color changes remain (they are not motion) + +--- + +## What Makes This Special + +**Absolute thematic fidelity.** This isn't a clinical "theme" loosely applied — it's a genuine PMR interface reimagined as a CV. The patient banner, the consultation journal format, the medications table, the coded entries, the traffic lights, the clinical alert, the login screen — every element is drawn from real NHS clinical software. The fidelity is what makes the concept work. A clinician visiting this site will immediately recognize the interface, and that recognition creates delight. + +**The consultation format is actually better for career content.** The History / Examination / Plan structure maps perfectly to Context / Analysis / Outcome — arguably a better format for presenting career achievements than traditional bullet lists. "History" gives the reader context for why the role existed. "Examination" shows what Andy analyzed and built. "Plan" shows what was delivered and measured. This is how clinical thinking works, and it's also how impact-driven career narratives should work. + +**The clinical alert is a guaranteed attention-grabber.** Framing "£14.6M in efficiency savings" as a system-generated clinical alert — with an amber background, a warning icon, and a required "Acknowledge" action — gives the number institutional weight. It doesn't feel like a boast; it feels like a data point flagged by a system. The user has to consciously dismiss it, which means they've read it, processed it, and engaged with it. No other portfolio design achieves this level of engagement with a single metric. + +**The medications-as-skills mapping is clever and navigable.** Presenting skills as a medications list with dosage, frequency, and status columns provides more information than a typical skills section. "Python | 90% | Daily | 2017 | Active" tells the reader: proficiency level, current usage intensity, how long Andy has used it, and whether it's still actively in use. The "prescribing history" expansion shows skill progression over time. This is richer data than a grid of progress bars. + +**Clinicians get the joke. Recruiters get the data.** The design works on two levels simultaneously. Healthcare professionals will recognize the PMR interface and appreciate the creativity (and the accuracy of the reproduction). Non-clinical recruiters won't know they're looking at a PMR clone, but they'll find the interface navigable, structured, and information-dense — because clinical systems are designed for efficient information retrieval under time pressure. Both audiences win. + +**The login screen is the most immersive transition.** Every NHS worker has typed their credentials into a dark-blue login screen at 8am. This transition puts them right there. It's a shared institutional experience, and it establishes the metaphor instantly: you are opening a record. The "patient" happens to be a career. By the time the PMR interface materializes, the user is already thinking in clinical-system mode. + +**Problem-oriented framing turns achievements into resolutions.** The Problems view reframes career achievements as "problems" that Andy identified and resolved. "Manual prescribing analysis inefficiency" is a problem statement. "Built Python switching algorithm, 14,000 patients identified, £2.6M annual savings" is the resolution. This narrative structure — problem followed by resolution followed by measurable outcome — is more compelling than a list of accomplishments because it shows the thinking that preceded the action. It reveals process, not just results. diff --git a/skills/bencium-innovative-ux-designer/ACCESSIBILITY.md b/skills/bencium-innovative-ux-designer/ACCESSIBILITY.md new file mode 100644 index 0000000..d514f4e --- /dev/null +++ b/skills/bencium-innovative-ux-designer/ACCESSIBILITY.md @@ -0,0 +1,111 @@ +# Accessibility Essentials + +Accessibility enables creativity - it's a foundation, not a limitation. WCAG 2.1 AA compliance. + +## Core Principles (POUR) + +- **Perceivable**: Content must be perceivable (alt text, contrast, captions) +- **Operable**: UI must be keyboard/touch accessible +- **Understandable**: Clear, predictable behavior +- **Robust**: Works with assistive technologies + +## Contrast Requirements + +| Element | Minimum Ratio | +|---------|---------------| +| Normal text | 4.5:1 | +| Large text (18pt+) | 3:1 | +| UI components | 3:1 | + +**Tools**: Chrome DevTools Accessibility tab, WebAIM Contrast Checker + +## Keyboard Navigation + +```tsx +// All interactive elements need focus states + + Accessible + + +// Custom elements need tabindex and key handlers + (e.key === 'Enter' || e.key === ' ') && handleClick()} +> + Custom Button + +``` + +**Essentials:** +- Tab through entire interface +- Enter/Space activates elements +- Escape closes modals +- Visible focus indicators always + +## Essential ARIA + +```tsx +// Buttons without text + + +// Expandable elements +Menu + +// Live regions for dynamic content +{statusMessage} +{errorMessage} + +// Form errors + +{hasError && Error text} +``` + +## Semantic HTML + +```tsx +// Use semantic elements, not divs +... +... + + +// Heading hierarchy (never skip levels) +Page Title + Section + Subsection +``` + +## Touch Targets + +- Minimum **44x44px** for all interactive elements +- Adequate spacing between targets +- `touch-manipulation` CSS for responsive touch + +## Screen Reader Content + +```tsx +// Hidden but announced +Additional context + +// Skip link + + Skip to main content + +``` + +## Quick Checklist + +- [ ] Keyboard: Can tab through everything +- [ ] Focus: Visible focus indicators +- [ ] Contrast: 4.5:1 for text +- [ ] Alt text: All images have appropriate alt +- [ ] Headings: Logical h1-h6 hierarchy +- [ ] Forms: Labels associated with inputs +- [ ] Errors: Announced to screen readers +- [ ] Touch: 44px minimum targets + +## Resources + +- [WCAG 2.1 Quick Reference](https://www.w3.org/WAI/WCAG21/quickref/) +- [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/) +- [ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/) diff --git a/skills/bencium-innovative-ux-designer/DESIGN-SYSTEM-TEMPLATE.md b/skills/bencium-innovative-ux-designer/DESIGN-SYSTEM-TEMPLATE.md new file mode 100644 index 0000000..e968748 --- /dev/null +++ b/skills/bencium-innovative-ux-designer/DESIGN-SYSTEM-TEMPLATE.md @@ -0,0 +1,577 @@ +# Design System Template + +Meta-framework for understanding what's fixed, project-specific, and adaptable in your design system. + +## Purpose + +This template helps you distinguish between: +- **Fixed Elements**: Universal rules that never change +- **Project-Specific Elements**: Filled in for each project based on brand +- **Adaptable Elements**: Context-dependent implementations + +--- + +## I. FIXED ELEMENTS + +These foundations remain consistent across all projects, regardless of brand or context. + +### 1. Spacing Scale + +**Fixed System:** +``` +4px, 8px, 12px, 16px, 24px, 32px, 48px, 64px, 96px +``` + +**Usage:** +- Margins, padding, gaps between elements +- Mathematical relationships ensure visual harmony +- Use multipliers of base unit (4px) + +**Why Fixed:** +Consistent spacing creates visual rhythm regardless of brand personality. + +### 2. Grid System + +**Fixed Structure:** +- **12-column grid** for most layouts (divisible by 2, 3, 4, 6) +- **16-column grid** for data-heavy interfaces +- **Gutters**: 16px (mobile), 24px (tablet), 32px (desktop) + +**Why Fixed:** +Grid provides structural order. Brand personality shows through color, typography, content—not grid structure. + +### 3. Accessibility Standards + +**Fixed Requirements:** +- **WCAG 2.1 AA** compliance minimum +- **Contrast**: 4.5:1 for normal text, 3:1 for large text +- **Touch targets**: Minimum 44×44px +- **Keyboard navigation**: All interactive elements accessible +- **Screen reader**: Semantic HTML, ARIA labels where needed + +**Why Fixed:** +Accessibility is not negotiable. It's a baseline requirement for ethical, legal, and usable products. + +### 4. Typography Hierarchy Logic + +**Fixed Structure:** +- **Mathematical scaling**: 1.25x (major third) or 1.333x (perfect fourth) +- **Hierarchy levels**: Display → H1 → H2 → H3 → Body → Small → Caption +- **Line height**: 1.5x for body text, 1.2-1.3x for headlines +- **Line length**: 45-75 characters optimal + +**Why Fixed:** +Mathematical relationships create predictable, harmonious hierarchy. Specific fonts change, but the logic doesn't. + +### 5. Component Architecture + +**Fixed Patterns:** +- **Button states**: Default, Hover, Active, Focus, Disabled +- **Form structure**: Label above input, error below, helper text optional +- **Modal pattern**: Overlay + centered content + close mechanism +- **Card structure**: Container → Header → Body → Footer (optional) + +**Why Fixed:** +Users expect consistent component behavior. Architecture is fixed; appearance is project-specific. + +### 6. Animation Timing Framework + +**Fixed Physics Profiles:** +- **Lightweight** (icons, chips): 150ms +- **Standard** (cards, panels): 300ms +- **Weighty** (modals, pages): 500ms + +**Fixed Easing:** +- **Ease-out**: Entrances (fast start, slow end) +- **Ease-in**: Exits (slow start, fast end) +- **Ease-in-out**: Transitions (smooth both ends) + +**Why Fixed:** +Natural physics feel consistent across brands. Duration and easing create that feeling. + +--- + +## II. PROJECT-SPECIFIC ELEMENTS + +Fill in these for each project based on brand personality and purpose. + +### 1. Brand Color System + +**Template Structure:** + +``` +NEUTRALS (4-5 colors): +- Background lightest: _______ (e.g., slate-50 or warm-white) +- Surface: _______ (e.g., slate-100) +- Border/divider: _______ (e.g., slate-300) +- Text secondary: _______ (e.g., slate-600) +- Text primary: _______ (e.g., slate-900) + +ACCENTS (1-3 colors): +- Primary (main CTA): _______ (e.g., teal-500) +- Secondary (alternative action): _______ (optional) +- Status colors: + - Success: _______ (green-ish) + - Warning: _______ (amber-ish) + - Error: _______ (red-ish) + - Info: _______ (blue-ish) +``` + +**Questions to Answer:** +- What emotion should the brand evoke? (Trust, excitement, calm, urgency) +- Warm or cool neutrals? +- Conservative or bold accents? + +**Examples:** + +**Project A: Fintech App** +``` +Neutrals: Cool greys (slate-50 → slate-900) +Primary: Deep blue (#0A2463) – trust, professionalism +Success: Muted green (#10B981) +Why: Financial products need trust, not playfulness +``` + +**Project B: Creative Community** +``` +Neutrals: Warm greys with beige undertones +Primary: Coral (#FF6B6B) – energy, creativity +Success: Teal (#06D6A0) – fresh, unexpected +Why: Creative spaces should feel inviting, not corporate +``` + +**Project C: Healthcare Platform** +``` +Neutrals: Pure greys (minimal color temperature) +Primary: Soft blue (#4A90E2) – calm, clinical +Success: Medical green (#38A169) +Why: Healthcare needs clarity and calm, not distraction +``` + +### 2. Typography Pairing + +**Template:** + +``` +HEADLINE FONT: _______ +- Weight: _______ (e.g., Bold 700) +- Use case: H1, H2, display text +- Personality: _______ (geometric/humanist/serif/etc.) + +BODY FONT: _______ +- Weight: _______ (e.g., Regular 400, Medium 500) +- Use case: Paragraphs, UI text +- Personality: _______ (neutral/readable/efficient) + +OPTIONAL ACCENT FONT: _______ +- Weight: _______ +- Use case: _______ (special headlines, callouts) +``` + +**Pairing Logic:** +- Serif + Sans-serif (classic, editorial) +- Geometric + Humanist (modern + warm) +- Display + System (distinctive + efficient) + +**Examples:** + +**Project A: Editorial Platform** +``` +Headline: Playfair Display (Serif, Bold 700) +Body: Inter (Sans-serif, Regular 400) +Why: Serif headlines = trustworthy, editorial feel +``` + +**Project B: Tech Startup** +``` +Headline: DM Sans (Sans-serif, Bold 700) +Body: DM Sans (Regular 400, Medium 500) +Why: Single-font system = modern, efficient, cohesive +``` + +**Project C: Luxury Brand** +``` +Headline: Cormorant Garamond (Serif, Light 300) +Body: Lato (Sans-serif, Regular 400) +Why: Elegant serif + readable sans = sophisticated +``` + +### 3. Tone of Voice + +**Template:** + +``` +BRAND PERSONALITY: +- Formal ↔ Casual: _______ (1-10 scale) +- Professional ↔ Friendly: _______ (1-10 scale) +- Serious ↔ Playful: _______ (1-10 scale) +- Authoritative ↔ Conversational: _______ (1-10 scale) + +MICROCOPY EXAMPLES: +- Button label (submit form): _______ +- Error message (invalid email): _______ +- Success message (saved): _______ +- Empty state: _______ + +ANIMATION PERSONALITY: +- Speed: _______ (quick/moderate/slow) +- Feel: _______ (precise/smooth/bouncy) +``` + +**Examples:** + +**Project A: Banking App** +``` +Personality: Formal (8), Professional (9), Serious (8) +Button: "Submit Application" +Error: "Email address format is invalid" +Success: "Application submitted successfully" +Animation: Quick (precise, efficient, no-nonsense) +``` + +**Project B: Social App** +``` +Personality: Casual (8), Friendly (9), Playful (7) +Button: "Let's go!" +Error: "Hmm, that email doesn't look right" +Success: "Nice! You're all set 🎉" +Animation: Moderate (smooth, friendly bounce) +``` + +### 4. Animation Speed & Feel + +**Template:** + +``` +SPEED PREFERENCE: +- UI interactions: _______ (100-150ms / 150-200ms / 200-300ms) +- State changes: _______ (200ms / 300ms / 400ms) +- Page transitions: _______ (300ms / 500ms / 700ms) + +ANIMATION STYLE: +- Easing preference: _______ (sharp / standard / bouncy) +- Movement type: _______ (minimal / smooth / expressive) +``` + +**Examples:** + +**Project A: Trading Platform** +``` +Speed: Fast (100ms UI, 200ms states, 300ms pages) +Style: Sharp easing, minimal movement +Why: Traders need speed, not distraction +``` + +**Project B: Wellness App** +``` +Speed: Slow (200ms UI, 400ms states, 500ms pages) +Style: Smooth easing, gentle movement +Why: Calm, relaxing experience matches brand +``` + +--- + +## III. ADAPTABLE ELEMENTS + +Context-dependent implementations that vary based on use case. + +### 1. Component Variations + +**Button Variants:** +- **Primary**: Full background color (high emphasis) +- **Secondary**: Outline only (medium emphasis) +- **Tertiary**: Text only (low emphasis) +- **Destructive**: Red-ish (danger actions) +- **Ghost**: Minimal (navigation, toolbars) + +**Adaptation Rules:** +- Primary: Main CTA, one per screen section +- Secondary: Alternative actions +- Tertiary: Less important actions, multiple allowed +- Use brand colors, but hierarchy logic is fixed + +### 2. Responsive Breakpoints + +**Fixed Ranges:** +- XS: 0-479px (small phones) +- SM: 480-767px (large phones) +- MD: 768-1023px (tablets) +- LG: 1024-1439px (laptops) +- XL: 1440px+ (desktop) + +**Adaptable Implementations:** + +**Simple Content Site:** +``` +XS-SM: Single column +MD: 2 columns +LG-XL: 3 columns max +Why: Content-focused, don't overwhelm +``` + +**Dashboard/Data App:** +``` +XS: Collapsed, cards stack +SM: Simplified sidebar +MD: Full sidebar + main content +LG-XL: Sidebar + main + right panel +Why: Data apps need more screen real estate +``` + +### 3. Dark Mode Palette + +**Adaptation Strategy:** + +Not a simple inversion. Dark mode needs adjusted contrast: + +**Light Mode:** +``` +Background: #FFFFFF (white) +Text: #0F172A (slate-900) → 21:1 contrast +``` + +**Dark Mode (Adapted):** +``` +Background: #0F172A (slate-900) +Text: #E2E8F0 (slate-200) → 15.8:1 contrast (still AA, but softer) +``` + +**Why Adapt:** +Pure white on pure black is too harsh. Dark mode needs slightly lower contrast for eye comfort. + +### 4. Loading States + +**Context-Dependent:** + +**Fast operations (<500ms):** +- No loading indicator (feels instant) + +**Medium operations (500ms-2s):** +- Spinner or skeleton screen + +**Long operations (>2s):** +- Progress bar with percentage +- Or: Skeleton + estimated time + +**Interactive Operations:** +- Button shows spinner inside (don't disable, show state) + +### 5. Error Handling Strategy + +**Context-Dependent:** + +**Form Errors:** +``` +Validate: On blur (after user leaves field) +Display: Inline below field +Recovery: Clear error on fix +``` + +**API Errors:** +``` +Transient (network): Show retry button +Permanent (404): Show helpful message + next steps +Critical (500): Contact support option +``` + +**Data Errors:** +``` +Missing: Show empty state with action +Corrupt: Show error boundary with reload +Invalid: Highlight + explain what's wrong +``` + +--- + +## DECISION TREE + +When implementing a feature, ask: + +### Is this... + +**FIXED?** +- Does it affect structure, accessibility, or universal UX? +- Examples: Spacing scale, grid, contrast ratios, component architecture +- **Action**: Use the fixed system, no variation + +**PROJECT-SPECIFIC?** +- Does it express brand personality or purpose? +- Examples: Colors, typography, tone of voice, animation feel +- **Action**: Fill in the template for this project + +**ADAPTABLE?** +- Does it depend on context, content, or use case? +- Examples: Component variants, responsive behavior, error handling +- **Action**: Choose appropriate variation based on context + +--- + +## EXAMPLE: Implementing a "Submit" Button + +### Fixed Elements (Always the same): +- Touch target: 44px minimum height +- Padding: 16px horizontal (from spacing scale) +- States: Default, Hover, Active, Focus, Disabled +- Animation: 150ms ease-out (lightweight profile) + +### Project-Specific (Filled per project): +- **Project A (Bank)**: Dark blue background, white text, "Submit Application" +- **Project B (Social)**: Coral background, white text, "Let's Go!" +- **Project C (Healthcare)**: Soft blue background, white text, "Continue" + +### Adaptable (Context-dependent): +- **Form context**: Primary button (full color) +- **Toolbar context**: Ghost button (text only) +- **Danger context**: Destructive variant (red-ish) + +--- + +## VALIDATION CHECKLIST + +Before finalizing a design, check: + +### Fixed Elements +- [ ] Uses spacing scale (4/8/12/16/24/32/48/64/96px) +- [ ] Follows grid system (12 or 16 columns) +- [ ] Meets WCAG AA contrast (4.5:1 normal, 3:1 large) +- [ ] Touch targets ≥ 44px +- [ ] Typography follows mathematical scale +- [ ] Components follow standard architecture + +### Project-Specific Elements +- [ ] Brand colors filled in and intentional +- [ ] Typography pairing chosen and justified +- [ ] Tone of voice defined and consistent +- [ ] Animation speed matches brand personality + +### Adaptable Elements +- [ ] Component variants appropriate for context +- [ ] Responsive behavior fits content type +- [ ] Loading states match operation duration +- [ ] Error handling fits error type + +--- + +## PROJECT KICKOFF TEMPLATE + +Use this to start a new project: + +``` +PROJECT NAME: _______________________ +PURPOSE: ____________________________ + +BRAND PERSONALITY: +- Primary emotion: _______ +- Warm or cool: _______ +- Formal or casual: _______ +- Conservative or bold: _______ + +COLORS (fill the template): +- Neutral base: _______ +- Primary accent: _______ +- Status colors: _______ / _______ / _______ + +TYPOGRAPHY (fill the template): +- Headline font: _______ +- Body font: _______ +- Pairing rationale: _______ + +TONE: +- Button labels style: _______ +- Error message style: _______ +- Success message style: _______ + +ANIMATION: +- Speed preference: _______ (fast/moderate/slow) +- Feel preference: _______ (sharp/smooth/bouncy) + +TARGET DEVICES: +- Primary: _______ (mobile/desktop/both) +- Secondary: _______ +``` + +--- + +## MAINTAINING CONSISTENCY + +### Documentation +- Keep this template updated as system evolves +- Document WHY choices were made, not just WHAT + +### Communication +- Share with designers: "Here's what varies vs. what's fixed" +- Share with developers: "Here are the design tokens" + +### Tooling +- Use CSS variables for project-specific values +- Use Tailwind config for spacing scale +- Use design tokens in Figma/Storybook + +### Reviews +- Audit: Does new work follow fixed elements? +- Validate: Are project-specific elements intentional? +- Question: Are adaptations justified by context? + +--- + +## EXAMPLES OF COMPLETE SYSTEMS + +### System A: B2B SaaS (Conservative) + +**Fixed**: Standard spacing, 12-col grid, WCAG AA, major third type scale +**Project-Specific**: +- Colors: Cool greys + corporate blue +- Typography: DM Sans (headlines + body) +- Tone: Professional, formal +- Animation: Quick, precise (150ms) +**Adaptable**: +- Dashboard gets multi-panel layout +- Forms are extensive (use progressive disclosure) +- Errors show detailed technical info + +### System B: Consumer Social App (Playful) + +**Fixed**: Same spacing/grid/accessibility/type logic +**Project-Specific**: +- Colors: Warm greys + vibrant coral +- Typography: Poppins (headlines) + Inter (body) +- Tone: Casual, friendly, playful +- Animation: Moderate, bouncy (200ms) +**Adaptable**: +- Mobile-first (most users on phones) +- Forms are minimal (progressive profiling) +- Errors are friendly, not technical + +### System C: Healthcare Platform (Clinical) + +**Fixed**: Same foundational structure +**Project-Specific**: +- Colors: Pure greys + medical blue +- Typography: System fonts (SF Pro / Segoe) +- Tone: Clear, authoritative, calm +- Animation: Slow, smooth (300ms) +**Adaptable**: +- Desktop-first (clinical use at workstations) +- Forms are complex (HIPAA compliance) +- Errors are precise with next steps + +--- + +## KEY TAKEAWAY + +**The system flexibility framework lets you:** +- Maintain consistency (fixed elements) +- Express brand personality (project-specific) +- Adapt to context (adaptable elements) + +**Without this framework:** +- Designers reinvent spacing every project +- Components feel inconsistent across products +- Brand personality overrides accessibility +- Context-blind implementations feel wrong + +**With this framework:** +- Speed: Start from proven foundations +- Consistency: Fixed elements guarantee it +- Flexibility: Express unique brand identity +- Context: Adapt without breaking system diff --git a/skills/bencium-innovative-ux-designer/MOTION-SPEC.md b/skills/bencium-innovative-ux-designer/MOTION-SPEC.md new file mode 100644 index 0000000..e37e363 --- /dev/null +++ b/skills/bencium-innovative-ux-designer/MOTION-SPEC.md @@ -0,0 +1,72 @@ +# Motion Specification + +Motion should surprise and delight while serving function. Animation is a creative tool. + +## Easing Curves + +| Easing | CSS | Use For | +|--------|-----|---------| +| **Ease-out** | `cubic-bezier(0.0, 0.0, 0.2, 1)` | Entrances, appearing | +| **Ease-in** | `cubic-bezier(0.4, 0.0, 1, 1)` | Exits, disappearing | +| **Ease-in-out** | `cubic-bezier(0.4, 0.0, 0.2, 1)` | State changes, transforms | +| **Spring** | `cubic-bezier(0.68, -0.55, 0.265, 1.55)` | Playful, attention-grabbing | +| **Linear** | `linear` | Spinners, continuous loops | + +## Duration by Element Weight + +| Weight | Duration | Examples | +|--------|----------|----------| +| **Lightweight** | 150ms | Icons, badges, chips | +| **Standard** | 300ms | Cards, panels, list items | +| **Weighty** | 500ms | Modals, page transitions | + +## Duration by Interaction + +| Interaction | Duration | +|-------------|----------| +| Button press | 100ms | +| Hover state | 150ms | +| Tooltip appear | 200ms | +| Tab switch | 250ms | +| Modal open | 300ms | +| Page transition | 400ms | + +## Common Patterns + +```tsx +// Hover transition (CSS) + + +// Fade + slide (Framer Motion) + + +// Stagger children + + + +``` + +## Performance Rules + +- Only animate `transform` and `opacity` (GPU-accelerated) +- Avoid animating `width`, `height`, `margin`, `padding` +- Keep durations under 500ms for UI interactions +- Respect `prefers-reduced-motion`: + +```css +@media (prefers-reduced-motion: reduce) { + *, *::before, *::after { + animation-duration: 0.01ms !important; + transition-duration: 0.01ms !important; + } +} +``` + +## Resources + +- [Framer Motion](https://www.framer.com/motion/) +- [CSS Easing Functions](https://easings.net/) diff --git a/skills/bencium-innovative-ux-designer/RESPONSIVE-DESIGN.md b/skills/bencium-innovative-ux-designer/RESPONSIVE-DESIGN.md new file mode 100644 index 0000000..e1a33eb --- /dev/null +++ b/skills/bencium-innovative-ux-designer/RESPONSIVE-DESIGN.md @@ -0,0 +1,90 @@ +# Responsive Design Essentials + +Mobile-first approach: start with mobile, progressively enhance for larger screens. + +## Breakpoints + +| Range | Pixels | Devices | Strategy | +|-------|--------|---------|----------| +| **XS** | 0-479px | Small phones | Single column, stacked nav, 44px touch targets | +| **SM** | 480-767px | Large phones | Single column, bottom nav, simplified UI | +| **MD** | 768-1023px | Tablets | 2 columns possible, sidebar nav | +| **LG** | 1024-1439px | Laptops | Multi-column, full nav, desktop UI | +| **XL** | 1440px+ | Desktop | Max-width containers, multi-panel layouts | + +## Tailwind Responsive + +```tsx +// Mobile-first: base styles, then scale up + + +// Responsive grid + + +// Responsive typography + + +// Show/hide by breakpoint +Mobile only +Desktop only +``` + +## Fluid Typography + +```css +h1 { font-size: clamp(2rem, 5vw, 4rem); } +p { font-size: clamp(1rem, 2.5vw, 1.25rem); } +``` + +## Touch Targets + +- Minimum **44x44px** for all interactive elements +- Use `touch-manipulation` to prevent 300ms tap delay +- Adequate spacing between targets + +```tsx + +``` + +## Mobile Simplification + +| Desktop | Mobile | +|---------|--------| +| Full nav bar | Hamburger menu | +| Side-by-side fields | Stacked fields | +| Multi-column grid | Single column | +| Inline buttons | Fixed bottom bar | +| Data table | Collapsed cards | +| Visible sidebar | Hidden/collapsible | + +## Images + +```tsx +// Responsive images + + +// Next.js + +``` + +## Testing + +Test at these widths: +- 375px (iPhone SE) +- 390px (iPhone 14) +- 768px (iPad) +- 1024px (iPad Pro) +- 1280px+ (Desktop) + +## Resources + +- [Tailwind Responsive](https://tailwindcss.com/docs/responsive-design) diff --git a/skills/bencium-innovative-ux-designer/SKILL.md b/skills/bencium-innovative-ux-designer/SKILL.md new file mode 100644 index 0000000..9d2a791 --- /dev/null +++ b/skills/bencium-innovative-ux-designer/SKILL.md @@ -0,0 +1,718 @@ +--- +name: bencium-innovative-ux-designer +description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics. +metadata: + version: 2.0.0 +--- + +# Innovative UX Designer + +Create distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices. Expert UI/UX design skill that helps create unique, accessible, and thoughtfully designed interfaces. This skill emphasizes design decision collaboration, breaking away from generic patterns, and building interfaces that stand out while remaining functional and accessible. + +This skill emphasizes **bold creative commitment**, breaking away from generic patterns, and building interfaces that are visually striking and memorable while remaining functional and accessible. + +## Core Philosophy + +**CRITICAL: Design Thinking Protocol** + +Before coding, **ASK to understand context**, then **COMMIT BOLDLY** to a distinctive direction: + +### Questions to Ask First +1. **Purpose**: What problem does this interface solve? Who uses it? +2. **Tone**: What aesthetic extreme fits? (see Tone Options below) +3. **Constraints**: Technical requirements (framework, performance, accessibility)? +4. **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember? + +### Tone Options (Pick an Extreme) +Choose a clear aesthetic direction and execute with precision: +- **Brutally minimal** - stripped to essence, bold typography, vast whitespace +- **Maximalist chaos** - layered, dense, visually rich, controlled disorder +- **Retro-futuristic** - vintage meets sci-fi, nostalgic tech aesthetics +- **Organic/natural** - soft edges, earthy colors, nature-inspired textures +- **Luxury/refined** - elegant spacing, premium typography, subtle details +- **Playful/toy-like** - bright colors, rounded shapes, delightful interactions +- **Editorial/magazine** - strong typography hierarchy, asymmetric layouts +- **Brutalist/raw** - exposed structure, harsh contrasts, intentionally rough +- **Art deco/geometric** - bold patterns, metallic accents, symmetric elegance +- **Soft/pastel** - gentle gradients, muted tones, calming atmosphere +- **Industrial/utilitarian** - functional, no-nonsense, mechanical precision + +### After Getting Context +- **Commit fully** to the chosen direction - no half measures +- Present 2-3 alternative approaches with trade-offs +- Then implement with precision: production-grade, visually striking, memorable + +## Foundational Design Principles + +### Stand Out From Generic Patterns + +**NEVER Use These AI-Generated Aesthetics:** +- **Fonts**: Inter, Roboto, Arial, system fonts as primary choice, Space Grotesk (overused by AI) +- **Colors**: Generic SaaS blue (#3B82F6), purple gradients on white backgrounds +- **Patterns**: Cookie-cutter layouts, predictable component arrangements +- **Effects**: Glass morphism, Apple design mimicry, liquid/blob backgrounds +- **Overall**: Anything that looks "Claude-generated" or machine-made + +**Instead, Create Atmosphere:** +- Suggest photography, patterns, textures over flat solid colors +- Apply gradient meshes, noise textures, geometric patterns +- Use layered transparencies, dramatic shadows, decorative borders +- Consider custom cursors, grain overlays, contextual effects +- Think beyond typical patterns - you can step off the written path + +**Draw Inspiration From:** +- Modern landing pages (Perplexity, Comet Browser, Dia Browser) +- Framer templates and their innovative approaches +- Leading brand design studios +- Historical design movements (Bauhaus, Otl Aicher, Braun) - but as inspiration, not imitation +- Beautiful background animations (CSS, SVG) - slow, looping, subtle + +**Visual Interest Strategies:** +- Unique color pairs that aren't typical +- Animation effects that feel fresh +- Background patterns that add depth without distraction +- Typography combinations that create contrast +- Visual assets that tell a story + +### Core Design Philosophy + +1. **Simplicity Through Reduction** + - Identify the essential purpose and eliminate distractions + - Begin with complexity, then deliberately remove until reaching the simplest effective solution + - Every element must justify its existence + +2. **Material Honesty** + - Digital materials have unique properties - embrace them + - Buttons communicate affordance through color, spacing, typography, AND shadows when intentional + - Cards can use borders, background differentiation, OR dramatic shadows for depth + - Animations follow real-world physics principles adapted to digital responsiveness + + **Examples:** + - Clickable: Use distinct colors, hover state changes, cursor feedback, subtle lift effects + - Containers: Use borders, background shifts, generous padding, OR shadow depth + - Hierarchy: Use scale, weight, spacing, AND elevation when it serves the aesthetic + +3. **Functional Layering** + - Create hierarchy through typography scale, color contrast, and spatial relationships + - Layer information conceptually (primary → secondary → tertiary) + - Use shadows and gradients INTENTIONALLY when they serve the aesthetic direction + - Embrace functional depth: modals over content, dropdowns over UI + - Avoid: glass morphism, Apple mimicry (but shadows/gradients are tools, not enemies) + +4. **Obsessive Detail** + - Consider every pixel, interaction, and transition + - Excellence emerges from hundreds of small, intentional decisions + - Balance: Details should serve simplicity, not complexity + - When detail conflicts with clarity, clarity wins + +5. **Coherent Design Language** + - Every element should visually communicate its function + - Elements should feel part of a unified system + - Nothing should feel arbitrary + +6. **Invisibility of Technology** + - The best technology disappears + - Users should focus on content and goals, not on understanding the interface + +### What This Means in Practice + +**Color Usage:** +- Base palette: 4-5 neutral shades (backgrounds, borders, text) +- Accent palette: 1-3 bold colors (CTAs, status, emphasis) +- Neutrals are slightly desaturated, warm or cool based on brand intent +- Accents are saturated enough to create clear contrast + +**Typography:** +- Headlines: Emotional, attention-grabbing, UNEXPECTED (personality over pure legibility) +- Body/UI: Functional, highly legible (clarity over expression) +- 2-3 typefaces maximum, but make them CHARACTERFUL and distinctive +- Clear mathematical scale (e.g., 1.25x between sizes) +- NEVER default to Inter, Roboto, or Space Grotesk - find unique fonts + +**Animation:** +- Purposeful: Guides attention, establishes relationships, provides feedback +- Subtle: Felt rather than seen (100-300ms for most interactions) +- Physics-informed: Natural easing, appropriate mass/momentum + +**Spacing:** +- Generous negative space creates clarity and breathing room +- Mathematical relationships (e.g., 4px base, 8/16/24/32/48px scale) +- Consistent application creates visual rhythm + +### Design Decision Checklist + +Before presenting any design, verify: + +1. **Purpose**: Does every element serve a clear function? +2. **Hierarchy**: Is visual importance aligned with content importance? +3. **Consistency**: Do similar elements look and behave similarly? +4. **Accessibility**: Does it meet WCAG AA standards? (contrast, touch targets, keyboard nav) +5. **Responsiveness**: Does it work on mobile, tablet, desktop? +6. **Uniqueness**: Does this break from generic SaaS patterns? +7. **Approval**: Have I asked before implementing colors, fonts, sizes, layouts? + +**Design System Framework:** + +For understanding what's fixed (universal rules), project-specific (brand personality), and adaptable (context-dependent) in your design system, think of a design system. + +## Visual Design Standards + +### Color & Contrast + +**Color System Architecture:** + +Every interface needs two color roles: + +1. **Base/Neutral Palette (4-5 colors):** + - Backgrounds (lightest) + - Surface colors (cards, inputs) + - Borders and dividers + - Text (darkest) + - Use slightly desaturated, warm or cool greys based on brand + +2. **Accent Palette (1-3 colors):** + - Primary action (CTA buttons) + - Status indicators (success, warning, error, info) + - Focus/hover states + - Use saturated colors for clear contrast against neutrals + +**Palette Structure Example:** +``` +Neutrals: slate-50, slate-100, slate-300, slate-700, slate-900 +Accents: teal-500 (primary), amber-500 (warning), red-500 (error) +``` + +**Color Application Rules:** + +- **Backgrounds**: Lightest neutral (slate-50 or white) +- **Text**: Darkest neutral for primary text (slate-900), mid-tone for secondary (slate-600) +- **Buttons (primary)**: Accent color with white text +- **Buttons (secondary)**: Neutral with border and dark text +- **Status indicators**: Specific accent (green=success, red=error, amber=warning, blue=info) +- **Interactive states**: + - Hover: Darken by 10-15% or shift hue slightly + - Focus: Use ring/outline in accent color + - Disabled: Reduce opacity to 40-50% and remove hover effects + +**Color Relationships:** + +Choose warm or cool intentionally based on brand: +- **Warm greys** (beige/brown undertones): Organic, approachable, trustworthy +- **Cool greys** (blue undertones): Modern, tech-forward, professional + +Accent colors should have clear contrast with both: +- Light backgrounds (for buttons on white) +- Dark text (if used as backgrounds for white text) + +**Intentional Color Usage:** +- Every color must serve a purpose (hierarchy, function, status, or action) +- Avoid decorative colors that don't communicate meaning +- Maintain consistency: same color = same meaning throughout + +**Accessibility:** +- Ensure sufficient contrast for color-blind users +- Follow WCAG 2.1 AA: minimum 4.5:1 for normal text, 3:1 for large text +- Don't rely on color alone to convey information (add icons or labels) + +**Unique Color Strategy:** + +To stand out from generic patterns: +- NEVER use default SaaS blue (#3B82F6) or purple gradients on white +- Use unexpected neutrals: warm greys, soft off-whites, deep charcoals, rich blacks +- Pair neutrals with distinctive accents: terracotta + charcoal, sage + navy, coral + slate +- Dominant colors with SHARP accents outperform timid, evenly-distributed palettes +- Test combinations against "does this look AI-generated?" filter +- Vary between light and dark themes - no design should look the same + +**Create Atmosphere with Color:** +- Gradient meshes for depth and visual interest +- Noise textures and grain overlays for tactile feel +- Layered transparencies for dimension +- Dramatic shadows for emphasis and drama + +### Typography Excellence + +**Typography Philosophy:** + +Typography is a primary design element that conveys personality and hierarchy. + +**Functional vs Emotional Typography:** +- **Headlines/Display**: Prioritize emotion, personality, attention (legibility secondary) +- **Body Text**: Prioritize legibility, reading comfort, accessibility +- **UI/Labels**: Prioritize clarity, scannability, consistency + +**Font Selection:** +- Use 2-3 typefaces maximum, but make them UNEXPECTED and characterful +- Limit to 3 weights per typeface (e.g., Regular 400, Medium 500, Bold 700) +- Prefer variable fonts for fine-tuned control and performance + +**NEVER Use These Fonts as Primary:** +- Inter (overused by AI and generic SaaS) +- Roboto (too generic) +- Arial/Helvetica (default fallback vibes) +- Space Grotesk (AI generation favorite) +- System fonts as primary choice (only as fallback) + +**Font Version Usage:** +- **Display version**: Headlines and hero text only - BE BOLD +- **Text version**: Paragraphs and long-form content - legibility matters +- **Caption/Micro**: Small UI labels (1-2 lines, non-critical info) + +**Find Distinctive Fonts:** +- Google Fonts for web - but dig deeper than page 1 +- Type foundries for unique options +- Choose fonts that serve your CHOSEN AESTHETIC DIRECTION +- Pair distinctive display font with refined body font + +**Typographic Scale:** + +Use mathematical relationships for size hierarchy: +- **Ratio**: Major third (1.25x) for moderate contrast, Perfect fourth (1.333x) for dramatic +- **Base size**: 16px (1rem) for body text +- **Example scale (1.25x)**: + ``` + xs: 0.64rem (10px) + sm: 0.8rem (13px) + base: 1rem (16px) + lg: 1.25rem (20px) + xl: 1.563rem (25px) + 2xl: 1.953rem (31px) + 3xl: 2.441rem (39px) + 4xl: 3.052rem (49px) + 5xl: 3.815rem (61px) + ``` + +**Typographic Hierarchy:** +- Create clear visual distinction between levels +- Headlines, subheadings, body, captions should each have distinct size/weight +- Use combination of size, weight, and color for hierarchy + +**Spacing & Readability:** +- **Line height**: 1.5x font size for body text (e.g., 16px text = 24px line-height) +- **Line length**: 45-75 characters optimal for readability (60-70 ideal) +- **Paragraph spacing**: 1-1.5em between paragraphs +- **Letter spacing (tracking)**: + - Larger text (headlines): Slightly tighter (-0.02em to -0.05em) + - Normal text (body): Default (0) + - Small text (captions): Slightly looser (+0.01em to +0.03em) + - General rule: As size increases, reduce tracking; as size decreases, increase tracking + +**Font Pairing Logic:** + +When using multiple typefaces, create contrast through: +- **Category contrast**: Serif + Sans-serif (classic, clear distinction) +- **Weight contrast**: Light + Bold (dynamic, energetic) +- **Personality contrast**: Geometric + Humanist (modern + warm) + +Examples: +- Serif headlines + Sans body (editorial, trustworthy) +- Display headlines + System body (distinctive + efficient) +- Bold sans headlines + Light sans body (modern, clean) + +**UI Typography:** + +Specific guidance for interface elements: +- **Button text**: Semi-Bold (600), 14-16px, consistent casing (all-caps OR title case) +- **Form labels**: Regular (400), 14px, positioned above input +- **Form input text**: Regular (400), 16px minimum (prevents iOS zoom on focus) +- **Placeholder text**: Light (300) or desaturated color, same size as input +- **Error messages**: Regular (400), 12-14px, color-coded (red-ish) + +**Responsive Typography:** + +Scale type sizes across breakpoints: +```tsx +// Example with Tailwind + + Responsive Headline + + +// Or with CSS clamp (fluid) +h1 { + font-size: clamp(2rem, 5vw, 4rem); +} +``` + +Reduce sizes on mobile (20-30% smaller than desktop) +Reduce hierarchy levels on small screens (fewer distinct sizes) + +### Layout & Spatial Design + +**Compositional Balance:** +- Every screen should feel balanced +- Pay attention to visual weight and negative space +- Use generous negative space to focus attention +- Add sufficient margins and paddings for professional, spacious look + +**Grid Discipline:** +- Maintain consistent underlying grid system +- Create sense of order while allowing meaningful exceptions +- Use grid/flex wrappers with `gap` for spacing +- Prioritize wrappers over direct margins/padding on children + +**Spatial Relationships:** +- Group related elements through proximity, alignment, and shared attributes +- Use size, color, and spacing to highlight important elements +- Guide user focus through visual hierarchy + +**Attention Guidance:** +- Design interfaces that guide user attention effectively +- Avoid cluttered interfaces where elements compete +- Create clear paths through the content + +## Interaction Design + + +**Motion Specification:** + +For detailed motion specs, see MOTION-SPEC.md (easing curves, duration tables, state-specific animations, implementation patterns). + +### User Experience Patterns + +**Core UX Principles:** + +1. **Direct Manipulation** + - Users interact directly with content, not through abstract controls + - Examples: + - Drag & drop to reorder items (not up/down buttons) + - Inline editing (click to edit, not separate form) + - Sliders for ranges (not numeric input with +/-) + - Pinch/zoom gestures on mobile (not +/- buttons) + +2. **Immediate Feedback** + - Every interaction provides instantaneous visual feedback (within 100ms) + - Types of feedback: + - **Visual**: Button pressed state, hover effects, color changes + - **Haptic**: Vibration on mobile (submit, error, success) + - **Audio**: Subtle sounds for critical actions (optional, user-controlled) + - **Loading**: Skeleton screens, spinners for >300ms operations + - **Success**: Checkmarks, green highlights, toast notifications + - **Error**: Red highlights, inline error messages, shake animations + +3. **Consistent Behavior** + - Similar-looking elements behave similarly + - Examples: + - **Visual consistency**: All primary buttons have same colors, sizes, hover states + - **Behavioral consistency**: All modals close via X button, ESC key, and outside click + - **Interaction consistency**: All drag targets have same hover state and drop feedback + - **Pattern consistency**: All forms validate on blur and submit + +4. **Forgiveness** + - Make errors difficult, but recovery easy + - **Prevention strategies**: + - Disable invalid actions (grey out unavailable buttons) + - Validate inputs inline (before submission) + - Confirm destructive actions (delete, overwrite) + - Auto-save in background (drafts, progress) + - **Recovery strategies**: + - Undo/redo for all state changes + - Soft deletes (trash/archive before permanent delete) + - Clear error messages with actionable fixes + - Preserve user input on errors (don't clear forms) + +5. **Progressive Disclosure** + - Reveal details as needed rather than overwhelming users + - Levels of disclosure: + - **Summary**: Show essential info by default (card title, price, rating) + - **Details**: Expand to show more info (description, specs, reviews) + - **Advanced**: Hide complex options behind "Advanced settings" toggle + - Examples: + - Accordion: Start collapsed, expand on click + - Search filters: Show 3-5 common filters, hide rest behind "More filters" + - Settings: Basic settings visible, advanced behind "Show advanced" + +**Modern UX Patterns:** + +1. **Conversational Interfaces** + + Prioritize natural language interaction where appropriate: + + **Four types:** + - **Pure chat**: Full conversation (AI assistants, support bots) + - **Command palette**: Text-based shortcuts (Cmd+K, search everywhere) + - **Smart search**: Natural language queries (search "meetings next week" vs filtering) + - **Form alternatives**: Conversational data collection ("What's your name?" vs form fields) + + **When to use:** + - Complex searches with multiple variables + - Task guidance (wizards, onboarding) + - Contextual help + - Quick actions (command palette) + + **When NOT to use:** + - Simple forms (just use inputs) + - Precise control interfaces (design tools, dashboards) + - High-frequency repetitive tasks + +2. **Adaptive Layouts** + + Respond to user context automatically: + - **Time-based**: Dark mode at night, light during day + - **Device-based**: Simplified UI on mobile, full features on desktop + - **Connection-based**: Reduce images/video on slow connections + - **Usage-based**: Prioritize frequent actions, hide rarely-used features + + Examples: + - Auto dark/light mode based on time or system preference + - Simplified mobile navigation (hamburger menu) vs full desktop nav + - Collapsed sidebar on small screens, expanded on large + +3. **Bold Visual Expression** + + Aesthetic flexibility based on chosen direction: + - Shadows ALLOWED and encouraged when intentional (dramatic shadows, soft elevation) + - Gradients ALLOWED for depth, accents, backgrounds, and atmosphere + - NO glass morphism effects (this is the one banned technique) + - NO Apple design mimicry (find your own voice) + - Focus on typography, color, spacing, AND visual effects to create hierarchy + - Create atmosphere: gradient meshes, noise textures, grain overlays, dramatic lighting + +**Navigation:** +- Clear structure with intuitive navigation menus +- Implement breadcrumbs for deep hierarchies (more than 2 levels) +- Use standard UI patterns to reduce learning curve (hamburger menu, tab bars) +- Ensure predictable behavior (back button works, links look clickable) +- Maintain navigation context (highlight current page, preserve scroll position) + +## Styling Implementation + +### Component Library & Tools + +**Component Library:** +- Strongly prefer shadcn components (v4, pre-installed in `@/components/ui`) +- Import individually: `import { Button } from "@/components/ui/button";` +- Use over plain HTML elements (`` over ``) +- Avoid creating custom components with names that clash with shadcn + +**Styling Engine:** +- Use Tailwind utility classes exclusively +- Adhere to theme variables in `index.css` via CSS custom properties +- Map variables in `@theme` (see `tailwind.config.js`) +- Use inline styles or CSS modules only when absolutely necessary + +**Icons:** +- Use `@phosphor-icons/react` for buttons and inputs +- Example: `import { Plus } from "@phosphor-icons/react"; ` +- Use color for plain icon buttons +- Don't override default `size` or `weight` unless requested + +**Notifications:** +- Use `sonner` for toasts +- Example: `import { toast } from 'sonner'` + +**Loading States:** +- Always add loading states, spinners, placeholder animations +- Use skeletons until content renders + +### Layout Implementation + +**Spacing Strategy:** +- Use grid/flex wrappers with `gap` for spacing +- Prioritize wrappers over direct margins/padding on children +- Nest wrappers as needed for complex layouts + +**Conditional Styling:** +- Use ternary operators or clsx/classnames utilities +- Example: `className={clsx('base-class', { 'active-class': isActive })}` + +### Responsive Design + +**Fluid Layouts:** +- Use relative units (%, em, rem) instead of fixed pixels +- Implement CSS Grid and Flexbox for flexible layouts +- Design mobile-first, then scale up + +**Media Queries:** +- Use breakpoints based on content needs, not specific devices +- Test across range of devices and orientations + +**Touch Targets:** +- Minimum 44x44 pixels for interactive elements +- Provide adequate spacing between touch targets +- Consider hover states for desktop, focus states for touch/keyboard + +**Performance:** +- Optimize assets for mobile networks +- Use CSS animations over JavaScript +- Implement lazy loading for images and videos + +## Accessibility Standards + +**Core Requirements:** +- Follow WCAG 2.1 AA guidelines +- Ensure keyboard navigability for all interactive elements +- Minimum touch target size: 44×44px +- Use semantic HTML for screen reader compatibility +- Provide alternative text for images and non-text content + +**Implementation Details:** +- Use descriptive variable and function names +- Event functions: prefix with "handle" (handleClick, handleKeyDown) +- Add accessibility attributes: + - `tabindex="0"` for custom interactive elements + - `aria-label` for buttons without text + - `role` attributes when semantic HTML isn't sufficient +- Ensure logical tab order +- Provide visible focus states + +## Design Process & Testing + +### Design Workflow + +1. **Understand Context:** + - What problem are we solving? + - Who are the users and when will they use this? + - What are the success criteria? + +2. **Explore Options:** + - Present 2-3 alternative approaches + - Explain trade-offs of each option + - Ask which direction resonates + +3. **Implement Iteratively:** + - Start with structure and hierarchy + - Add visual polish progressively + - Test at each stage + +4. **Validate:** + - Use playwright MCP to test visual changes + - Check across different screen sizes + - Verify accessibility + +### Testing Checklist + +**Visual Testing:** +- Use playwright MCP when available for automated testing +- Check responsive behavior at common breakpoints +- Verify touch targets on mobile +- Test with different content lengths (short, long, edge cases) + +**Accessibility Testing:** +- Test keyboard navigation +- Verify screen reader compatibility +- Check color contrast ratios +- Ensure focus states are visible + +**Cross-Device Testing:** +- Test on actual devices, not just emulators +- Check different browsers (Chrome, Firefox, Safari) +- Verify touch interactions on mobile +- Test landscape and portrait orientations + +## Examples + +### Example 1: Designing a Button + +**Initial Question to Ask:** +``` +Before I implement this button, I have a few design questions: +1. What's the primary action you want to emphasize? +2. Do you have brand colors in mind, or should I suggest options? +3. What emotion should this button convey? (urgent, calm, playful, professional) +``` + +**After Getting Approval, Implementation:** +```tsx +import { Button } from "@/components/ui/button"; +import { ArrowRight } from "@phosphor-icons/react"; + + + Get Started + + +``` + +### Example 2: Typography Hierarchy + +**Question First:** +``` +For this content hierarchy, I'm thinking: +- Headline: Large, bold, attention-grabbing +- Subheading: Medium, regular weight +- Body: Smaller, optimized for reading + +Should we go bold and contemporary, or subtle and refined? +``` + +**Implementation After Approval:** +```tsx + + + Headline Here + + + Supporting subheading + + + Body text optimized for readability with proper line height. + + +``` + +### Example 3: Unique Color Palette Suggestion + +**Presenting Options:** +``` +I'd like to suggest three color directions that break from typical SaaS patterns: + +1. **Warm Earth Tones** + - Base: Warm grey (#E8E2DC) + - Accent: Terracotta (#C86E4B) + - For: Organic, trustworthy feel + +2. **Cool Midnight** + - Base: Deep navy (#1A2332) + - Accent: Cyan (#4ECDC4) + - For: Modern, tech-forward feel + +3. **Soft Pastels** + - Base: Soft pink (#FFE5E5) + - Accent: Sage green (#9DB5A4) + - For: Calm, approachable feel + +Which direction feels right for your brand? +``` + +## Common Patterns to Avoid + +❌ **NEVER:** +- Use Inter, Roboto, Arial, Space Grotesk as primary fonts +- Use generic SaaS blue (#3B82F6) or purple gradients on white +- Copy Apple's design language or use glass morphism +- Create cookie-cutter layouts that look AI-generated +- Skip asking about context before designing +- Converge on common choices across generations (vary everything!) +- Use animations that delay user actions +- Create cluttered interfaces where elements compete + +✅ **ALWAYS:** +- Ask about purpose, tone, constraints, differentiation FIRST +- Then commit BOLDLY to a distinctive aesthetic direction +- Use unexpected, characterful typography choices +- Create atmosphere: shadows, gradients, textures, grain (when intentional) +- Dominant colors with sharp accents (not timid, evenly-distributed palettes) +- Provide immediate feedback for interactions +- Test with real devices +- Validate accessibility (it enables creativity, not limits it) +- Remember: Claude is capable of extraordinary creative work - don't hold back! + +## Version History + +- v2.0.0 (2025-11-22): Creative liberation update - bold aesthetics, shadows/gradients allowed, Design Thinking protocol +- v1.0.0 (2025-10-18): Initial release with comprehensive UI/UX design guidance + +## References + +For additional context, see: +- **Anthropic Frontend Aesthetics Cookbook**: https://github.com/anthropics/claude-cookbooks/blob/main/coding/prompting_for_frontend_aesthetics.ipynb +- WCAG 2.1 Guidelines: https://www.w3.org/WAI/WCAG21/quickref/ +- Google Fonts: https://fonts.google.com/ +- Tailwind CSS Docs: https://tailwindcss.com/docs +- Shadcn UI Components: https://ui.shadcn.com/ + +**Progressive Disclosure Files:** +- ACCESSIBILITY.md - Accessibility essentials (WCAG AA baseline) +- MOTION-SPEC.md - Animation timing and easing +- RESPONSIVE-DESIGN.md - Mobile-first breakpoints and patterns
` elements with `` for expand/collapse, `aria-expanded` attribute. + +### Keyboard Navigation + +- `Tab` moves between: sidebar items, patient banner buttons, main content interactive elements +- `ArrowUp` / `ArrowDown` within the sidebar moves between navigation items (roving tabindex) +- `Enter` / `Space` on sidebar items activates that view +- `Enter` / `Space` on consultation entries toggles expand/collapse +- `Alt+1` through `Alt+7` directly activates sidebar items (matches clinical system keyboard shortcuts) +- `Escape` closes expanded items, context menus, and search dropdown +- Search input is focusable with `/` key (common pattern) + +### Screen Reader Experience + +1. On page load, after login animation, the screen reader announces: "Patient Record for Charlwood, Andrew. Summary view." +2. The clinical alert is announced immediately via `role="alert"`: "Alert: This patient has identified fourteen point six million pounds in prescribing efficiency savings across Norfolk and Waveney ICS." +3. Sidebar navigation items are announced with their label and active state. +4. Tables are announced with column headers — e.g., "Medications table. Row 1: Drug Name: Python. Dose: 90 percent. Frequency: Daily. Start: 2017. Status: Active." +5. Expandable items announce their expanded/collapsed state. +6. Breadcrumb uses `` with `` and `aria-current="page"` on the last item. + +### Alert Accessibility + +- Clinical alert uses `role="alert"` and `aria-live="assertive"` — screen readers announce it immediately on appearance. +- The "Acknowledge" button is clearly labeled: `aria-label="Acknowledge clinical alert"`. +- After acknowledgment, the removal is smooth (no jarring DOM change for screen readers — the element simply removes itself from the accessibility tree). + +### Focus Management + +- After login completes, focus moves to the first sidebar item (Summary). +- After navigating to a new view, focus moves to the first heading in the main content area. +- After expanding a consultation, focus moves to the "HISTORY" heading within the expanded content. +- After closing a context menu, focus returns to the element that triggered it. +- After acknowledging an alert, focus moves to the main content area's first interactive element. + +### Color and Contrast + +- All text meets WCAG 2.1 AA contrast requirements against its background. +- Traffic light indicators are never the sole communicator of state — they always accompany text labels ("Active", "Resolved", "In Progress"). +- NHS blue (`#005EB8`) on white provides a contrast ratio of ~7.3:1 (exceeds AA). +- The amber alert text (`#92400E`) on amber background (`#FEF3C7`) provides a contrast ratio of ~5.8:1 (meets AA). + +### Motion Preferences + +When `prefers-reduced-motion: reduce` is active: +- Login typing animation completes instantly (full text appears at once) +- Clinical alert appears without slide animation (instant render) +- Consultation expand/collapse is instant (no height animation) +- Patient banner condensation is instant (no smooth transition) +- All hover background-color changes remain (they are not motion) + +--- + +## What Makes This Special + +**Absolute thematic fidelity.** This isn't a clinical "theme" loosely applied — it's a genuine PMR interface reimagined as a CV. The patient banner, the consultation journal format, the medications table, the coded entries, the traffic lights, the clinical alert, the login screen — every element is drawn from real NHS clinical software. The fidelity is what makes the concept work. A clinician visiting this site will immediately recognize the interface, and that recognition creates delight. + +**The consultation format is actually better for career content.** The History / Examination / Plan structure maps perfectly to Context / Analysis / Outcome — arguably a better format for presenting career achievements than traditional bullet lists. "History" gives the reader context for why the role existed. "Examination" shows what Andy analyzed and built. "Plan" shows what was delivered and measured. This is how clinical thinking works, and it's also how impact-driven career narratives should work. + +**The clinical alert is a guaranteed attention-grabber.** Framing "£14.6M in efficiency savings" as a system-generated clinical alert — with an amber background, a warning icon, and a required "Acknowledge" action — gives the number institutional weight. It doesn't feel like a boast; it feels like a data point flagged by a system. The user has to consciously dismiss it, which means they've read it, processed it, and engaged with it. No other portfolio design achieves this level of engagement with a single metric. + +**The medications-as-skills mapping is clever and navigable.** Presenting skills as a medications list with dosage, frequency, and status columns provides more information than a typical skills section. "Python | 90% | Daily | 2017 | Active" tells the reader: proficiency level, current usage intensity, how long Andy has used it, and whether it's still actively in use. The "prescribing history" expansion shows skill progression over time. This is richer data than a grid of progress bars. + +**Clinicians get the joke. Recruiters get the data.** The design works on two levels simultaneously. Healthcare professionals will recognize the PMR interface and appreciate the creativity (and the accuracy of the reproduction). Non-clinical recruiters won't know they're looking at a PMR clone, but they'll find the interface navigable, structured, and information-dense — because clinical systems are designed for efficient information retrieval under time pressure. Both audiences win. + +**The login screen is the most immersive transition.** Every NHS worker has typed their credentials into a dark-blue login screen at 8am. This transition puts them right there. It's a shared institutional experience, and it establishes the metaphor instantly: you are opening a record. The "patient" happens to be a career. By the time the PMR interface materializes, the user is already thinking in clinical-system mode. + +**Problem-oriented framing turns achievements into resolutions.** The Problems view reframes career achievements as "problems" that Andy identified and resolved. "Manual prescribing analysis inefficiency" is a problem statement. "Built Python switching algorithm, 14,000 patients identified, £2.6M annual savings" is the resolution. This narrative structure — problem followed by resolution followed by measurable outcome — is more compelling than a list of accomplishments because it shows the thinking that preceded the action. It reveals process, not just results. diff --git a/skills/bencium-innovative-ux-designer/ACCESSIBILITY.md b/skills/bencium-innovative-ux-designer/ACCESSIBILITY.md new file mode 100644 index 0000000..d514f4e --- /dev/null +++ b/skills/bencium-innovative-ux-designer/ACCESSIBILITY.md @@ -0,0 +1,111 @@ +# Accessibility Essentials + +Accessibility enables creativity - it's a foundation, not a limitation. WCAG 2.1 AA compliance. + +## Core Principles (POUR) + +- **Perceivable**: Content must be perceivable (alt text, contrast, captions) +- **Operable**: UI must be keyboard/touch accessible +- **Understandable**: Clear, predictable behavior +- **Robust**: Works with assistive technologies + +## Contrast Requirements + +| Element | Minimum Ratio | +|---------|---------------| +| Normal text | 4.5:1 | +| Large text (18pt+) | 3:1 | +| UI components | 3:1 | + +**Tools**: Chrome DevTools Accessibility tab, WebAIM Contrast Checker + +## Keyboard Navigation + +```tsx +// All interactive elements need focus states + + Accessible + + +// Custom elements need tabindex and key handlers + (e.key === 'Enter' || e.key === ' ') && handleClick()} +> + Custom Button + +``` + +**Essentials:** +- Tab through entire interface +- Enter/Space activates elements +- Escape closes modals +- Visible focus indicators always + +## Essential ARIA + +```tsx +// Buttons without text + + +// Expandable elements +Menu + +// Live regions for dynamic content +{statusMessage} +{errorMessage} + +// Form errors + +{hasError && Error text} +``` + +## Semantic HTML + +```tsx +// Use semantic elements, not divs +... +... + + +// Heading hierarchy (never skip levels) +Page Title + Section + Subsection +``` + +## Touch Targets + +- Minimum **44x44px** for all interactive elements +- Adequate spacing between targets +- `touch-manipulation` CSS for responsive touch + +## Screen Reader Content + +```tsx +// Hidden but announced +Additional context + +// Skip link + + Skip to main content + +``` + +## Quick Checklist + +- [ ] Keyboard: Can tab through everything +- [ ] Focus: Visible focus indicators +- [ ] Contrast: 4.5:1 for text +- [ ] Alt text: All images have appropriate alt +- [ ] Headings: Logical h1-h6 hierarchy +- [ ] Forms: Labels associated with inputs +- [ ] Errors: Announced to screen readers +- [ ] Touch: 44px minimum targets + +## Resources + +- [WCAG 2.1 Quick Reference](https://www.w3.org/WAI/WCAG21/quickref/) +- [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/) +- [ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/) diff --git a/skills/bencium-innovative-ux-designer/DESIGN-SYSTEM-TEMPLATE.md b/skills/bencium-innovative-ux-designer/DESIGN-SYSTEM-TEMPLATE.md new file mode 100644 index 0000000..e968748 --- /dev/null +++ b/skills/bencium-innovative-ux-designer/DESIGN-SYSTEM-TEMPLATE.md @@ -0,0 +1,577 @@ +# Design System Template + +Meta-framework for understanding what's fixed, project-specific, and adaptable in your design system. + +## Purpose + +This template helps you distinguish between: +- **Fixed Elements**: Universal rules that never change +- **Project-Specific Elements**: Filled in for each project based on brand +- **Adaptable Elements**: Context-dependent implementations + +--- + +## I. FIXED ELEMENTS + +These foundations remain consistent across all projects, regardless of brand or context. + +### 1. Spacing Scale + +**Fixed System:** +``` +4px, 8px, 12px, 16px, 24px, 32px, 48px, 64px, 96px +``` + +**Usage:** +- Margins, padding, gaps between elements +- Mathematical relationships ensure visual harmony +- Use multipliers of base unit (4px) + +**Why Fixed:** +Consistent spacing creates visual rhythm regardless of brand personality. + +### 2. Grid System + +**Fixed Structure:** +- **12-column grid** for most layouts (divisible by 2, 3, 4, 6) +- **16-column grid** for data-heavy interfaces +- **Gutters**: 16px (mobile), 24px (tablet), 32px (desktop) + +**Why Fixed:** +Grid provides structural order. Brand personality shows through color, typography, content—not grid structure. + +### 3. Accessibility Standards + +**Fixed Requirements:** +- **WCAG 2.1 AA** compliance minimum +- **Contrast**: 4.5:1 for normal text, 3:1 for large text +- **Touch targets**: Minimum 44×44px +- **Keyboard navigation**: All interactive elements accessible +- **Screen reader**: Semantic HTML, ARIA labels where needed + +**Why Fixed:** +Accessibility is not negotiable. It's a baseline requirement for ethical, legal, and usable products. + +### 4. Typography Hierarchy Logic + +**Fixed Structure:** +- **Mathematical scaling**: 1.25x (major third) or 1.333x (perfect fourth) +- **Hierarchy levels**: Display → H1 → H2 → H3 → Body → Small → Caption +- **Line height**: 1.5x for body text, 1.2-1.3x for headlines +- **Line length**: 45-75 characters optimal + +**Why Fixed:** +Mathematical relationships create predictable, harmonious hierarchy. Specific fonts change, but the logic doesn't. + +### 5. Component Architecture + +**Fixed Patterns:** +- **Button states**: Default, Hover, Active, Focus, Disabled +- **Form structure**: Label above input, error below, helper text optional +- **Modal pattern**: Overlay + centered content + close mechanism +- **Card structure**: Container → Header → Body → Footer (optional) + +**Why Fixed:** +Users expect consistent component behavior. Architecture is fixed; appearance is project-specific. + +### 6. Animation Timing Framework + +**Fixed Physics Profiles:** +- **Lightweight** (icons, chips): 150ms +- **Standard** (cards, panels): 300ms +- **Weighty** (modals, pages): 500ms + +**Fixed Easing:** +- **Ease-out**: Entrances (fast start, slow end) +- **Ease-in**: Exits (slow start, fast end) +- **Ease-in-out**: Transitions (smooth both ends) + +**Why Fixed:** +Natural physics feel consistent across brands. Duration and easing create that feeling. + +--- + +## II. PROJECT-SPECIFIC ELEMENTS + +Fill in these for each project based on brand personality and purpose. + +### 1. Brand Color System + +**Template Structure:** + +``` +NEUTRALS (4-5 colors): +- Background lightest: _______ (e.g., slate-50 or warm-white) +- Surface: _______ (e.g., slate-100) +- Border/divider: _______ (e.g., slate-300) +- Text secondary: _______ (e.g., slate-600) +- Text primary: _______ (e.g., slate-900) + +ACCENTS (1-3 colors): +- Primary (main CTA): _______ (e.g., teal-500) +- Secondary (alternative action): _______ (optional) +- Status colors: + - Success: _______ (green-ish) + - Warning: _______ (amber-ish) + - Error: _______ (red-ish) + - Info: _______ (blue-ish) +``` + +**Questions to Answer:** +- What emotion should the brand evoke? (Trust, excitement, calm, urgency) +- Warm or cool neutrals? +- Conservative or bold accents? + +**Examples:** + +**Project A: Fintech App** +``` +Neutrals: Cool greys (slate-50 → slate-900) +Primary: Deep blue (#0A2463) – trust, professionalism +Success: Muted green (#10B981) +Why: Financial products need trust, not playfulness +``` + +**Project B: Creative Community** +``` +Neutrals: Warm greys with beige undertones +Primary: Coral (#FF6B6B) – energy, creativity +Success: Teal (#06D6A0) – fresh, unexpected +Why: Creative spaces should feel inviting, not corporate +``` + +**Project C: Healthcare Platform** +``` +Neutrals: Pure greys (minimal color temperature) +Primary: Soft blue (#4A90E2) – calm, clinical +Success: Medical green (#38A169) +Why: Healthcare needs clarity and calm, not distraction +``` + +### 2. Typography Pairing + +**Template:** + +``` +HEADLINE FONT: _______ +- Weight: _______ (e.g., Bold 700) +- Use case: H1, H2, display text +- Personality: _______ (geometric/humanist/serif/etc.) + +BODY FONT: _______ +- Weight: _______ (e.g., Regular 400, Medium 500) +- Use case: Paragraphs, UI text +- Personality: _______ (neutral/readable/efficient) + +OPTIONAL ACCENT FONT: _______ +- Weight: _______ +- Use case: _______ (special headlines, callouts) +``` + +**Pairing Logic:** +- Serif + Sans-serif (classic, editorial) +- Geometric + Humanist (modern + warm) +- Display + System (distinctive + efficient) + +**Examples:** + +**Project A: Editorial Platform** +``` +Headline: Playfair Display (Serif, Bold 700) +Body: Inter (Sans-serif, Regular 400) +Why: Serif headlines = trustworthy, editorial feel +``` + +**Project B: Tech Startup** +``` +Headline: DM Sans (Sans-serif, Bold 700) +Body: DM Sans (Regular 400, Medium 500) +Why: Single-font system = modern, efficient, cohesive +``` + +**Project C: Luxury Brand** +``` +Headline: Cormorant Garamond (Serif, Light 300) +Body: Lato (Sans-serif, Regular 400) +Why: Elegant serif + readable sans = sophisticated +``` + +### 3. Tone of Voice + +**Template:** + +``` +BRAND PERSONALITY: +- Formal ↔ Casual: _______ (1-10 scale) +- Professional ↔ Friendly: _______ (1-10 scale) +- Serious ↔ Playful: _______ (1-10 scale) +- Authoritative ↔ Conversational: _______ (1-10 scale) + +MICROCOPY EXAMPLES: +- Button label (submit form): _______ +- Error message (invalid email): _______ +- Success message (saved): _______ +- Empty state: _______ + +ANIMATION PERSONALITY: +- Speed: _______ (quick/moderate/slow) +- Feel: _______ (precise/smooth/bouncy) +``` + +**Examples:** + +**Project A: Banking App** +``` +Personality: Formal (8), Professional (9), Serious (8) +Button: "Submit Application" +Error: "Email address format is invalid" +Success: "Application submitted successfully" +Animation: Quick (precise, efficient, no-nonsense) +``` + +**Project B: Social App** +``` +Personality: Casual (8), Friendly (9), Playful (7) +Button: "Let's go!" +Error: "Hmm, that email doesn't look right" +Success: "Nice! You're all set 🎉" +Animation: Moderate (smooth, friendly bounce) +``` + +### 4. Animation Speed & Feel + +**Template:** + +``` +SPEED PREFERENCE: +- UI interactions: _______ (100-150ms / 150-200ms / 200-300ms) +- State changes: _______ (200ms / 300ms / 400ms) +- Page transitions: _______ (300ms / 500ms / 700ms) + +ANIMATION STYLE: +- Easing preference: _______ (sharp / standard / bouncy) +- Movement type: _______ (minimal / smooth / expressive) +``` + +**Examples:** + +**Project A: Trading Platform** +``` +Speed: Fast (100ms UI, 200ms states, 300ms pages) +Style: Sharp easing, minimal movement +Why: Traders need speed, not distraction +``` + +**Project B: Wellness App** +``` +Speed: Slow (200ms UI, 400ms states, 500ms pages) +Style: Smooth easing, gentle movement +Why: Calm, relaxing experience matches brand +``` + +--- + +## III. ADAPTABLE ELEMENTS + +Context-dependent implementations that vary based on use case. + +### 1. Component Variations + +**Button Variants:** +- **Primary**: Full background color (high emphasis) +- **Secondary**: Outline only (medium emphasis) +- **Tertiary**: Text only (low emphasis) +- **Destructive**: Red-ish (danger actions) +- **Ghost**: Minimal (navigation, toolbars) + +**Adaptation Rules:** +- Primary: Main CTA, one per screen section +- Secondary: Alternative actions +- Tertiary: Less important actions, multiple allowed +- Use brand colors, but hierarchy logic is fixed + +### 2. Responsive Breakpoints + +**Fixed Ranges:** +- XS: 0-479px (small phones) +- SM: 480-767px (large phones) +- MD: 768-1023px (tablets) +- LG: 1024-1439px (laptops) +- XL: 1440px+ (desktop) + +**Adaptable Implementations:** + +**Simple Content Site:** +``` +XS-SM: Single column +MD: 2 columns +LG-XL: 3 columns max +Why: Content-focused, don't overwhelm +``` + +**Dashboard/Data App:** +``` +XS: Collapsed, cards stack +SM: Simplified sidebar +MD: Full sidebar + main content +LG-XL: Sidebar + main + right panel +Why: Data apps need more screen real estate +``` + +### 3. Dark Mode Palette + +**Adaptation Strategy:** + +Not a simple inversion. Dark mode needs adjusted contrast: + +**Light Mode:** +``` +Background: #FFFFFF (white) +Text: #0F172A (slate-900) → 21:1 contrast +``` + +**Dark Mode (Adapted):** +``` +Background: #0F172A (slate-900) +Text: #E2E8F0 (slate-200) → 15.8:1 contrast (still AA, but softer) +``` + +**Why Adapt:** +Pure white on pure black is too harsh. Dark mode needs slightly lower contrast for eye comfort. + +### 4. Loading States + +**Context-Dependent:** + +**Fast operations (<500ms):** +- No loading indicator (feels instant) + +**Medium operations (500ms-2s):** +- Spinner or skeleton screen + +**Long operations (>2s):** +- Progress bar with percentage +- Or: Skeleton + estimated time + +**Interactive Operations:** +- Button shows spinner inside (don't disable, show state) + +### 5. Error Handling Strategy + +**Context-Dependent:** + +**Form Errors:** +``` +Validate: On blur (after user leaves field) +Display: Inline below field +Recovery: Clear error on fix +``` + +**API Errors:** +``` +Transient (network): Show retry button +Permanent (404): Show helpful message + next steps +Critical (500): Contact support option +``` + +**Data Errors:** +``` +Missing: Show empty state with action +Corrupt: Show error boundary with reload +Invalid: Highlight + explain what's wrong +``` + +--- + +## DECISION TREE + +When implementing a feature, ask: + +### Is this... + +**FIXED?** +- Does it affect structure, accessibility, or universal UX? +- Examples: Spacing scale, grid, contrast ratios, component architecture +- **Action**: Use the fixed system, no variation + +**PROJECT-SPECIFIC?** +- Does it express brand personality or purpose? +- Examples: Colors, typography, tone of voice, animation feel +- **Action**: Fill in the template for this project + +**ADAPTABLE?** +- Does it depend on context, content, or use case? +- Examples: Component variants, responsive behavior, error handling +- **Action**: Choose appropriate variation based on context + +--- + +## EXAMPLE: Implementing a "Submit" Button + +### Fixed Elements (Always the same): +- Touch target: 44px minimum height +- Padding: 16px horizontal (from spacing scale) +- States: Default, Hover, Active, Focus, Disabled +- Animation: 150ms ease-out (lightweight profile) + +### Project-Specific (Filled per project): +- **Project A (Bank)**: Dark blue background, white text, "Submit Application" +- **Project B (Social)**: Coral background, white text, "Let's Go!" +- **Project C (Healthcare)**: Soft blue background, white text, "Continue" + +### Adaptable (Context-dependent): +- **Form context**: Primary button (full color) +- **Toolbar context**: Ghost button (text only) +- **Danger context**: Destructive variant (red-ish) + +--- + +## VALIDATION CHECKLIST + +Before finalizing a design, check: + +### Fixed Elements +- [ ] Uses spacing scale (4/8/12/16/24/32/48/64/96px) +- [ ] Follows grid system (12 or 16 columns) +- [ ] Meets WCAG AA contrast (4.5:1 normal, 3:1 large) +- [ ] Touch targets ≥ 44px +- [ ] Typography follows mathematical scale +- [ ] Components follow standard architecture + +### Project-Specific Elements +- [ ] Brand colors filled in and intentional +- [ ] Typography pairing chosen and justified +- [ ] Tone of voice defined and consistent +- [ ] Animation speed matches brand personality + +### Adaptable Elements +- [ ] Component variants appropriate for context +- [ ] Responsive behavior fits content type +- [ ] Loading states match operation duration +- [ ] Error handling fits error type + +--- + +## PROJECT KICKOFF TEMPLATE + +Use this to start a new project: + +``` +PROJECT NAME: _______________________ +PURPOSE: ____________________________ + +BRAND PERSONALITY: +- Primary emotion: _______ +- Warm or cool: _______ +- Formal or casual: _______ +- Conservative or bold: _______ + +COLORS (fill the template): +- Neutral base: _______ +- Primary accent: _______ +- Status colors: _______ / _______ / _______ + +TYPOGRAPHY (fill the template): +- Headline font: _______ +- Body font: _______ +- Pairing rationale: _______ + +TONE: +- Button labels style: _______ +- Error message style: _______ +- Success message style: _______ + +ANIMATION: +- Speed preference: _______ (fast/moderate/slow) +- Feel preference: _______ (sharp/smooth/bouncy) + +TARGET DEVICES: +- Primary: _______ (mobile/desktop/both) +- Secondary: _______ +``` + +--- + +## MAINTAINING CONSISTENCY + +### Documentation +- Keep this template updated as system evolves +- Document WHY choices were made, not just WHAT + +### Communication +- Share with designers: "Here's what varies vs. what's fixed" +- Share with developers: "Here are the design tokens" + +### Tooling +- Use CSS variables for project-specific values +- Use Tailwind config for spacing scale +- Use design tokens in Figma/Storybook + +### Reviews +- Audit: Does new work follow fixed elements? +- Validate: Are project-specific elements intentional? +- Question: Are adaptations justified by context? + +--- + +## EXAMPLES OF COMPLETE SYSTEMS + +### System A: B2B SaaS (Conservative) + +**Fixed**: Standard spacing, 12-col grid, WCAG AA, major third type scale +**Project-Specific**: +- Colors: Cool greys + corporate blue +- Typography: DM Sans (headlines + body) +- Tone: Professional, formal +- Animation: Quick, precise (150ms) +**Adaptable**: +- Dashboard gets multi-panel layout +- Forms are extensive (use progressive disclosure) +- Errors show detailed technical info + +### System B: Consumer Social App (Playful) + +**Fixed**: Same spacing/grid/accessibility/type logic +**Project-Specific**: +- Colors: Warm greys + vibrant coral +- Typography: Poppins (headlines) + Inter (body) +- Tone: Casual, friendly, playful +- Animation: Moderate, bouncy (200ms) +**Adaptable**: +- Mobile-first (most users on phones) +- Forms are minimal (progressive profiling) +- Errors are friendly, not technical + +### System C: Healthcare Platform (Clinical) + +**Fixed**: Same foundational structure +**Project-Specific**: +- Colors: Pure greys + medical blue +- Typography: System fonts (SF Pro / Segoe) +- Tone: Clear, authoritative, calm +- Animation: Slow, smooth (300ms) +**Adaptable**: +- Desktop-first (clinical use at workstations) +- Forms are complex (HIPAA compliance) +- Errors are precise with next steps + +--- + +## KEY TAKEAWAY + +**The system flexibility framework lets you:** +- Maintain consistency (fixed elements) +- Express brand personality (project-specific) +- Adapt to context (adaptable elements) + +**Without this framework:** +- Designers reinvent spacing every project +- Components feel inconsistent across products +- Brand personality overrides accessibility +- Context-blind implementations feel wrong + +**With this framework:** +- Speed: Start from proven foundations +- Consistency: Fixed elements guarantee it +- Flexibility: Express unique brand identity +- Context: Adapt without breaking system diff --git a/skills/bencium-innovative-ux-designer/MOTION-SPEC.md b/skills/bencium-innovative-ux-designer/MOTION-SPEC.md new file mode 100644 index 0000000..e37e363 --- /dev/null +++ b/skills/bencium-innovative-ux-designer/MOTION-SPEC.md @@ -0,0 +1,72 @@ +# Motion Specification + +Motion should surprise and delight while serving function. Animation is a creative tool. + +## Easing Curves + +| Easing | CSS | Use For | +|--------|-----|---------| +| **Ease-out** | `cubic-bezier(0.0, 0.0, 0.2, 1)` | Entrances, appearing | +| **Ease-in** | `cubic-bezier(0.4, 0.0, 1, 1)` | Exits, disappearing | +| **Ease-in-out** | `cubic-bezier(0.4, 0.0, 0.2, 1)` | State changes, transforms | +| **Spring** | `cubic-bezier(0.68, -0.55, 0.265, 1.55)` | Playful, attention-grabbing | +| **Linear** | `linear` | Spinners, continuous loops | + +## Duration by Element Weight + +| Weight | Duration | Examples | +|--------|----------|----------| +| **Lightweight** | 150ms | Icons, badges, chips | +| **Standard** | 300ms | Cards, panels, list items | +| **Weighty** | 500ms | Modals, page transitions | + +## Duration by Interaction + +| Interaction | Duration | +|-------------|----------| +| Button press | 100ms | +| Hover state | 150ms | +| Tooltip appear | 200ms | +| Tab switch | 250ms | +| Modal open | 300ms | +| Page transition | 400ms | + +## Common Patterns + +```tsx +// Hover transition (CSS) + + +// Fade + slide (Framer Motion) + + +// Stagger children + + + +``` + +## Performance Rules + +- Only animate `transform` and `opacity` (GPU-accelerated) +- Avoid animating `width`, `height`, `margin`, `padding` +- Keep durations under 500ms for UI interactions +- Respect `prefers-reduced-motion`: + +```css +@media (prefers-reduced-motion: reduce) { + *, *::before, *::after { + animation-duration: 0.01ms !important; + transition-duration: 0.01ms !important; + } +} +``` + +## Resources + +- [Framer Motion](https://www.framer.com/motion/) +- [CSS Easing Functions](https://easings.net/) diff --git a/skills/bencium-innovative-ux-designer/RESPONSIVE-DESIGN.md b/skills/bencium-innovative-ux-designer/RESPONSIVE-DESIGN.md new file mode 100644 index 0000000..e1a33eb --- /dev/null +++ b/skills/bencium-innovative-ux-designer/RESPONSIVE-DESIGN.md @@ -0,0 +1,90 @@ +# Responsive Design Essentials + +Mobile-first approach: start with mobile, progressively enhance for larger screens. + +## Breakpoints + +| Range | Pixels | Devices | Strategy | +|-------|--------|---------|----------| +| **XS** | 0-479px | Small phones | Single column, stacked nav, 44px touch targets | +| **SM** | 480-767px | Large phones | Single column, bottom nav, simplified UI | +| **MD** | 768-1023px | Tablets | 2 columns possible, sidebar nav | +| **LG** | 1024-1439px | Laptops | Multi-column, full nav, desktop UI | +| **XL** | 1440px+ | Desktop | Max-width containers, multi-panel layouts | + +## Tailwind Responsive + +```tsx +// Mobile-first: base styles, then scale up + + +// Responsive grid + + +// Responsive typography + + +// Show/hide by breakpoint +Mobile only +Desktop only +``` + +## Fluid Typography + +```css +h1 { font-size: clamp(2rem, 5vw, 4rem); } +p { font-size: clamp(1rem, 2.5vw, 1.25rem); } +``` + +## Touch Targets + +- Minimum **44x44px** for all interactive elements +- Use `touch-manipulation` to prevent 300ms tap delay +- Adequate spacing between targets + +```tsx + +``` + +## Mobile Simplification + +| Desktop | Mobile | +|---------|--------| +| Full nav bar | Hamburger menu | +| Side-by-side fields | Stacked fields | +| Multi-column grid | Single column | +| Inline buttons | Fixed bottom bar | +| Data table | Collapsed cards | +| Visible sidebar | Hidden/collapsible | + +## Images + +```tsx +// Responsive images + + +// Next.js + +``` + +## Testing + +Test at these widths: +- 375px (iPhone SE) +- 390px (iPhone 14) +- 768px (iPad) +- 1024px (iPad Pro) +- 1280px+ (Desktop) + +## Resources + +- [Tailwind Responsive](https://tailwindcss.com/docs/responsive-design) diff --git a/skills/bencium-innovative-ux-designer/SKILL.md b/skills/bencium-innovative-ux-designer/SKILL.md new file mode 100644 index 0000000..9d2a791 --- /dev/null +++ b/skills/bencium-innovative-ux-designer/SKILL.md @@ -0,0 +1,718 @@ +--- +name: bencium-innovative-ux-designer +description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics. +metadata: + version: 2.0.0 +--- + +# Innovative UX Designer + +Create distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices. Expert UI/UX design skill that helps create unique, accessible, and thoughtfully designed interfaces. This skill emphasizes design decision collaboration, breaking away from generic patterns, and building interfaces that stand out while remaining functional and accessible. + +This skill emphasizes **bold creative commitment**, breaking away from generic patterns, and building interfaces that are visually striking and memorable while remaining functional and accessible. + +## Core Philosophy + +**CRITICAL: Design Thinking Protocol** + +Before coding, **ASK to understand context**, then **COMMIT BOLDLY** to a distinctive direction: + +### Questions to Ask First +1. **Purpose**: What problem does this interface solve? Who uses it? +2. **Tone**: What aesthetic extreme fits? (see Tone Options below) +3. **Constraints**: Technical requirements (framework, performance, accessibility)? +4. **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember? + +### Tone Options (Pick an Extreme) +Choose a clear aesthetic direction and execute with precision: +- **Brutally minimal** - stripped to essence, bold typography, vast whitespace +- **Maximalist chaos** - layered, dense, visually rich, controlled disorder +- **Retro-futuristic** - vintage meets sci-fi, nostalgic tech aesthetics +- **Organic/natural** - soft edges, earthy colors, nature-inspired textures +- **Luxury/refined** - elegant spacing, premium typography, subtle details +- **Playful/toy-like** - bright colors, rounded shapes, delightful interactions +- **Editorial/magazine** - strong typography hierarchy, asymmetric layouts +- **Brutalist/raw** - exposed structure, harsh contrasts, intentionally rough +- **Art deco/geometric** - bold patterns, metallic accents, symmetric elegance +- **Soft/pastel** - gentle gradients, muted tones, calming atmosphere +- **Industrial/utilitarian** - functional, no-nonsense, mechanical precision + +### After Getting Context +- **Commit fully** to the chosen direction - no half measures +- Present 2-3 alternative approaches with trade-offs +- Then implement with precision: production-grade, visually striking, memorable + +## Foundational Design Principles + +### Stand Out From Generic Patterns + +**NEVER Use These AI-Generated Aesthetics:** +- **Fonts**: Inter, Roboto, Arial, system fonts as primary choice, Space Grotesk (overused by AI) +- **Colors**: Generic SaaS blue (#3B82F6), purple gradients on white backgrounds +- **Patterns**: Cookie-cutter layouts, predictable component arrangements +- **Effects**: Glass morphism, Apple design mimicry, liquid/blob backgrounds +- **Overall**: Anything that looks "Claude-generated" or machine-made + +**Instead, Create Atmosphere:** +- Suggest photography, patterns, textures over flat solid colors +- Apply gradient meshes, noise textures, geometric patterns +- Use layered transparencies, dramatic shadows, decorative borders +- Consider custom cursors, grain overlays, contextual effects +- Think beyond typical patterns - you can step off the written path + +**Draw Inspiration From:** +- Modern landing pages (Perplexity, Comet Browser, Dia Browser) +- Framer templates and their innovative approaches +- Leading brand design studios +- Historical design movements (Bauhaus, Otl Aicher, Braun) - but as inspiration, not imitation +- Beautiful background animations (CSS, SVG) - slow, looping, subtle + +**Visual Interest Strategies:** +- Unique color pairs that aren't typical +- Animation effects that feel fresh +- Background patterns that add depth without distraction +- Typography combinations that create contrast +- Visual assets that tell a story + +### Core Design Philosophy + +1. **Simplicity Through Reduction** + - Identify the essential purpose and eliminate distractions + - Begin with complexity, then deliberately remove until reaching the simplest effective solution + - Every element must justify its existence + +2. **Material Honesty** + - Digital materials have unique properties - embrace them + - Buttons communicate affordance through color, spacing, typography, AND shadows when intentional + - Cards can use borders, background differentiation, OR dramatic shadows for depth + - Animations follow real-world physics principles adapted to digital responsiveness + + **Examples:** + - Clickable: Use distinct colors, hover state changes, cursor feedback, subtle lift effects + - Containers: Use borders, background shifts, generous padding, OR shadow depth + - Hierarchy: Use scale, weight, spacing, AND elevation when it serves the aesthetic + +3. **Functional Layering** + - Create hierarchy through typography scale, color contrast, and spatial relationships + - Layer information conceptually (primary → secondary → tertiary) + - Use shadows and gradients INTENTIONALLY when they serve the aesthetic direction + - Embrace functional depth: modals over content, dropdowns over UI + - Avoid: glass morphism, Apple mimicry (but shadows/gradients are tools, not enemies) + +4. **Obsessive Detail** + - Consider every pixel, interaction, and transition + - Excellence emerges from hundreds of small, intentional decisions + - Balance: Details should serve simplicity, not complexity + - When detail conflicts with clarity, clarity wins + +5. **Coherent Design Language** + - Every element should visually communicate its function + - Elements should feel part of a unified system + - Nothing should feel arbitrary + +6. **Invisibility of Technology** + - The best technology disappears + - Users should focus on content and goals, not on understanding the interface + +### What This Means in Practice + +**Color Usage:** +- Base palette: 4-5 neutral shades (backgrounds, borders, text) +- Accent palette: 1-3 bold colors (CTAs, status, emphasis) +- Neutrals are slightly desaturated, warm or cool based on brand intent +- Accents are saturated enough to create clear contrast + +**Typography:** +- Headlines: Emotional, attention-grabbing, UNEXPECTED (personality over pure legibility) +- Body/UI: Functional, highly legible (clarity over expression) +- 2-3 typefaces maximum, but make them CHARACTERFUL and distinctive +- Clear mathematical scale (e.g., 1.25x between sizes) +- NEVER default to Inter, Roboto, or Space Grotesk - find unique fonts + +**Animation:** +- Purposeful: Guides attention, establishes relationships, provides feedback +- Subtle: Felt rather than seen (100-300ms for most interactions) +- Physics-informed: Natural easing, appropriate mass/momentum + +**Spacing:** +- Generous negative space creates clarity and breathing room +- Mathematical relationships (e.g., 4px base, 8/16/24/32/48px scale) +- Consistent application creates visual rhythm + +### Design Decision Checklist + +Before presenting any design, verify: + +1. **Purpose**: Does every element serve a clear function? +2. **Hierarchy**: Is visual importance aligned with content importance? +3. **Consistency**: Do similar elements look and behave similarly? +4. **Accessibility**: Does it meet WCAG AA standards? (contrast, touch targets, keyboard nav) +5. **Responsiveness**: Does it work on mobile, tablet, desktop? +6. **Uniqueness**: Does this break from generic SaaS patterns? +7. **Approval**: Have I asked before implementing colors, fonts, sizes, layouts? + +**Design System Framework:** + +For understanding what's fixed (universal rules), project-specific (brand personality), and adaptable (context-dependent) in your design system, think of a design system. + +## Visual Design Standards + +### Color & Contrast + +**Color System Architecture:** + +Every interface needs two color roles: + +1. **Base/Neutral Palette (4-5 colors):** + - Backgrounds (lightest) + - Surface colors (cards, inputs) + - Borders and dividers + - Text (darkest) + - Use slightly desaturated, warm or cool greys based on brand + +2. **Accent Palette (1-3 colors):** + - Primary action (CTA buttons) + - Status indicators (success, warning, error, info) + - Focus/hover states + - Use saturated colors for clear contrast against neutrals + +**Palette Structure Example:** +``` +Neutrals: slate-50, slate-100, slate-300, slate-700, slate-900 +Accents: teal-500 (primary), amber-500 (warning), red-500 (error) +``` + +**Color Application Rules:** + +- **Backgrounds**: Lightest neutral (slate-50 or white) +- **Text**: Darkest neutral for primary text (slate-900), mid-tone for secondary (slate-600) +- **Buttons (primary)**: Accent color with white text +- **Buttons (secondary)**: Neutral with border and dark text +- **Status indicators**: Specific accent (green=success, red=error, amber=warning, blue=info) +- **Interactive states**: + - Hover: Darken by 10-15% or shift hue slightly + - Focus: Use ring/outline in accent color + - Disabled: Reduce opacity to 40-50% and remove hover effects + +**Color Relationships:** + +Choose warm or cool intentionally based on brand: +- **Warm greys** (beige/brown undertones): Organic, approachable, trustworthy +- **Cool greys** (blue undertones): Modern, tech-forward, professional + +Accent colors should have clear contrast with both: +- Light backgrounds (for buttons on white) +- Dark text (if used as backgrounds for white text) + +**Intentional Color Usage:** +- Every color must serve a purpose (hierarchy, function, status, or action) +- Avoid decorative colors that don't communicate meaning +- Maintain consistency: same color = same meaning throughout + +**Accessibility:** +- Ensure sufficient contrast for color-blind users +- Follow WCAG 2.1 AA: minimum 4.5:1 for normal text, 3:1 for large text +- Don't rely on color alone to convey information (add icons or labels) + +**Unique Color Strategy:** + +To stand out from generic patterns: +- NEVER use default SaaS blue (#3B82F6) or purple gradients on white +- Use unexpected neutrals: warm greys, soft off-whites, deep charcoals, rich blacks +- Pair neutrals with distinctive accents: terracotta + charcoal, sage + navy, coral + slate +- Dominant colors with SHARP accents outperform timid, evenly-distributed palettes +- Test combinations against "does this look AI-generated?" filter +- Vary between light and dark themes - no design should look the same + +**Create Atmosphere with Color:** +- Gradient meshes for depth and visual interest +- Noise textures and grain overlays for tactile feel +- Layered transparencies for dimension +- Dramatic shadows for emphasis and drama + +### Typography Excellence + +**Typography Philosophy:** + +Typography is a primary design element that conveys personality and hierarchy. + +**Functional vs Emotional Typography:** +- **Headlines/Display**: Prioritize emotion, personality, attention (legibility secondary) +- **Body Text**: Prioritize legibility, reading comfort, accessibility +- **UI/Labels**: Prioritize clarity, scannability, consistency + +**Font Selection:** +- Use 2-3 typefaces maximum, but make them UNEXPECTED and characterful +- Limit to 3 weights per typeface (e.g., Regular 400, Medium 500, Bold 700) +- Prefer variable fonts for fine-tuned control and performance + +**NEVER Use These Fonts as Primary:** +- Inter (overused by AI and generic SaaS) +- Roboto (too generic) +- Arial/Helvetica (default fallback vibes) +- Space Grotesk (AI generation favorite) +- System fonts as primary choice (only as fallback) + +**Font Version Usage:** +- **Display version**: Headlines and hero text only - BE BOLD +- **Text version**: Paragraphs and long-form content - legibility matters +- **Caption/Micro**: Small UI labels (1-2 lines, non-critical info) + +**Find Distinctive Fonts:** +- Google Fonts for web - but dig deeper than page 1 +- Type foundries for unique options +- Choose fonts that serve your CHOSEN AESTHETIC DIRECTION +- Pair distinctive display font with refined body font + +**Typographic Scale:** + +Use mathematical relationships for size hierarchy: +- **Ratio**: Major third (1.25x) for moderate contrast, Perfect fourth (1.333x) for dramatic +- **Base size**: 16px (1rem) for body text +- **Example scale (1.25x)**: + ``` + xs: 0.64rem (10px) + sm: 0.8rem (13px) + base: 1rem (16px) + lg: 1.25rem (20px) + xl: 1.563rem (25px) + 2xl: 1.953rem (31px) + 3xl: 2.441rem (39px) + 4xl: 3.052rem (49px) + 5xl: 3.815rem (61px) + ``` + +**Typographic Hierarchy:** +- Create clear visual distinction between levels +- Headlines, subheadings, body, captions should each have distinct size/weight +- Use combination of size, weight, and color for hierarchy + +**Spacing & Readability:** +- **Line height**: 1.5x font size for body text (e.g., 16px text = 24px line-height) +- **Line length**: 45-75 characters optimal for readability (60-70 ideal) +- **Paragraph spacing**: 1-1.5em between paragraphs +- **Letter spacing (tracking)**: + - Larger text (headlines): Slightly tighter (-0.02em to -0.05em) + - Normal text (body): Default (0) + - Small text (captions): Slightly looser (+0.01em to +0.03em) + - General rule: As size increases, reduce tracking; as size decreases, increase tracking + +**Font Pairing Logic:** + +When using multiple typefaces, create contrast through: +- **Category contrast**: Serif + Sans-serif (classic, clear distinction) +- **Weight contrast**: Light + Bold (dynamic, energetic) +- **Personality contrast**: Geometric + Humanist (modern + warm) + +Examples: +- Serif headlines + Sans body (editorial, trustworthy) +- Display headlines + System body (distinctive + efficient) +- Bold sans headlines + Light sans body (modern, clean) + +**UI Typography:** + +Specific guidance for interface elements: +- **Button text**: Semi-Bold (600), 14-16px, consistent casing (all-caps OR title case) +- **Form labels**: Regular (400), 14px, positioned above input +- **Form input text**: Regular (400), 16px minimum (prevents iOS zoom on focus) +- **Placeholder text**: Light (300) or desaturated color, same size as input +- **Error messages**: Regular (400), 12-14px, color-coded (red-ish) + +**Responsive Typography:** + +Scale type sizes across breakpoints: +```tsx +// Example with Tailwind + + Responsive Headline + + +// Or with CSS clamp (fluid) +h1 { + font-size: clamp(2rem, 5vw, 4rem); +} +``` + +Reduce sizes on mobile (20-30% smaller than desktop) +Reduce hierarchy levels on small screens (fewer distinct sizes) + +### Layout & Spatial Design + +**Compositional Balance:** +- Every screen should feel balanced +- Pay attention to visual weight and negative space +- Use generous negative space to focus attention +- Add sufficient margins and paddings for professional, spacious look + +**Grid Discipline:** +- Maintain consistent underlying grid system +- Create sense of order while allowing meaningful exceptions +- Use grid/flex wrappers with `gap` for spacing +- Prioritize wrappers over direct margins/padding on children + +**Spatial Relationships:** +- Group related elements through proximity, alignment, and shared attributes +- Use size, color, and spacing to highlight important elements +- Guide user focus through visual hierarchy + +**Attention Guidance:** +- Design interfaces that guide user attention effectively +- Avoid cluttered interfaces where elements compete +- Create clear paths through the content + +## Interaction Design + + +**Motion Specification:** + +For detailed motion specs, see MOTION-SPEC.md (easing curves, duration tables, state-specific animations, implementation patterns). + +### User Experience Patterns + +**Core UX Principles:** + +1. **Direct Manipulation** + - Users interact directly with content, not through abstract controls + - Examples: + - Drag & drop to reorder items (not up/down buttons) + - Inline editing (click to edit, not separate form) + - Sliders for ranges (not numeric input with +/-) + - Pinch/zoom gestures on mobile (not +/- buttons) + +2. **Immediate Feedback** + - Every interaction provides instantaneous visual feedback (within 100ms) + - Types of feedback: + - **Visual**: Button pressed state, hover effects, color changes + - **Haptic**: Vibration on mobile (submit, error, success) + - **Audio**: Subtle sounds for critical actions (optional, user-controlled) + - **Loading**: Skeleton screens, spinners for >300ms operations + - **Success**: Checkmarks, green highlights, toast notifications + - **Error**: Red highlights, inline error messages, shake animations + +3. **Consistent Behavior** + - Similar-looking elements behave similarly + - Examples: + - **Visual consistency**: All primary buttons have same colors, sizes, hover states + - **Behavioral consistency**: All modals close via X button, ESC key, and outside click + - **Interaction consistency**: All drag targets have same hover state and drop feedback + - **Pattern consistency**: All forms validate on blur and submit + +4. **Forgiveness** + - Make errors difficult, but recovery easy + - **Prevention strategies**: + - Disable invalid actions (grey out unavailable buttons) + - Validate inputs inline (before submission) + - Confirm destructive actions (delete, overwrite) + - Auto-save in background (drafts, progress) + - **Recovery strategies**: + - Undo/redo for all state changes + - Soft deletes (trash/archive before permanent delete) + - Clear error messages with actionable fixes + - Preserve user input on errors (don't clear forms) + +5. **Progressive Disclosure** + - Reveal details as needed rather than overwhelming users + - Levels of disclosure: + - **Summary**: Show essential info by default (card title, price, rating) + - **Details**: Expand to show more info (description, specs, reviews) + - **Advanced**: Hide complex options behind "Advanced settings" toggle + - Examples: + - Accordion: Start collapsed, expand on click + - Search filters: Show 3-5 common filters, hide rest behind "More filters" + - Settings: Basic settings visible, advanced behind "Show advanced" + +**Modern UX Patterns:** + +1. **Conversational Interfaces** + + Prioritize natural language interaction where appropriate: + + **Four types:** + - **Pure chat**: Full conversation (AI assistants, support bots) + - **Command palette**: Text-based shortcuts (Cmd+K, search everywhere) + - **Smart search**: Natural language queries (search "meetings next week" vs filtering) + - **Form alternatives**: Conversational data collection ("What's your name?" vs form fields) + + **When to use:** + - Complex searches with multiple variables + - Task guidance (wizards, onboarding) + - Contextual help + - Quick actions (command palette) + + **When NOT to use:** + - Simple forms (just use inputs) + - Precise control interfaces (design tools, dashboards) + - High-frequency repetitive tasks + +2. **Adaptive Layouts** + + Respond to user context automatically: + - **Time-based**: Dark mode at night, light during day + - **Device-based**: Simplified UI on mobile, full features on desktop + - **Connection-based**: Reduce images/video on slow connections + - **Usage-based**: Prioritize frequent actions, hide rarely-used features + + Examples: + - Auto dark/light mode based on time or system preference + - Simplified mobile navigation (hamburger menu) vs full desktop nav + - Collapsed sidebar on small screens, expanded on large + +3. **Bold Visual Expression** + + Aesthetic flexibility based on chosen direction: + - Shadows ALLOWED and encouraged when intentional (dramatic shadows, soft elevation) + - Gradients ALLOWED for depth, accents, backgrounds, and atmosphere + - NO glass morphism effects (this is the one banned technique) + - NO Apple design mimicry (find your own voice) + - Focus on typography, color, spacing, AND visual effects to create hierarchy + - Create atmosphere: gradient meshes, noise textures, grain overlays, dramatic lighting + +**Navigation:** +- Clear structure with intuitive navigation menus +- Implement breadcrumbs for deep hierarchies (more than 2 levels) +- Use standard UI patterns to reduce learning curve (hamburger menu, tab bars) +- Ensure predictable behavior (back button works, links look clickable) +- Maintain navigation context (highlight current page, preserve scroll position) + +## Styling Implementation + +### Component Library & Tools + +**Component Library:** +- Strongly prefer shadcn components (v4, pre-installed in `@/components/ui`) +- Import individually: `import { Button } from "@/components/ui/button";` +- Use over plain HTML elements (`` over ``) +- Avoid creating custom components with names that clash with shadcn + +**Styling Engine:** +- Use Tailwind utility classes exclusively +- Adhere to theme variables in `index.css` via CSS custom properties +- Map variables in `@theme` (see `tailwind.config.js`) +- Use inline styles or CSS modules only when absolutely necessary + +**Icons:** +- Use `@phosphor-icons/react` for buttons and inputs +- Example: `import { Plus } from "@phosphor-icons/react"; ` +- Use color for plain icon buttons +- Don't override default `size` or `weight` unless requested + +**Notifications:** +- Use `sonner` for toasts +- Example: `import { toast } from 'sonner'` + +**Loading States:** +- Always add loading states, spinners, placeholder animations +- Use skeletons until content renders + +### Layout Implementation + +**Spacing Strategy:** +- Use grid/flex wrappers with `gap` for spacing +- Prioritize wrappers over direct margins/padding on children +- Nest wrappers as needed for complex layouts + +**Conditional Styling:** +- Use ternary operators or clsx/classnames utilities +- Example: `className={clsx('base-class', { 'active-class': isActive })}` + +### Responsive Design + +**Fluid Layouts:** +- Use relative units (%, em, rem) instead of fixed pixels +- Implement CSS Grid and Flexbox for flexible layouts +- Design mobile-first, then scale up + +**Media Queries:** +- Use breakpoints based on content needs, not specific devices +- Test across range of devices and orientations + +**Touch Targets:** +- Minimum 44x44 pixels for interactive elements +- Provide adequate spacing between touch targets +- Consider hover states for desktop, focus states for touch/keyboard + +**Performance:** +- Optimize assets for mobile networks +- Use CSS animations over JavaScript +- Implement lazy loading for images and videos + +## Accessibility Standards + +**Core Requirements:** +- Follow WCAG 2.1 AA guidelines +- Ensure keyboard navigability for all interactive elements +- Minimum touch target size: 44×44px +- Use semantic HTML for screen reader compatibility +- Provide alternative text for images and non-text content + +**Implementation Details:** +- Use descriptive variable and function names +- Event functions: prefix with "handle" (handleClick, handleKeyDown) +- Add accessibility attributes: + - `tabindex="0"` for custom interactive elements + - `aria-label` for buttons without text + - `role` attributes when semantic HTML isn't sufficient +- Ensure logical tab order +- Provide visible focus states + +## Design Process & Testing + +### Design Workflow + +1. **Understand Context:** + - What problem are we solving? + - Who are the users and when will they use this? + - What are the success criteria? + +2. **Explore Options:** + - Present 2-3 alternative approaches + - Explain trade-offs of each option + - Ask which direction resonates + +3. **Implement Iteratively:** + - Start with structure and hierarchy + - Add visual polish progressively + - Test at each stage + +4. **Validate:** + - Use playwright MCP to test visual changes + - Check across different screen sizes + - Verify accessibility + +### Testing Checklist + +**Visual Testing:** +- Use playwright MCP when available for automated testing +- Check responsive behavior at common breakpoints +- Verify touch targets on mobile +- Test with different content lengths (short, long, edge cases) + +**Accessibility Testing:** +- Test keyboard navigation +- Verify screen reader compatibility +- Check color contrast ratios +- Ensure focus states are visible + +**Cross-Device Testing:** +- Test on actual devices, not just emulators +- Check different browsers (Chrome, Firefox, Safari) +- Verify touch interactions on mobile +- Test landscape and portrait orientations + +## Examples + +### Example 1: Designing a Button + +**Initial Question to Ask:** +``` +Before I implement this button, I have a few design questions: +1. What's the primary action you want to emphasize? +2. Do you have brand colors in mind, or should I suggest options? +3. What emotion should this button convey? (urgent, calm, playful, professional) +``` + +**After Getting Approval, Implementation:** +```tsx +import { Button } from "@/components/ui/button"; +import { ArrowRight } from "@phosphor-icons/react"; + + + Get Started + + +``` + +### Example 2: Typography Hierarchy + +**Question First:** +``` +For this content hierarchy, I'm thinking: +- Headline: Large, bold, attention-grabbing +- Subheading: Medium, regular weight +- Body: Smaller, optimized for reading + +Should we go bold and contemporary, or subtle and refined? +``` + +**Implementation After Approval:** +```tsx + + + Headline Here + + + Supporting subheading + + + Body text optimized for readability with proper line height. + + +``` + +### Example 3: Unique Color Palette Suggestion + +**Presenting Options:** +``` +I'd like to suggest three color directions that break from typical SaaS patterns: + +1. **Warm Earth Tones** + - Base: Warm grey (#E8E2DC) + - Accent: Terracotta (#C86E4B) + - For: Organic, trustworthy feel + +2. **Cool Midnight** + - Base: Deep navy (#1A2332) + - Accent: Cyan (#4ECDC4) + - For: Modern, tech-forward feel + +3. **Soft Pastels** + - Base: Soft pink (#FFE5E5) + - Accent: Sage green (#9DB5A4) + - For: Calm, approachable feel + +Which direction feels right for your brand? +``` + +## Common Patterns to Avoid + +❌ **NEVER:** +- Use Inter, Roboto, Arial, Space Grotesk as primary fonts +- Use generic SaaS blue (#3B82F6) or purple gradients on white +- Copy Apple's design language or use glass morphism +- Create cookie-cutter layouts that look AI-generated +- Skip asking about context before designing +- Converge on common choices across generations (vary everything!) +- Use animations that delay user actions +- Create cluttered interfaces where elements compete + +✅ **ALWAYS:** +- Ask about purpose, tone, constraints, differentiation FIRST +- Then commit BOLDLY to a distinctive aesthetic direction +- Use unexpected, characterful typography choices +- Create atmosphere: shadows, gradients, textures, grain (when intentional) +- Dominant colors with sharp accents (not timid, evenly-distributed palettes) +- Provide immediate feedback for interactions +- Test with real devices +- Validate accessibility (it enables creativity, not limits it) +- Remember: Claude is capable of extraordinary creative work - don't hold back! + +## Version History + +- v2.0.0 (2025-11-22): Creative liberation update - bold aesthetics, shadows/gradients allowed, Design Thinking protocol +- v1.0.0 (2025-10-18): Initial release with comprehensive UI/UX design guidance + +## References + +For additional context, see: +- **Anthropic Frontend Aesthetics Cookbook**: https://github.com/anthropics/claude-cookbooks/blob/main/coding/prompting_for_frontend_aesthetics.ipynb +- WCAG 2.1 Guidelines: https://www.w3.org/WAI/WCAG21/quickref/ +- Google Fonts: https://fonts.google.com/ +- Tailwind CSS Docs: https://tailwindcss.com/docs +- Shadcn UI Components: https://ui.shadcn.com/ + +**Progressive Disclosure Files:** +- ACCESSIBILITY.md - Accessibility essentials (WCAG AA baseline) +- MOTION-SPEC.md - Animation timing and easing +- RESPONSIVE-DESIGN.md - Mobile-first breakpoints and patterns