manage/openspec/changes/web-ui-rework/proposal.md

Proposal — web-ui-rework

Phase: proposal. Grounded in openspec/changes/web-ui-rework/exploration.md (verified inventory). No code changes. Product/UX questions for the user are collected in §8 — Proposal question round and must be answered before this proposal is treated as locked.

1. Problem / motivation

The Manage frontend is mid-migration: the app shell (App.tsx) and the new ObservabilityPage.tsx already live on shadcn/ui + Tailwind + lucide-react, but 22 files still import @mui/material, 2 use @mui/x-data-grid, and 2 use @mui/icons-material (10 distinct icons). The result is a split-feeling product: two design languages, two theming systems (MUI @emotion vs the Tailwind v4 @theme tokens in index.css), and a no-op theme.ts shim left behind. Orphaned charting deps (recharts, d3) linger in package.json even though no in-app charting exists.

This half-finished state collides with a second driver: Manage has moved to a thin-dashboard observability model where charts/metrics/logs live in external Grafana, and in-app surfaces show only Alertmanager alerts + Prometheus target health + Grafana deep-links. Finishing the migration is therefore not cosmetic — it is how we codify the decoupling (remove the charting deps, retire the last MUI surface, make the external-link affordance consistent) and land a coherent visual redesign on one design system.

2. Target outcome / product vision

A single, coherent Manage UI on shadcn/ui + Tailwind v4 + lucide-react, visually consistent with the already-migrated shell and ObservabilityPage:

• Every page uses the same tokens (primary #4f8cff, Inter, rounded-lg, one border weight) and the same layout primitives — Card over ad-hoc Paper, Tailwind flex/grid over MUI Grid/Stack.
• Observability stays first-class and thin: status as numbers/Badges plus outbound Grafana kiosk deep-links; no in-app charts.
• DataGrid surfaces (Media, FileBrowser) become TanStack Table on the shadcn Table primitive, preserving pagination / row-selection / row-click / column-visibility.
• A reconciled information architecture (Backups surfaced in nav; one name for Media/Applications).
• @mui/*, @emotion/*, recharts, d3, and the theme.ts shim are gone, and docs/REQUIREMENTS.md reflects the new UX.

3. Scope (in)

• Finish MUI v9 → shadcn/ui + Tailwind + lucide-react across all remaining consumers in frontend/src (22 material files + 2 DataGrid files + 2 icon files).
• Add the missing shadcn primitives (tabs table dialog input label checkbox switch progress separator avatar textarea dropdown-menu scroll-area) and @tanstack/react-table.
• Migrate both @mui/x-data-grid DataGrid usages to TanStack Table + shadcn Table.
• Deliver a visual/UX redesign aligned to the thin-dashboard model (density, typography ramp, status Badge semantics including a success variant, consistent external-link affordance).
• Remove orphaned recharts, d3, the theme.ts shim, and all @mui/* + @emotion/* deps.
• Reconcile IA: surface Backups in nav; resolve Media vs Applications naming.
• Update docs/REQUIREMENTS.md.

4. Non-goals

• No in-app charting — no recharts/d3 re-introduction, no custom charts; metrics visualisation stays in Grafana.
• No new design system — shadcn/ui + the existing Tailwind v4 @theme tokens only.
• No backend API changes — frontend types/* contracts stay unless a UI simplification forces one, which must be flagged separately.
• No MUI retention — all @mui/* and @emotion/* removed by the final slice.
• No auth/routing model change — OIDC (auth.ts, react-oidc-context) and react-router-dom structure unchanged; only nav items/IA may shift.
• No form-library introduction — keep current uncontrolled/useState form parity.

5. Key technical risks

• DataGrid → TanStack Table (high). The two DataGrid usages (Media.tsx, FileBrowser.impl.tsx) must reproduce pagination, row-selection, row-click, and column-visibility. Whether to also carry over client-side resizing/sorting is an open product question (exploration §4) and is the single highest-risk slice — sequenced last so the shared Table primitive and tokens are already settled.
• UsersPage size (high). pages/UsersPage.impl.tsx is the largest consumer (25 MUI components + 9 icons + Drawer + Table + a rich-text compose UI with formatting actions and attachments). Likely needs a sub-split to stay under the 400-line slice budget.
• Cross-slice visual drift (medium). 22 files over ~8 slices; mitigated by migrating shared building blocks first (exploration §9 slice 2) and documenting the Tailwind layout patterns up front.
• lucide-react v1 pin (low–medium). ^1.14.0 is an unusual major; the 10 mapped icon names must be verified to exist before the UsersPage slice.
• No component test harness today (medium). See exploration §11; whether to add Vitest in slice 1 is an open question.

6. High-level slice strategy

Chained PRs, ≤400 changed lines each, each leaving npm run build + npm run lint green. Full table and sequencing rationale live in exploration.md §9; summary:

1. Foundation — shadcn primitives + @tanstack/react-table, remove recharts/d3, delete theme.ts.
2. Shared components — SectionCard, SelectionRailCard, TabbedCard, MetricCard, DiskSpaceCard, HoverEditButton, DialogFooter, ConfirmDialog, LibraryOverview, NowPlaying/SessionActivityPanel.
3. Backups cluster (+ surface /backups in nav).
4. Dashboard + Applications.
5. Settings + Actions.
6. Users (largest; may sub-split).
7. DataGrid → TanStack Table — Media + FileBrowser (highest risk; last).
8. Cleanup + docs — remove @mui/* + @emotion/*, final typecheck/lint, update docs/REQUIREMENTS.md.

Slices 6 and 7 are the most likely to need sub-splitting to stay ≤400 lines.

7. Success criteria

• npm run build (tsc -b + vite build) and npm run lint green; existing node --test suites pass.
• Zero @mui/* or @emotion/* imports remain in frontend/src (verified by grep); recharts, d3, and theme.ts removed.
• Both DataGrid surfaces rebuilt on TanStack Table with pagination / row-selection / row-click / column-visibility parity.
• ObservabilityPage parity preserved (Alertmanager alerts + Prometheus target health + Grafana deep-links); no in-app charts introduced.
• Visual consistency with the migrated shell + ObservabilityPage; Backups surfaced in nav; Media/Applications naming resolved.
• docs/REQUIREMENTS.md updated to reflect the UX/architecture change.

8. Proposal question round

The following product/UX questions need user answers before this proposal is treated as locked. They are intended to uncover business rules, IA intent, and scope boundaries — not delivery mechanics. (Parent: ask these verbatim.)

Q1 — Information architecture (parent-ask): Today the sidebar lists Dashboard, Observability, Media, Files, Users, Actions, Settings — but "Media" routes to /applications (component Applications), and a working Backups page (/backups) is hidden from the nav. Do you want (a) Backups as its own top-level nav item, (b) Backups grouped under a "Media ops" section, or (c) left as URL-only? And should the Media/Applications surface be named "Media" or "Applications" going forward?

Q2 — Visual density (parent-ask): The migrated shell uses comfortable spacing (p-4 md:p-6, gap-4). Should the redesign keep comfortable density across all 22 pages, or do some dense tables (Media, Users, Backups runs) need a compact mode to fit more rows on screen?

Q3 — TanStack Table feature parity (parent-ask): The current DataGrids use column visibility; resizing and sorting usage is ambiguous. For the rebuilt tables, do you want (a) visibility-only parity (smallest scope), (b) add sorting, or (c) add sorting + column resizing (closest to a full DataGrid)?

Q4 — Test harness (parent-ask): There is no component test harness today (only tsc -b, eslint, and node --test on pure-JS transforms). Should slice 1 introduce a minimal Vitest + Testing Library harness for the migrated components, or proceed on static + manual smoke evidence per slice?

Q5 — Palette (parent-ask): The current primary is #4f8cff with chart-1..5 tokens defined but unused. Do you want to (a) keep #4f8cff and repurpose the chart tokens as Grafana-link color cues, (b) shift the primary to a new accent (please specify), or (c) keep the palette as-is and drop the unused chart tokens entirely?

---

Recommended next phase: spec — after the §8 questions are answered, refine scope/token/IA decisions and lock the slice contracts.