docs(spec): HQ console redesign — warm ops-console system upgrade

Direction A v2 discipline (flat border-defined surfaces, black-ink primary,
accent-for-state, table/state patterns, Ctrl+K palette) wearing the H-04 warm
palette + teal accent. Client 360 with 12-month relationship-pulse ribbon.
UI-only; no backend changes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/superpowers/specs/2026-07-17-hq-console-redesign-design.md

@@ -0,0 +1,149 @@
+# HQ Console Redesign — Design Spec
+
+*Approved direction: "system upgrade" — Direction A v2's system discipline wearing H-04's
+warm palette. Sources reviewed: `admin_design_v2.html` (a Claude Design handoff tar; the
+chosen "Direction A v2" system), `H-04 Client 360 (timeline ribbon).html`, `Tecnostac
+Unified Workspace` promo, the small APEX card/loan-detail mockups, and the current
+`@sims/ui` tokens. Companion docs: `2026-07-17-apex-82963-ux-reference.md` (UX checklist
+honoured throughout), `2026-07-17-quote-to-close-funnel-design.md` (pages this shell must
+accommodate).*
+
+## 1. Goal & scope
+
+Visual + UX upgrade of `apps/hq-web` and `packages/ui`. **UI-only: no backend or schema
+changes; all data from existing endpoints.** Money math, repos, and tests untouched.
+`@sims/ui` stays generic — HQ-specific composites live in `apps/hq-web`.
+
+## 2. Design tokens (`packages/ui/src/tokens.css`)
+
+Warm neutrals + teal default accent; flat, border-defined surfaces (shadows only on
+overlays); black-ink primary buttons; accent reserved for *state*.
+
+| Token | Light | Dark (warm-tinted) |
+|---|---|---|
+| `--bg` | `#FAFAF7` | `#131210` |
+| `--bg-raised` | `#FFFFFF` | `#1B1A17` |
+| `--bg-hover` | `#F2F1EC` | `#242320` |
+| `--bg-inset` | `#F2F1EC` | `#0E0D0B` |
+| `--border` | `#E7E5DE` | `#2B2A25` |
+| `--border-strong` | `#D6D4CC` | `#3A3830` |
+| `--text` | `#1A1A17` | `#EAE8E2` |
+| `--text-dim` | `#6B6A62` | `#A8A69C` |
+
+- Semantic colors keep current structure (`ok/warn/err` + `*-soft`) re-tuned to the
+  muted H-04 range (ok `#047857`, warn `#A8702B`, err `#A64242` in light; brighter in dark).
+- **New accent `teal`** (`#115E59` / strong `#0F4F4A`; dark-mode accent ≈ `#2DA89A`) added
+  to the switcher and made the **default** in `theme.ts`. All six existing accents stay.
+- **Primary buttons become near-black ink** (`--text`-derived), not accent-filled. Accent
+  paints active nav, selected chips, links, focus rings. Danger stays red-toned.
+- Radius: `--radius: 6px` (cards, buttons), `--radius-sm: 4px` (chips, inputs) new,
+  `--radius-lg: 10px` (modals, palette). Pills 999px.
+- Type: Inter for UI + money (`tabular-nums` kept); **JetBrains Mono for machine data** —
+  client codes, doc numbers, GSTINs, IDs — via a `.mono` utility class. Uppercase
+  micro-labels 11px / 0.06em tracking (never below 11px — WCAG note from the H-04 review).
+- Shadows: `--shadow-sm/md` near-removed from resting surfaces (cards are 1px-bordered,
+  flat); `--shadow-lg` kept for modals/palette.
+
+## 3. App shell (`Layout.tsx`, `app.css`)
+
+- **Sidebar, grouped with uppercase eyebrows + count badges:**
+  - **WORK** — Dashboard *(badge: reminder queue count; amber, red if any failed)*,
+    Clients, New Document. *(Pipeline slots here when the funnel spec lands.)*
+  - **CATALOG** — Modules
+  - **INSIGHT** — Reports
+  - **ADMIN** — Employees *(currently routed but missing from nav — fixed here; role
+    visibility mirrors the page's own gating)*, Document Template *(owner-only, as today)*
+  - Active item: soft warm fill + 2px accent left bar + 600 weight. Footer: app version +
+    server-health dot (existing `/api/health`).
+- **Top bar:** breadcrumb (route-derived, e.g. `Clients / <name>`); search field opening
+  the command palette (`Ctrl K` kbd hint); **Gmail status pill** (ok dot "Gmail" /
+  amber "Gmail disconnected") — the hard-down banner stays as today, restyled; ThemeSwitcher;
+  user chip (initials avatar + display name + role); logout.
+- **Command palette (Ctrl+K):** 640px overlay over scrim. Groups: *Clients* (live results
+  from the existing `getClients(q)` search), *Go to* (static routes), *Actions* ("New
+  document", "New client"). Keyboard-first (↑↓ enter esc). Debounced fetch; no new endpoints.
+- **Responsive-lite (APEX-checklist item h):** below ~900px the sidebar collapses behind a
+  hamburger; content single-columns; tables scroll horizontally inside their card
+  (`overflow-x: auto`) — usable on a phone browser, not a native-app layout.
+
+## 4. Component upgrades (`packages/ui` — generic only)
+
+| Component | Change |
+|---|---|
+| `PageHeader` | Adds optional `breadcrumb`, inline status-chip slot, and stat-strip slot below desc (Direction A v2 header pattern). Existing call sites keep working (all new props optional). |
+| `DataTable` | Per-row `tone` (subtle `*-soft` tinting — e.g. overdue rows err-soft; APEX-checklist "pending first" is data-side, tinting is the visual half); per-column `mono`; sticky header. |
+| `FilterChips` **new** | Pill row with counts, single-select (`All · Active · Dormant · Lost`). Serves the funnel spec's `All | Mine | Overdue | Owner` later. |
+| `Skeleton` **new** | Varied-width shimmer bars; replaces every "Loading…" EmptyState. |
+| `ErrorState` **new** | Message + "Try again" button wired to the page's `reload()`. |
+| `RecordHeader` **new** | Initials avatar (deterministic tint from name hash) + title + status pill + meta line + right action cluster. |
+| `Tabs` **new** | Underline style, optional mono count per tab. |
+| `CommandPalette` **new** | Generic overlay taking grouped items + async group loader. |
+| `Badge`, `StatCard`, `Stats`, `Modal`, `Notice`, `Button`, inputs | Restyled via tokens; `StatCard` gains optional `tone` on the hint (delta coloring). |
+
+Icons: **`lucide-react`** (new dependency, tree-shaken) for nav + action icons — replaces
+the mockups' emoji placeholders. Used in `apps/hq-web` only, so `@sims/ui` gains no dependency.
+
+## 5. Pages (`apps/hq-web`)
+
+- **Dashboard** — header stat strip (Overdue ₹ · Queued · Failed · Follow-ups today);
+  reminder queue as the hero card (row-tinted by status; preview/send/dismiss inline as
+  today); remaining sections become cards in a 2-col grid ≥1100px, stacked below. Counts
+  visible on every card; no silent caps (unchanged data contracts).
+- **Clients** — FilterChips by status with counts + existing search + total badge; `code`
+  column mono; inline-create form restyled as a card.
+- **ClientDetail → "Client 360"** (hero page):
+  - `RecordHeader`: avatar, name, status pill, meta line (`code · state · GSTIN · since`),
+    actions: Log call · Record payment · New document.
+  - KPI row: Outstanding ₹ · Active modules · AMC status · Last interaction.
+  - **Timeline ribbon "Relationship pulse — last 12 months"** (HQ-specific component in
+    `apps/hq-web`): 4 lanes — Documents / Payments / Interactions / AMC & renewals — on a
+    shared 12-month axis, plotted from data the page already loads. Hover → readout bar
+    below the strip (H-04's scrubber line: `APR · INVOICE INV-042 — ₹1,20,000 · paid`);
+    click → navigate to the record (doc → `/documents/:id`) or switch to its tab. Pure
+    SVG/CSS, no chart library. Legend included for every marker shape.
+  - **Tabs** replace the 7-section stack: Overview (KPIs + ribbon + recent items) ·
+    Modules · Documents · Payments & plans · AMC · Interactions · AWS — counts in labels.
+    Tab state in the URL hash query so links deep-link.
+- **DocumentView** — RecordHeader treatment (doc number mono + status pill + actions),
+  totals right-aligned tabular.
+- **NewDocument** — restyled two-pane (form + LivePreview) with new inputs/cards.
+- **Reports** — pill tab switcher between report types; export/copy affordance kept.
+- **Modules, Employees, DocumentTemplate** — restyled with new primitives; Employees added
+  to nav (ADMIN group).
+- **Login** — split panel: dark warm brand panel (SiMS HQ lockup) + form card.
+
+## 6. Explicitly not doing
+
+Density toggle; permission matrix / tenant screens (not HQ's domain); roadmap badges in
+nav; bulk-select bars and inline table editing (no use case yet); native-app mobile
+patterns (responsive-lite only); backend changes of any kind; the Pipeline page itself
+(funnel spec builds it — this design only reserves its nav slot and provides `FilterChips`
+/ row-toning it needs).
+
+## 7. Error handling & states
+
+Every page: `Skeleton` while loading, `ErrorState` with retry on fetch failure (wired to
+the existing `useData.reload`), `EmptyState` with a next-action hint when lists are empty.
+Command palette shows "no matches" and network-error rows inline. Gmail pill degrades to
+banner behavior exactly as today.
+
+## 8. Testing & verification
+
+- `npm run typecheck` and `npm test` (177 tests) stay green — no domain code touched.
+- New `@sims/ui` components get vitest render tests where logic exists (FilterChips
+  selection, Tabs switching, DataTable tone/mono mapping, timeline bucketing math for the
+  ribbon: month-bucket function is a pure exported helper with unit tests).
+- End-to-end: run server + Vite, exercise Dashboard → Clients → Client 360 (all tabs,
+  ribbon hover/click) → DocumentView → NewDocument preview → Reports → theme/accent switch
+  (light+dark) → Ctrl+K palette → narrow-viewport pass, before claiming done.
+
+## 9. Build order (for the implementation plan)
+
+1. Tokens + base restyle (everything inherits immediately)
+2. Shell (sidebar groups, top bar, Gmail pill, responsive-lite)
+3. Generic components (Skeleton/ErrorState/FilterChips/Tabs/RecordHeader/DataTable/PageHeader upgrades)
+4. Command palette
+5. Dashboard + Clients
+6. Client 360 (tabs, then ribbon)
+7. Remaining pages + Login
+8. Verification pass (§8)