135 lines
8.7 KiB
Markdown
135 lines
8.7 KiB
Markdown
# Guardrails
|
|
|
|
Hard rules that MUST be followed in every iteration. Violating these will produce incorrect output.
|
|
|
|
## Design Direction
|
|
|
|
### When: Making ANY aesthetic decision
|
|
**Rule:** The direction is **GP System Dashboard** — a tile-based clinical record system with a light, modern aesthetic. Teal accent (#0D6E6E), light sidebar (#F7FAFA), warm sage background (#F0F5F4), white card surfaces. The clinical metaphor lives in the STRUCTURE (tiles as "record sections", status indicators, medication-style skill entries, coded entries) — not in dark chrome or heavy clinical styling.
|
|
**Why:** The previous dark-sidebar PMR interface is being replaced with the lighter, tile-based GP System concept (`References/GPSystemconcept.html`).
|
|
|
|
## Design System Guardrails
|
|
|
|
### When: Writing ANY visual component
|
|
**Rule:** Light-mode only. Do NOT add dark mode classes, `dark:` prefixes, or theme toggles.
|
|
**Why:** The design direction is light-mode only.
|
|
|
|
### When: Setting border-radius on cards and tiles
|
|
**Rule:** Use 8px border-radius (var(--radius)) for cards and tiles. Use 6px (var(--radius-sm)) for inner elements (metric cards, activity items, tags). The only exception is the LoginScreen card which uses 12px, and the command palette which uses 12px.
|
|
**Why:** The GP System concept uses 8px radius, slightly more rounded than the old 4px clinical style, reflecting the lighter aesthetic.
|
|
|
|
### When: Using monospace/code font
|
|
**Rule:** Use Geist Mono (`font-family: 'Geist Mono', monospace`) for timestamps, session info, dates, GPhC number, and coded data values. Fira Code is used in boot/ECG phases only.
|
|
**Why:** Geist Mono is the specified monospace font for the dashboard interface.
|
|
|
|
### When: Choosing the UI text font
|
|
**Rule:** Use Elvaro Grotesque (font-ui) as primary, Blumir (font-ui-alt) as alternative. Do NOT use Inter, Roboto, or system defaults. DM Sans appears in the concept HTML but is NOT the production font — use Elvaro Grotesque.
|
|
**Why:** Premium typography is the primary vehicle for the luxury feel. The concept HTML uses DM Sans as a placeholder; the production build uses the licensed premium fonts.
|
|
|
|
### When: Adding shadows to cards or tiles
|
|
**Rule:** Use the three-tier shadow system:
|
|
- `--shadow-sm`: `0 1px 2px rgba(26,43,42,0.05)` (default card state)
|
|
- `--shadow-md`: `0 2px 8px rgba(26,43,42,0.08)` (hover / interactive)
|
|
- `--shadow-lg`: `0 8px 32px rgba(26,43,42,0.12)` (command palette, overlays)
|
|
**Why:** Shadows create depth hierarchy. sm=resting, md=interactive, lg=overlay.
|
|
|
|
### When: Styling borders
|
|
**Rule:** Use `1px solid var(--border-light)` (#E4EDEB) for card and tile borders. Use `1px solid var(--border)` (#D4E0DE) for structural borders (sidebar right edge, topbar bottom, section dividers).
|
|
**Why:** Two-tier border system: lighter for cards, slightly stronger for structural elements.
|
|
|
|
### When: Choosing accent/interactive colors
|
|
**Rule:** Use teal `#0D6E6E` (var(--accent)) for interactive elements: links, active states, avatar gradient, dots, hover highlights. Hover: `#0A8080`. Accent-light: `rgba(10,128,128,0.08)` for subtle backgrounds.
|
|
**Why:** Teal is the primary accent in the GP System concept. It replaces NHS Blue as the interactive color.
|
|
|
|
### When: Using status colors
|
|
**Rule:** Status colors: success=`#059669`, amber=`#D97706`, alert=`#DC2626`, purple=`#7C3AED` (education). Each with matching light/border variants. Always pair colored indicators with text labels.
|
|
**Why:** Traffic light convention. Color-only indicators violate WCAG.
|
|
|
|
## Layout Guardrails
|
|
|
|
### When: Building the dashboard layout
|
|
**Rule:** Three-zone layout: TopBar (fixed, 48px) + Sidebar (fixed left, 272px) + Main content (scrollable card grid). Main content has 24px-28px padding and card grid with 16px gap. Grid: 2 columns on desktop, 1 column below 900px.
|
|
**Why:** Matches the GP System concept layout structure.
|
|
|
|
### When: Ordering tiles in the card grid
|
|
**Rule:** Tile order: Patient Summary (full) → Latest Results (half) + Repeat Medications (half) → Last Consultation (full) → Career Activity (full) → Education (full) → Projects (full). Full-width tiles span both columns.
|
|
**Why:** This ordering follows the concept layout with the user's addition of Patient Summary at the top.
|
|
|
|
## Sidebar Guardrails
|
|
|
|
### When: Building the sidebar
|
|
**Rule:** Sidebar contains ONLY: PersonHeader (avatar, name, title, status, details) → Tags → Alerts/Highlights. Active Projects, Core Skills, and Education are in the MAIN CONTENT as tiles, NOT in the sidebar.
|
|
**Why:** User explicitly requested moving Projects, Skills, and Education from sidebar to main dashboard tiles.
|
|
|
|
## Interaction Guardrails
|
|
|
|
### When: Expanding/collapsing tile content
|
|
**Rule:** Height animation ONLY (200ms, ease-out). Do NOT fade opacity on content. Single-expand accordion — only one item expanded at a time within a tile.
|
|
**Why:** Consistent expand/collapse behavior. Opacity fade was explicitly prohibited.
|
|
|
|
### When: Building the command palette
|
|
**Rule:** Trigger via Ctrl+K or search bar click. Overlay with backdrop blur. ESC to close. Arrow key navigation. Fuzzy search via fuse.js.
|
|
**Why:** Matches concept interaction pattern.
|
|
|
|
### When: Building KPI flip cards
|
|
**Rule:** Click to flip metric card (front=value, back=explanation). 400ms CSS perspective flip or instant swap with reduced motion. Only one card flipped at a time.
|
|
**Why:** User requested interactive KPI exploration with explanation text.
|
|
|
|
## Login Screen Guardrails
|
|
|
|
### When: Building the login typing animation
|
|
**Rule:** Username types at 80ms/char. Password dots at 60ms/dot. After typing completes, the "Log In" button becomes interactive — the user clicks it. It is NOT auto-triggered.
|
|
**Why:** The natural pace lets users absorb what's happening. The interactive button creates a moment of user agency.
|
|
|
|
## Component Guardrails
|
|
|
|
### When: Displaying traffic light status indicators
|
|
**Rule:** Colored dots must ALWAYS have text labels. Never use color as the sole indicator.
|
|
**Why:** WCAG — color cannot be the only means of communicating information.
|
|
|
|
### When: Writing table or list markup inside tiles
|
|
**Rule:** Use semantic markup. Tables use `<table>`, `<thead>`, `<th scope="col">`, `<tbody>`, `<tr>`, `<td>`. Lists use `<ul>`/`<ol>` with `<li>`. No div-based tables.
|
|
**Why:** Screen readers require native semantics.
|
|
|
|
### When: Using icons
|
|
**Rule:** Use `lucide-react` icons only. No unicode symbols, no inline SVG copied from external sources. Exception: the concept's SVG icons should be converted to their lucide-react equivalents (e.g., concept's house icon → `Home` from lucide-react).
|
|
**Why:** Consistent icon system, tree-shakeable, accessible.
|
|
|
|
## Data Guardrails
|
|
|
|
### When: Displaying CV content
|
|
**Rule:** All data must come from `src/data/*.ts` files. Do NOT hardcode content in components or change any numbers/dates. New data files (profile.ts, tags.ts, alerts.ts, kpis.ts, skills.ts) must be accurate to CV_v4.md.
|
|
**Why:** Data has been validated against CV_v4.md. Single source of truth.
|
|
|
|
### When: Building the "Repeat Medications" (skills) tile
|
|
**Rule:** Use the exact frequencies specified by the user: Data Analysis="Twice daily", Power BI="Once weekly", Python="Daily", SQL="Daily", JavaScript/TypeScript="When required". Include "years of experience" like "length of time on medication".
|
|
**Why:** User explicitly specified these frequency values for the medication metaphor.
|
|
|
|
## Visual Review Guardrails
|
|
|
|
### When: Completing any visual task
|
|
**Rule:** After quality checks, open `http://localhost:5173` via Playwright MCP tools, take a screenshot, and compare against `References/GPSystemconcept.html`. Fix visual discrepancies. If browser tools are unavailable, note in progress.txt and proceed.
|
|
**Why:** Code review alone cannot catch visual issues.
|
|
|
|
### When: Browser tools fail
|
|
**Rule:** Skip visual review, note it in progress.txt, continue. Do NOT retry more than twice.
|
|
**Why:** Visual review is valuable but not blocking.
|
|
|
|
## Technical Guardrails
|
|
|
|
### When: Writing TypeScript
|
|
**Rule:** No `any` types. All props must have typed interfaces.
|
|
**Why:** Strict typing prevents runtime errors.
|
|
|
|
### When: Adding animations
|
|
**Rule:** All animations must respect `prefers-reduced-motion`. With reduced motion: all animations skip to final state instantly.
|
|
**Why:** Accessibility requirement.
|
|
|
|
### When: Running quality checks
|
|
**Rule:** Run `npm run typecheck`, `npm run lint`, and `npm run build` after EVERY task. Fix all errors before committing.
|
|
**Why:** Build failures compound across iterations.
|
|
|
|
### When: Referencing the concept design
|
|
**Rule:** The reference design is `References/GPSystemconcept.html`. Open it in a browser or read the HTML to understand the visual target. The concept is the LAYOUT reference; production fonts and some colors differ (see font and color guardrails).
|
|
**Why:** The concept HTML is the single source of truth for layout and spatial composition.
|