` (or `flex-row`) | none needed |
| `Grid` | CSS grid `grid grid-cols-* gap-*` w/ responsive `md:`/`lg:` | none needed |
| `Chip` | `Badge` (`@/components/ui/badge`) | **present** |
| `Button` | `Button` (`@/components/ui/button`) | **present** |
| `IconButton` | `Button variant="ghost" size="icon"` (pattern already used in shell) | **present** |
| `Tooltip` | `Tooltip` (`@/components/ui/tooltip`) | **present** |
| `Alert` | `Alert`/`AlertTitle`/`AlertDescription` | **present** |
| `Select`/`MenuItem`/`FormControl`/`InputLabel` | `Select` family (`@/components/ui/select`) | **present** |
| `Paper` | `
` or `Card` | none needed |
| `Table`/`TableHead`/`TableBody`/`TableRow`/`TableCell`/`TableContainer` | shadcn `Table` family | **add** |
| `Tabs`/`Tab` | shadcn `Tabs` (`TabsList`/`TabsTrigger`/`TabsContent`) | **add** |
| `Dialog`/`DialogTitle`/`DialogContent`/`DialogActions` | shadcn `Dialog` (+ `DialogFooter`, `DialogHeader`) | **add** |
| `TextField` | `Input` (+ `Label`) | **add** |
| `Checkbox` | `Checkbox` | **add** |
| `Switch` | `Switch` | **add** |
| `LinearProgress` | `Progress` | **add** |
| `Divider` | `Separator` | **add** |
| `Avatar` | `Avatar` | **add** |
| `Drawer` | `Sheet` (side="right") — already used for mobile nav | **present** |
| `FormControlLabel` / `FormHelperText` | `Label` + `
` | **add** `Label` |
| `DataGrid` (`@mui/x-data-grid`) | TanStack Table + shadcn `Table` (see §4) | **add** `@tanstack/react-table` |
## 4. DataGrid decision — TanStack Table (KEY TECHNICAL RISK)
**Recommendation:** migrate both DataGrid usages to **`@tanstack/react-table`** (headless) styled with the shadcn `Table` primitive. Rationale: headless (no opinionated styling, fits Tailwind), first-class sorting/filtering/pagination/selection/column-visibility, actively maintained, and the project already uses `@tanstack/react-query` so the dependency family is consistent.
**Feature parity that MUST be preserved** (derived from source):
| Page | Columns (`field`) | Features in use |
|---|---|---|
| `pages/Media.tsx` | title, series, season, episode, type, year, runtime_min, size, bitrate, hdr, video, resolution, date_added, library, path | pagination, row selection, row click (opens file browser), column visibility management, stable row id |
| `pages/FileBrowser.impl.tsx` | type, name, ext, size, modified | row selection, row click (selects file for ffprobe), column visibility management |
**Open parity questions for the proposal phase:**
- Does the redesign keep client-side column *resizing*, or only *visibility*? (Source scan shows visibility; resizing usage is ambiguous and must be confirmed against the live DataGrid props.)
- Sorting/filtering: Media has external controls already (its own filter UI); decide whether TanStack sorting is added or deferred to keep slice size ≤400 lines.
This is the single highest-risk slice; it is sequenced **last** so the shared Table primitive and design tokens are already settled.
## 5. shadcn primitives gap list
Add via `npx shadcn@latest add ` (project already initialised — `components.json`, `@/components/ui`, `cn()` in `src/lib/utils.ts`):
```
tabs table dialog input label checkbox switch progress separator avatar textarea dropdown-menu scroll-area
```
Plus dependency: `npm i @tanstack/react-table`.
Already present (do not re-add): `button tooltip sheet card badge alert select skeleton collapsible`.
## 6. Design tokens, theming, and redesign direction
**Current tokens (`frontend/src/index.css`, Tailwind v4 `@theme`)** — already a complete shadcn-style system:
- Font: Inter (300–700 via Google Fonts).
- Light: background `#fafafa`, foreground `#0f172a`, card `#ffffff`, primary `#4f8cff`, border `#e2e8f0`, muted-foreground `#64748b`.
- `.dark`: background `#0f172a`, card `#1e293b`, border `#334155`, muted-foreground `#94a3b8`.
- Radius `0.625rem`. Chart palette `chart-1..5` defined but **unused** (no charting) — keep for Grafana-link color cues, or drop.
- Dark mode: `useDarkMode()` in `App.tsx` toggles `.dark` on ``; `theme.ts` is a no-op shim.
**Config:** `frontend/tailwind.config.cjs` is minimal (`content` glob only) — correct for Tailwind v4 which reads tokens from `@theme` in CSS. No JS theme config to migrate.
**Redesign direction (consistent with shell + ObservabilityPage):**
- **Density:** comfortable, not cramped. Page padding `p-4 md:p-6` (matches `` in `App.tsx`). Card gap `gap-4`. Section spacing via `SectionCard` replacement.
- **Typography ramp:** headings `text-lg font-semibold` (page title, per `TopBar`), section titles `text-base font-semibold`, body `text-sm`, captions `text-xs text-muted-foreground`.
- **Color semantics:** status uses Badge variants — `default` (info), `secondary` (neutral), `destructive` (error/firing alert), and a success variant to add for healthy/OK (currently only ObservabilityPage has health semantics). Keep primary blue `#4f8cff`.
- **Surfaces:** prefer `Card` over ad-hoc `Paper`; one border weight (`border-border`), one radius (`rounded-lg`).
- **Layout primitive:** replace MUI `Grid`/`Stack` with a small set of Tailwind patterns documented in the design doc so all 22 files stay consistent across slices.
## 7. Information architecture & navigation
**Current nav (`App.tsx` `navItems`):** Dashboard (`/`), Observability (`/observability`), Media (`/applications`), Files (`/files`), Users (`/users`), Actions (`/actions`), Settings (`/settings`).
**Routing facts:**
- `/monitoring` → `` (legacy redirect).
- `/media` → `Applications` (alias).
- `/backups` route **exists** (`BackupsPage`) but is **not in the sidebar** — reachable only by URL or via the Dashboard widget's deep-link.
**IA recommendations for the proposal:**
- Surface **Backups** in the nav (currently hidden) — either its own item or folded into a "Media ops" group.
- Reconcile the **Media ↔ Applications** naming (nav says "Media", route is `/applications`, page component is `Applications`); pick one name.
- Keep Observability as a first-class top-level item (it is the post-decoupling home for status + Grafana links).
## 8. Observability-decoupling implications for the redesign
- **Stays in-app:** Alertmanager alerts list, Prometheus target health table, monitoring-machine status, Grafana deep-link cards (kiosk iframe URLs + Explore). All already implemented in `ObservabilityPage.tsx`.
- **Becomes / stays a Grafana deep-link:** any metric chart, time-series, log stream. The `chart-1..5` tokens and orphaned `recharts`/`d3` deps are leftovers from the removed in-app Monitoring UI — removing them codifies the decoupling.
- **Design consequence:** no chart components need to be designed; "metric" surfaces become either a number (MetricCard) or an outbound Grafana link. The redesign should make the **external-link affordance** consistent (lucide `ExternalLink`, already used in `ObservabilityPage`).
## 9. Slice plan preview (Force-chained, ≤400 changed lines/PR)
Sequenced so each slice leaves `npm run build` + `npm run lint` green and is independently reviewable:
1. **Foundation** — add shadcn primitives (§5), add `@tanstack/react-table`, remove `recharts`+`d3` from `package.json`, delete `theme.ts`. Enables all later slices.
2. **Shared components** — migrate the reusable building blocks first to prevent drift: `SectionCard`, `SelectionRailCard`, `TabbedCard`, `MetricCard`, `DiskSpaceCard`, `HoverEditButton`, `DialogFooter`, `ConfirmDialog`, `LibraryOverview`, `NowPlaying`/`SessionActivityPanel`.
3. **Backups cluster** — `BackupAlertsTable`, `BackupJobsTable`, `BackupRunsTable`, `BackupsPage`, `BackupDashboardWidget` (+ surface `/backups` in nav).
4. **Dashboard + Applications** — `Dashboard.tsx`, `Applications.tsx`.
5. **Settings + Actions** — `Settings.tsx`, `Actions.tsx`.
6. **Users** — `UsersPage.impl.tsx` (largest MUI consumer: 25 components + 9 icons + Drawer + Table + rich-text compose). May sub-split.
7. **DataGrid → TanStack Table** — `Media.tsx` + `FileBrowser.impl.tsx` (highest risk; sequenced last).
8. **Cleanup + docs** — remove `@mui/*` + `@emotion/*` deps, final typecheck/lint pass, update `docs/REQUIREMENTS.md`.
~8 slices; slices 6 and 7 are the most likely to need sub-splitting at apply time to stay under 400 lines.
## 10. Risks & open questions for the proposal
1. **DataGrid parity (high)** — TanStack Table must reproduce pagination/selection/row-click/column-visibility; resizing/sorting scope undecided (§4).
2. **UsersPage size (high)** — single largest migration; rich-text compose UI with formatting actions, attachments, drawer, table. Needs its own careful slice (possibly split).
3. **Cross-slice visual drift (medium)** — 22 files migrated over 8 slices; mitigated by doing shared components (slice 2) and documenting the Tailwind layout patterns in the design doc first.
4. **lucide-react v1 pin (low–medium)** — unusual major (`^1.14.0`); verify all 10 mapped icon names exist before the UsersPage slice.
5. **Form patterns (low)** — current forms are uncontrolled/`useState`; keep parity, no form library introduction (non-goal).
6. **IA decisions (product)** — Backups nav placement, Media/Applications naming (§7).
7. **Testing coverage (medium)** — see §11; no component test harness exists today.
## 11. Testing strategy note
- `frontend/package.json` has **no `test` script**. Capability today:
- `npm run build` → `tsc -b && vite build` (typecheck + build).
- `npm run lint` → `eslint .`.
- `node --test` on `frontend/tests/*.mjs` (`users.test.mjs`, `userState.test.mjs`) — pure-JS transform tests, run directly, not wired into npm.
- `openspec/config.yaml` declares **no strict-TDD flag**.
- **Implication:** "green" for each slice = `tsc -b` clean + `eslint` clean + existing `node --test` suites pass + manual smoke of the affected page. The proposal should decide whether to introduce a minimal component test harness (e.g. Vitest + Testing Library) as slice 1 work, or proceed on static + smoke evidence only.
---
**Status:** explore complete. **Recommended next phase:** `proposal` (with a product-question round before locking, given redesign + IA ambiguity).