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

Exploration — web-ui-rework

Phase: explore. Evidence-grounded mapping of the rework surface. No code changes. Recovered by the orchestrator after the sdd-explore subagent hit an MCP-bridge heap OOM; all figures below were re-derived directly from source with multiline-aware parsing and verified with grep.

1. Scope and non-goals

In scope

• Finish the MUI v9 → shadcn/ui + Tailwind CSS + lucide-react migration for every remaining @mui/* consumer in frontend/src.
• Deliver a visual/UX redesign on top of the migrated primitives, consistent with the already-migrated style references: frontend/src/App.tsx (shell + sidebar) and frontend/src/components/ObservabilityPage.tsx.
• Align the UI to the new observability model: Manage is a thin dashboard; charts/metrics/logs live in external, decoupled Grafana. In-app surfaces show Alertmanager alerts + Prometheus target health + Grafana deep-links only.
• Remove orphaned charting deps (recharts, d3) and the no-op theme.ts shim.
• Add the missing shadcn primitives and @tanstack/react-table needed for the migration.
• Update docs/REQUIREMENTS.md to reflect the UX/architecture change (per AGENTS.md).

Non-goals

• No in-app charting. Do not re-introduce recharts/d3 or build custom charts; metrics visualisation stays in Grafana.
• No new design system. Use shadcn/ui + the existing Tailwind v4 @theme token system; do not adopt a different component library.
• No backend API changes as part of this rework. The data contracts in frontend/src/types/* are unchanged unless a UI simplification forces one, which must then be flagged separately.
• No MUI retention. @mui/material, @mui/icons-material, @mui/x-data-grid, @emotion/react, @emotion/styled are all removed by the final slice.
• No auth/routing model change. OIDC flow (auth.ts, react-oidc-context) and react-router-dom structure stay as-is; only nav items/IA may shift.

2. Extended component inventory (verified from source)

Parsing note: MUI imports are multiline (import {\n Box,\n Card,\n} from "@mui/material"); figures below use a brace-bounded multiline parser and were cross-checked with grep -rlE '@mui/(material|icons-material|x-data-grid)' src.

2a. @mui/material — 22 files, 37 distinct components

File	#	Components
pages/UsersPage.impl.tsx	25	Alert, Avatar, Box, Button, Checkbox, Chip, Dialog, DialogActions, DialogContent, DialogTitle, Divider, Drawer, IconButton, LinearProgress, Paper, Stack, Table, TableBody, TableCell, TableContainer, TableHead, TableRow, TextField, Tooltip, Typography
pages/Dashboard.tsx	20	Alert, Box, Button, Card, CardContent, Chip, Dialog, DialogContent, DialogTitle, FormControl, FormControlLabel, FormHelperText, Grid, InputLabel, MenuItem, Select, Stack, Switch, TextField, Typography
pages/Actions.tsx	19	Alert, Box, Button, Card, CardContent, Chip, Dialog, DialogContent, DialogTitle, Divider, FormControl, InputLabel, MenuItem, Select, Stack, Tab, Tabs, TextField, Typography
pages/Settings.tsx	18	Alert, Box, Button, Card, CardContent, Checkbox, Chip, Dialog, DialogContent, DialogTitle, FormControlLabel, Grid, MenuItem, Stack, Switch, Tab, TextField, Typography
pages/FileBrowser.impl.tsx	15	Alert, Box, Button, Card, CardContent, Chip, FormControl, Grid, InputLabel, MenuItem, Select, Stack, Tab, TextField, Typography
pages/Media.tsx	14	Alert, Box, Button, Card, CardContent, FormControl, Grid, InputLabel, LinearProgress, MenuItem, Select, Stack, TextField, Typography
components/BackupRunsTable.tsx	12	Chip, FormControl, InputLabel, MenuItem, Paper, Select, Table, TableBody, TableCell, TableContainer, TableHead, TableRow
components/SessionActivityPanel.tsx	10	Button, Chip, Paper, Table, TableBody, TableCell, TableContainer, TableHead, TableRow, Typography
components/BackupAlertsTable.tsx	9	Button, Chip, Paper, Table, TableBody, TableCell, TableContainer, TableHead, TableRow
pages/Applications.tsx	9	Alert, Box, Card, CardContent, Chip, Grid, Stack, Tab, Typography
components/BackupJobsTable.tsx	8	Chip, Paper, Table, TableBody, TableCell, TableContainer, TableHead, TableRow
components/DiskSpaceCard.tsx	7	Box, Card, CardContent, Grid, LinearProgress, Stack, Typography
components/BackupDashboardWidget.tsx	5	Box, Card, CardContent, Chip, Typography
components/ConfirmDialog.tsx	5	Dialog, DialogContent, DialogTitle, Stack, Typography
components/LibraryOverview.tsx	5	Card, CardContent, Grid, Stack, Typography
components/SectionCard.tsx	5	Box, Card, CardContent, Stack, Typography
components/BackupsPage.tsx	4	Box, Tab, Tabs, Typography
components/SelectionRailCard.tsx	4	Box, Card, CardContent, Typography
components/TabbedCard.tsx	4	Box, Card, CardContent, Tabs
components/DialogFooter.tsx	3	Box, Button, DialogActions
components/MetricCard.tsx	3	Card, CardContent, Typography
components/HoverEditButton.tsx	1	IconButton

Component frequency (migration sizing): Typography 16 · Box 14 · Card/CardContent 13 · Chip 11 · Stack 11 · Button 9 · Grid 7 · Alert 7 · MenuItem 6 · TextField 6 · Paper/Table*/FormControl/InputLabel/Select/Tab 5 · Dialog/DialogContent/DialogTitle 5 · Tabs 3 · LinearProgress 3 · DialogActions/IconButton/Divider/FormControlLabel/Switch/Checkbox 2 · FormHelperText/Avatar/Drawer/Tooltip 1.

2b. @mui/x-data-grid — 2 files (DataGrid)

• pages/Media.tsx — DataGrid, GridColDef
• pages/FileBrowser.impl.tsx — DataGrid, GridColDef, GridRowSelectionModel

2c. @mui/icons-material — 2 files, 10 distinct icons (default-import-per-icon style)

File	Icons → lucide-react equivalent
components/HoverEditButton.tsx	EditOutlined → Pencil
pages/UsersPage.impl.tsx	Close→X · AttachFile→Paperclip · FormatBold→Bold · FormatItalic→Italic · Link→Link · FormatListBulleted→List · MailOutlined→Mail · Send→Send · DeleteOutlined→Trash2

lucide caveat: package.json pins lucide-react: ^1.14.0, an unusual major. The named icons above (Pencil, X, Paperclip, Bold, Italic, Link, List, Mail, Send, Trash2) are standard lucide exports, but the version pin must be verified to export them before the UsersPage slice.

2d. Orphaned / unused deps (verified zero imports)

• recharts: ^3.8.1 — no from "recharts" anywhere. Removable.
• d3: ^7.9.0 — no from "d3" / from "d3-*" anywhere. Removable.
• frontend/src/theme.ts — no-op shim (getAppTheme returns {}); safe to delete once no caller remains.

2e. Already-migrated style references (the design targets)

• frontend/src/App.tsx — shell: fixed sidebar (w-16/w-60 collapse), TopBar (sticky, backdrop-blur, version chips), MobileDrawer (shadcn Sheet), useDarkMode toggles dark class on <html>.
• frontend/src/components/ObservabilityPage.tsx (575 lines) — uses shadcn Card/Badge/Alert/Button/Select/Skeleton/Collapsible + 12 lucide icons; Grafana deep-links via kiosk URLs (/d/node-exporter-overview/...?kiosk&var-instance=…) and Explore.

3. MUI → shadcn/ui + Tailwind mapping table

MUI	shadcn/ui + Tailwind	Primitive status
Card / CardContent	Card / CardContent (@/components/ui/card)	present
Typography	semantic <h1>–<h6>/<p>/<span> + Tailwind text-* font-*	none needed
Box	<div> + flex/grid utilities	none needed
Stack	<div className="flex flex-col gap-*"> (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	<div className="rounded-lg border bg-card"> 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 + <p className="text-xs text-muted-foreground">	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 <name> (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 <html>; 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 <main> 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 → <Navigate to="/observability" replace /> (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).