# Frontend Redesign Plan — Aligning with `docs/design` Mockups This plan describes how to evolve `packages/web` from the current minimal Tailwind UI to match the editorial, warm-neutral design defined in `docs/design/MeshiTrack.html` and the screenshots under `docs/design/screenshots/`. The mockups are a React (UMD + Babel) prototype using a CSS-token system. We will port the **visual language and information architecture** into the existing **Next.js App Router + Tailwind v4** project, without dragging the prototype's runtime (React UMD, global `window.*` modules, inline data) into production. --- ## 1. Goals & Non-Goals ### Goals - Match the visual language of the mockups: typography (Fraunces / Inter Tight / JetBrains Mono), warm-neutral palette, sage brand, generous whitespace, soft shadows, rounded cards. - Reproduce the **app shell**: persistent left sidebar with grouped navigation + sticky topbar with title/subtitle, search, theme toggle, notifications. - Reproduce the **page archetypes** shown in the mockups: editorial "hero" header, multi-card grid with consistent `mt-card` style, status pills, supply bars, mini SVG charts. - Support light/dark themes and an accent switcher (sage / cobalt / terracotta / graphite) via CSS custom properties. - Keep accessibility, responsive layout, and SSR-friendliness intact. ### Non-Goals - Do not import the prototype's `data.jsx` mock data into production. - Do not adopt the prototype's `window.*` global module pattern or Babel-in-browser runtime. - Do not redesign data flows or API contracts; only the presentation layer changes. - Do not block on building every page in the mockup; food-domain pages (Phases 5-9) will reuse the system once the medicine pages are migrated. --- ## 2. Gap Analysis | Area | Current state (`packages/web`) | Target (mockups) | | ------------------------------------------------------------------------------------------------------ | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------- | | Theme tokens | Tailwind v4 `@theme` with a green ramp only | Full token set: warm neutrals, brand sage, status, viz palette, radii, shadows, fonts; light + dark | | Typography | System sans only | Fraunces (display), Inter Tight (UI), JetBrains Mono (numerics/keys), tabular-nums utility | | Sidebar | Flat list, 3 links, no groups, no badges | Grouped (`Medicines` section), icons, active state, badges, footer with avatar/role | | TopBar | Household chip + avatar | Breadcrumbs, title + subtitle, search with `⌘K`, notifications, theme toggle | | Cards | Ad-hoc Tailwind cards | Reusable `Card`, `CardHeader`, `Pill`, `Button` (`primary`/`ghost`), supply bar, ring chart, sparkbar | | Dashboard | 2 link cards | Hero greeting + ring, Today's schedule, Running low, Spending bars, Days-of-supply, Pending orders, Recent activity | | Cabinet / Schedule / Regimens / Organizer / Library / Refills / Purchases / Prices / Stores / Activity | Mostly placeholder grids/tables | Editorial layouts with status chips, swatches, supply bars (see screenshots) | | Theming | None | `data-theme="light | dark"`on``, accent CSS vars | | Icons | None defined centrally | Inline SVG icon set (`Icon.jsx` in mockup) | --- ## 3. Target Architecture ### 3.1 Design tokens (Tailwind v4 `@theme` + CSS vars) - Replace the current `@theme` block in [packages/web/src/styles/globals.css](packages/web/src/styles/globals.css) with the full token set from [docs/design/styles/tokens.css](docs/design/styles/tokens.css): - Color tokens exposed both as CSS vars (`--bg`, `--ink`, `--brand`, ...) **and** as Tailwind theme colors (`--color-bg`, `--color-ink`, ...) so utilities like `bg-bg`, `text-ink`, `border-border` work. - Radii (`--r-xs`..`--r-xl`) and shadows (`--shadow-sm/md/lg`). - Font family vars + load Fraunces / Inter Tight / JetBrains Mono via `next/font/google` in [packages/web/src/app/layout.tsx](packages/web/src/app/layout.tsx) and bind them to the `--font-*` vars. - Add `[data-theme='dark']` overrides in `globals.css` (copy from tokens.css). - Add small global utility classes used by the mockup: `.mono`, `.serif`, `.num` (tabular-nums) — keep names so mockup snippets can be lifted with minimal edits. ### 3.2 Theme + accent provider - New `ThemeProvider` (client component) that: - Persists `theme` (`light|dark`) and `accent` (`sage|cobalt|terracotta|graphite`) in `localStorage`. - Sets `data-theme` on `document.documentElement` and writes the accent's `--brand`, `--brand-deep`, `--brand-soft`, `--brand-soft-ink`, `--viz-1` CSS vars (logic ported from `docs/design/MeshiTrack.html` `useEffect`). - Avoids FOUC by emitting a tiny inline script in `app/layout.tsx` that reads `localStorage` and applies `data-theme` before hydration. - Expose a `useTheme()` hook for the topbar toggle. ### 3.3 Component library (`packages/web/src/components/ui/`) Port the mockup's reusable primitives as typed React components: - `Icon` — single component over an inline SVG map (`dashboard`, `cabinet`, `clock`, `list`, `calendar`, `pill`, `refresh`, `truck`, `tag`, `store`, `trend`, `settings`, `search`, `bell`, `sun`, `moon`, `chev`, `arrow`, `check`, `injection`, `capsule`). - `Card`, `CardHeader` (title + sub + right-side action slot). - `Button` with `variant: 'primary' | 'ghost' | 'danger'` and optional `size`. - `Pill` (status chip) with `tone: 'ok' | 'warn' | 'danger' | 'info' | 'neutral'`. - `SupplyBar`, `Ring` (SVG progress ring), `SparkBars` (monthly bars), `Sparkline`. - `Kbd`, `IconButton`, `Avatar`, `SearchInput`, `Breadcrumbs`. These live in `packages/web/src/components/ui/` and are pure presentational components (no data fetching, no `'use client'` unless they need state — most do not). ### 3.4 App shell Rewrite the layout primitives: - [packages/web/src/components/layout/Sidebar.tsx](packages/web/src/components/layout/Sidebar.tsx): - Brand block (logo + wordmark + household sub-line — `household.name` instead of mock "Red Panda Den"). - Grouped nav from a `NAV` array mirroring the mockup's structure but driven by `next/navigation`'s `usePathname` for active state. - Footer with `Avatar` + `displayName` + role from `useApi()`. - Badges (e.g. low-supply count, pending refills) wired to real SWR fetchers (Phase 2 — initially render the slot but optional). - [packages/web/src/components/layout/TopBar.tsx](packages/web/src/components/layout/TopBar.tsx): - Accept `title`, `subtitle`, `crumbs`, `actions` props. Provided either via a `` component each route renders, **or** via a Zustand/Context "page header" store updated from each page (recommended: a server-component `PageHeader` slot rendered above the page body — simpler, no client state). - Search input (visual only at first; `⌘K` palette is a follow-up). - Theme toggle wired to `useTheme()`. - Notifications bell (visual only initially). - [packages/web/src/app/(dashboard)/layout.tsx](): - Switch root container to the mockup's grid: `grid-template-columns: 248px 1fr; min-height: 100vh; background: var(--bg)`. - Inner `
` becomes `mt-page` with the mockup's padding (`32px` desktop, responsive down). ### 3.5 Page layout pattern Each route renders: ``` ...cards / grid... ``` `PageHeader` is a server component that renders the topbar's middle area (title block + breadcrumbs). The sticky outer `TopBar` reads `children` via React's `slots` pattern: simplest is to make `TopBar` itself accept `title/subtitle/crumbs` and have pages set them via a thin `PageHeaderContext` (client provider) or via Next's `template.tsx` + parallel routes. Choose the **Context approach** for minimal churn. --- ## 4. Page-by-Page Mapping For each route, port the layout from the mockup's JSX while replacing mock data with the existing service hooks. | Route | Current file | Mockup source | Notes | | ---------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/dashboard` | [dashboard/page.tsx]() | [Dashboard.jsx](docs/design/src/Dashboard.jsx) | Hero + Ring, Today's schedule, Running low, Spending, Supply, Pending orders, Activity. Many cards depend on data we don't yet expose; render skeletons / "Coming soon" states for missing endpoints. | | `/medicines/cabinet` | `medicines/cabinet/` | [Cabinet.jsx](docs/design/src/Cabinet.jsx) | Grid of medicine cards with swatch, supply bar, status pill. | | `/medicines/regimens` | `medicines/regimens/` | `RegimensPage` in [OtherPages.jsx](docs/design/src/OtherPages.jsx) | Per-regimen rows with schedule chips. | | `/medicines/organizer` | `medicines/organizer/` | [Schedule.jsx](docs/design/src/Schedule.jsx) `OrganizerPage` | 7-day x slots grid. | | `/medicines/library` | `medicines/library/` | `LibraryPage` | Filterable medicine table. | | `/medicines/activity` | `medicines/activity/` | `ActivityPage` | Activity feed + spend summary. | | `/refills` (new) | — | `RefillsPage` | Add route under `(dashboard)/refills/`. | | `/purchases` | `purchases/` | `PurchasesPage` | List with status pills. | | `/medicine-prices` | `medicine-prices/` | `PricesPage` | Per-store price comparison. | | `/stores` | `stores/` | `StoresPage` | Store cards. | | `/settings` | `settings/` | `SettingsPage` | Household + account sections. | Also add a **Schedule & Log** page (`/schedule` or `/medicines/schedule`) per mockup — currently missing. Update [medicines/page.tsx]() (and [dashboard/page.tsx]() if kept) to use `Card`/`CardHeader` instead of ad-hoc Tailwind classes. --- ## 5. Phased Rollout Treat this as 5 PR-sized increments, each independently shippable. ### Phase A — Foundations (no visible page changes yet) 1. Port tokens.css into `globals.css` (CSS vars + Tailwind v4 `@theme` mappings + dark overrides). 2. Wire fonts via `next/font/google` in `app/layout.tsx`; bind to `--font-*` vars. 3. Add `ThemeProvider` + FOUC-safe inline script. 4. Add `Icon` component and the icon set. 5. Add UI primitives: `Card`, `CardHeader`, `Button`, `Pill`, `IconButton`, `Avatar`, `Kbd`, `SearchInput`, `Breadcrumbs`, `Ring`, `SupplyBar`, `SparkBars`. 6. Vitest unit tests + RTL smoke tests for each primitive. ### Phase B — App shell 1. Rewrite `Sidebar` with grouped nav, icons, active-route detection via `usePathname`, footer. 2. Rewrite `TopBar` with title/subtitle/crumbs slots, search, theme toggle, notifications. 3. Add `PageHeaderContext` (or a header slot mechanism) so pages can set the topbar content. 4. Update `(dashboard)/layout.tsx` grid + `
` styling. 5. Snapshot/RTL tests for shell. ### Phase C — Dashboard 1. Re-implement `/dashboard` with hero + ring + cards using real data where available, skeletons elsewhere. 2. Wire "Running low" to existing cabinet endpoint; "Pending orders" to purchases; "Activity" to activity endpoint. 3. Tests: render with seeded SWR cache. ### Phase D — Medicine pages 1. Port Cabinet, Library, Regimens, Organizer, Activity, Schedule & Log one at a time. 2. Each PR: lift JSX from the mockup, replace mock data with `services/*` SWR hooks, add tests. ### Phase E — Commerce + settings 1. Port Refills (new route), Purchases, Prices, Stores, Settings. 2. Add accent picker UI in Settings. --- ## 6. Tailwind v4 Token Mapping (concrete snippet) In [packages/web/src/styles/globals.css](packages/web/src/styles/globals.css): ```css @import 'tailwindcss'; @theme { --font-sans: 'Inter Tight', ui-sans-serif, system-ui, sans-serif; --font-display: 'Fraunces', ui-serif, Georgia, serif; --font-mono: 'JetBrains Mono', ui-monospace, SFMono-Regular, monospace; --color-bg: var(--bg); --color-bg-elev: var(--bg-elev); --color-bg-inset: var(--bg-inset); --color-border: var(--border); --color-border-strong: var(--border-strong); --color-ink: var(--ink); --color-ink-strong: var(--ink-strong); --color-ink-muted: var(--ink-muted); --color-ink-faint: var(--ink-faint); --color-brand: var(--brand); --color-brand-deep: var(--brand-deep); --color-brand-soft: var(--brand-soft); --color-danger: var(--danger); --color-warn: var(--warn); --color-ok: var(--ok); --color-info: var(--info); --radius-xs: var(--r-xs); --radius-sm: var(--r-sm); --radius-md: var(--r-md); --radius-lg: var(--r-lg); --radius-xl: var(--r-xl); } :root { /* paste the :root block from docs/design/styles/tokens.css */ } [data-theme='dark'] { /* paste the dark block */ } ``` This lets us write `bg-bg-elev text-ink-strong border-border rounded-lg shadow-md` while still being able to use the raw `var(--brand)` inside inline SVGs (matching the mockup's pattern). --- ## 7. Risks & Mitigations | Risk | Mitigation | | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | FOUC on theme switch / SSR mismatch | Inline script in `` reads `localStorage` and sets `data-theme` before React hydrates. Mark theme-dependent UI as client-only when needed. | | Mockup uses inline `style={{...var(--viz-X)...}}` heavily | Keep that pattern in components; tokens are CSS vars so this works fine. | | Real data shape differs from mock data | For each card, define a small typed view-model and a transformer from API DTO; render skeletons when data is unavailable. | | Tailwind v4 `@theme` + custom CSS vars interplay | Verified above: declare CSS vars in `:root`/`[data-theme=dark]`, then map them to `--color-*` inside `@theme` so utilities pick them up. | | Test snapshots churn | Co-locate component tests, prefer RTL queries by role/text over snapshots; use snapshots only for the icon set. | | Scope creep | Strictly follow the phased rollout; each phase is independently mergeable. | --- ## 8. Out-of-Scope Follow-ups - `⌘K` command palette (search input is visual-only initially). - Real notification feed. - Per-user accent persistence in DB (initially `localStorage` only). - Mobile drawer for the sidebar (mockup is desktop-first; add a `< 900px` breakpoint that collapses to a top hamburger). - Animations beyond the existing CSS transitions. --- ## 9. Definition of Done (per phase) - All new components have unit tests; coverage for `packages/web` does not regress. - `npm run lint` and `npm run typecheck` pass at the workspace root. - Visual parity verified against the relevant screenshot in `docs/design/screenshots/`. - No usage of `any`; all view-models typed; all client-only files marked `'use client'`. - No regressions in existing E2E tests.