docs(ui): sync design system docs with bespoke health redesign

After the v1.1 restructure, health was further redesigned per a separate
brief and went bespoke -- new components (HealthStatusRibbon,
HealthPriorityCard, HealthPriorityList, HealthAuditSection), no
PageShell/PageHeader/MonitorLayout, custom severity-driven hierarchy.

Bring the docs in line:

- design-system.md: add §1d Bespoke as a fourth identity-strip pattern
  with health as canonical reference; remove health from PageHeader
  and Monitor canonical-reference slots (now TBD)
- design-decisions.md: v1.2 revision row capturing the redesign and
  the resulting doc cleanup
- screenshots-phase2/after-03-health.png: replace stale Monitor-archetype
  screenshot with the actual final redesigned page (Privacy mode ON)
- design-system-phase2-preview.html: regenerate; describe the four
  patterns, embed the new screenshot, update the file change list
This commit is contained in:
Tam Nhu Tran
2026-04-25 18:55:47 -04:00
parent 63198ab1ff
commit dd9854bfd7
4 changed files with 71 additions and 31 deletions
+18
View File
@@ -34,6 +34,24 @@ Phase 2's home + cliproxy migrations are reverted. Health stays migrated (Monito
---
## v1.2 revision (2026-04-25) — health redesign and bespoke pattern
After the v1.1 restructure, the `health` page received a separate, focused redesign per a dedicated handoff brief (`plans/reports/handoff-260425-1417-health-page-redesign.md`). The redesign went bespoke:
- New domain components: `HealthStatusRibbon`, `HealthPriorityCard`, `HealthPriorityList`, `HealthAuditSection`
- Severity-driven layout: priority surfaces (errors/warnings) at the top with prominent fix affordances, audit accordion below
- Dynamic colored background tied to overall status, glassmorphic accents
- No `PageShell`, no `PageHeader`, no `MonitorLayout` — full custom shell
**Resolution:** add a fourth identity-strip pattern — **§1d Bespoke** — for pages whose content shape doesn't fit the three primary patterns. The v1.1 row's claim that "health stays migrated (Monitor archetype + PageHeader works there)" no longer holds; corrected here.
**Side effects:**
- `PageHeader` lost its canonical reference (was health). New reference TBD when another page adopts it.
- `MonitorLayout` lost its canonical reference. Primitives remain available for future Monitor pages.
- `Bespoke` is explicitly an escape hatch — not a default. Code review enforces "you tried the three patterns first."
---
## How to revisit
If a decision turns out wrong in practice, update this doc and bump the affected primitive — don't silently drift. Each row above should be appended with a "Revised: <date> · <reason>" line if changed.
File diff suppressed because one or more lines are too long
+17 -3
View File
@@ -2,7 +2,7 @@
A page-level design system extracted from the **canonical reference pages**`home` and `cliproxy` — that already prove the patterns work in production. New pages should adapt to these references, not the other way around.
Health is the second-tier reference for pages whose content shape (gauge + KPIs + group accordions) doesn't fit either canonical hero — it uses the `MonitorLayout` archetype.
Some pages legitimately need a bespoke design (the redesigned `health` page is the current example) — when content shape demands custom hierarchy, the system should step out of the way rather than force the page into a wrong-fit archetype.
> Live preview in dev: `bun run dev` then visit `/_styleguide`.
@@ -63,7 +63,7 @@ Page identity (brand + page-level CTA + status) lives **inside the left rail**.
### 1c. `PageHeader` — title-row chrome
**Canonical reference:** `pages/health.tsx`
**Canonical reference:** none yet (was `health.tsx` until its bespoke redesign — see §1d).
```
┌────────────────────────────────────────────────────────────────────┐
@@ -81,6 +81,19 @@ Traditional title row with description and trailing actions.
**API:** `<PageHeader title description status actions />` — title + description on left, status badges + action buttons on right.
### 1d. Bespoke — full custom design
**Canonical reference:** `pages/health.tsx`
When a page's content shape demands its own hierarchy (priority-driven sections, dynamic backgrounds tied to status, custom card primitives like `HealthStatusRibbon` / `HealthPriorityCard`), the design system gets out of the way. Bespoke pages still respect global concerns (privacy mode, theme, sidebar) but build their own layout from scratch.
**Use it when:**
- None of the three patterns above fits without distorting the content
- The page's information hierarchy is genuinely unique (e.g. severity-driven priority surfaces with secondary audit lists)
- A bespoke implementation will be clearly better than forcing a fit
**Cost:** higher LOC, no reuse, no consistency — only justified when content demands it.
### Decision table
| Page shape | Identity strip |
@@ -88,6 +101,7 @@ Traditional title row with description and trailing actions.
| Dashboard / overview with ≤4 hero stats | **HeroBar** (home pattern) |
| Multi-entity Config (3-pane: list/form/json) | **Rail-anchored** (cliproxy pattern, no top chrome) |
| Single-entity Config OR Monitor with a real hero viz | **PageHeader** + body archetype |
| Severity / priority-driven page with custom hierarchy | **Bespoke** (health pattern) |
| Wizard / login / dialog | None — bespoke shell |
---
@@ -124,7 +138,7 @@ Left rail = `ListPane` (multi-entity) or `SectionRail` (single-entity, with `Int
### 2b. Monitor — KPI row + 12-col grid
**Canonical reference:** `pages/health.tsx`
**Canonical reference:** none in this PR. Health used to be the reference but went bespoke (§1d). The primitives (`MonitorLayout`, `KpiRow`, `KpiCard`, `MonitorGrid`, `MonitorCard`) ship and remain available; first page to genuinely need them becomes the next reference.
```
┌────────────────────────────────────────┐
Binary file not shown.

Before

Width:  |  Height:  |  Size: 104 KiB

After

Width:  |  Height:  |  Size: 134 KiB