# 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)