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

# Web UI Specification

> Change: `web-ui-rework` · Domain: `web-ui` · Phase: **spec**
> Grounded in `openspec/changes/web-ui-rework/proposal.md` and `exploration.md` (verified inventory).
> Locked product decisions encoded as requirements: IA (Backups top-level; surface named "Media" at `/media` with `/applications` → redirect), TanStack visibility-only table parity, palette (`#4f8cff` kept + `chart-1..5` repurposed), comfortable density, Vitest harness in slice 1.

## Purpose

Define WHAT must be true of the Manage web frontend after the rework: a single coherent UI on **shadcn/ui + Tailwind v4 + lucide-react**, a **thin-dashboard** observability model (no in-app charts; Grafana deep-links preserved), **TanStack Table** data grids with **visibility-only** parity, a **reconciled information architecture**, and **zero** MUI/`@emotion`/`recharts`/`d3`/`theme.ts` residue — delivered as a chain of build-and-lint-green slices. This spec is acceptance-focused and verifiable; it deliberately does not prescribe implementation.

## Requirements

### Requirement: Single design system

The frontend MUST render all surfaces using only **shadcn/ui** primitives, **Tailwind v4** `@theme` tokens, and **lucide-react** icons. The application MUST NOT introduce any additional component or styling library. The application MUST NOT retain any `@mui/*` or `@emotion/*` import.

#### Scenario: No MUI imports remain anywhere in source

- GIVEN the `web-ui-rework` change is fully applied
- WHEN a recursive search of `frontend/src` is performed for imports from `@mui/material`, `@mui/icons-material`, `@mui/x-data-grid`, `@emotion/react`, or `@emotion/styled`
- THEN the search returns zero matches
- AND `@mui/material`, `@mui/icons-material`, `@mui/x-data-grid`, `@emotion/react`, and `@emotion/styled` are absent from `frontend/package.json`

#### Scenario: No new design system adopted

- GIVEN the rework is applied
- WHEN `frontend/package.json` dependencies are inspected
- THEN no component library other than the existing shadcn/ui + Tailwind + lucide-react stack is present

### Requirement: Orphaned charting dependencies removed and no in-app charting

The frontend MUST remove the unused `recharts` and `d3` dependencies from `frontend/package.json`. The frontend MUST NOT introduce any in-app chart, time-series, or log-stream visualization component. The no-op `frontend/src/theme.ts` shim MUST be deleted. Metric surfaces MUST be expressed as numbers or outbound Grafana links only.

#### Scenario: Charting dependencies are gone

- GIVEN the final slice is applied
- WHEN `frontend/package.json` is inspected
- THEN neither `recharts` nor `d3` is listed as a dependency
- AND a recursive search of `frontend/src` for imports from `recharts`, `d3`, or `d3-*` returns zero matches

#### Scenario: No chart component is introduced

- GIVEN the rework is applied
- WHEN the migrated pages and components are inspected
- THEN no component renders an in-app chart, sparkline, or graph canvas
- AND observability metric surfaces render only as numeric values, status Badges, or outbound Grafana deep-link affordances

#### Scenario: Theme shim deleted

- GIVEN the foundation slice is applied
- WHEN the `frontend/src/theme.ts` file is checked for existence
- THEN it does not exist
- AND no import of `theme`/`getAppTheme` remains in `frontend/src`

### Requirement: Palette — primary color kept and chart tokens repurposed

The primary color MUST remain `#4f8cff`. The existing `chart-1..5` CSS tokens in `frontend/src/index.css` MUST be **repurposed** as Grafana-link and status color cues (success / info / warning / destructive / neutral) and MUST NOT be dropped from the token system. Status Badges MUST convey meaning through these semantic color cues.

#### Scenario: Primary color unchanged

- GIVEN the rework is applied
- WHEN `frontend/src/index.css` is inspected
- THEN the primary color token resolves to `#4f8cff` in both light and dark themes

#### Scenario: Chart tokens retained and repurposed

- GIVEN the rework is applied
- WHEN `frontend/src/index.css` is inspected
- THEN the `chart-1` through `chart-5` tokens are still defined
- AND they are documented/applied as Grafana-link and status semantic cues (success / info / warning / destructive / neutral)
- AND status Badges draw their variant colors from these cues

### Requirement: Comfortable visual density across all surfaces

The redesign MUST use comfortable density on every surface: page padding `p-4 md:p-6` (matching the migrated shell `<main>`) and card spacing `gap-4`. The application MUST NOT introduce a compact or dense mode for any table, list, or panel.

#### Scenario: Comfortable density on every page

- GIVEN each migrated page is rendered
- WHEN the page content container is inspected
- THEN it uses comfortable padding consistent with the shell (`p-4 md:p-6`) and card gaps (`gap-4`)

#### Scenario: No compact mode

- GIVEN the rework is applied
- WHEN the frontend is inspected for a density/compact toggle or compact spacing classes on tables
- THEN no compact or dense mode exists for Media, Users, Backups runs, or any other surface

### Requirement: Status Badge semantics

The Badge component MUST provide variants that cover success (healthy/OK), info (default), neutral (secondary), warning, and destructive (error / firing alert). Status displays across Backups, Observability, and Users MUST map status values to these variants consistently.

#### Scenario: Healthy status uses a success cue

- GIVEN a monitoring target or backup run is in a healthy/OK state
- WHEN its status is rendered
- THEN it displays a Badge using the success color cue (mapped from the repurposed `chart-*` tokens)

#### Scenario: Firing alert uses a destructive cue

- GIVEN an Alertmanager alert is firing
- WHEN its status is rendered
- THEN it displays a destructive Badge

### Requirement: Information architecture — Backups as a top-level navigation item

The **Backups** surface MUST be exposed as a top-level navigation item in the sidebar, linking to the existing `/backups` route.

#### Scenario: Backups is reachable from the sidebar

- GIVEN the application shell is rendered
- WHEN the sidebar navigation items are inspected
- THEN a top-level "Backups" item is present
- AND selecting it navigates to `/backups` and renders the Backups page

### Requirement: Information architecture — Media surface naming and route reconciliation

The Media/Applications surface MUST be named **"Media"** going forward, and its canonical route MUST be `/media`. The legacy `/applications` route MUST redirect (replace) to `/media`, mirroring the existing `/monitoring` → `/observability` redirect pattern. This change MUST NOT alter the OIDC authentication model or the `react-router-dom` routing structure beyond the renamed nav item, the `/media` route, and the `/applications` redirect.

#### Scenario: Media route is the canonical entry

- GIVEN the rework is applied
- WHEN the sidebar "Media" item is selected
- THEN the browser navigates to `/media`
- AND the Media/Applications surface is rendered under the name "Media"

#### Scenario: Legacy /applications redirects to /media

- GIVEN the application is running
- WHEN a user navigates directly to `/applications`
- THEN the client router issues a replace redirect to `/media`
- AND the Media surface is rendered (same pattern as `/monitoring` → `/observability`)

#### Scenario: Auth and routing model unchanged

- GIVEN the rework is applied
- WHEN the authentication and routing setup is inspected
- THEN the OIDC flow (`auth.ts`, `react-oidc-context`) and the `react-router-dom` structure are unchanged
- AND only nav items, the `/media` route, and the `/applications` redirect differ from the prior state

### Requirement: TanStack Table — visibility-only parity (no sorting, no resizing)

The Media and FileBrowser data grids MUST be rebuilt on `@tanstack/react-table` styled with the shadcn `Table` primitive, reproducing **only** the features currently in use: **column visibility management**, **pagination** (where present), **row selection**, and **row click**. This is **visibility only** parity — the smallest DataGrid scope — and the rebuilt tables MUST NOT add column sorting, and MUST NOT add column resizing.

#### Scenario: No sorting added

- GIVEN the rebuilt Media and FileBrowser tables are rendered
- WHEN the table headers and column definitions are inspected
- THEN no sortable-column behavior is present
- AND no sort affordance is rendered

#### Scenario: No column resizing added

- GIVEN the rebuilt Media and FileBrowser tables are rendered
- WHEN the column edges are inspected
- THEN no column-resize handles or resizing behavior are present

### Requirement: TanStack Table — column visibility management preserved

Both rebuilt tables MUST preserve the existing column-visibility management behavior, allowing the same set of columns to be shown or hidden as before the rework.

#### Scenario: Column visibility works on Media

- GIVEN the rebuilt Media table is rendered
- WHEN a user toggles the visibility of a column
- THEN that column is shown or hidden accordingly
- AND the set of toggleable columns matches the pre-rework DataGrid columns (title, series, season, episode, type, year, runtime, size, bitrate, hdr, video, resolution, date_added, library, path)

#### Scenario: Column visibility works on FileBrowser

- GIVEN the rebuilt FileBrowser table is rendered
- WHEN a user toggles the visibility of a column
- THEN that column is shown or hidden accordingly
- AND the set of toggleable columns matches the pre-rework columns (type, name, ext, size, modified)

### Requirement: TanStack Table — pagination preserved where present

The Media table MUST preserve its pagination behavior (page-size selection, total-count display, and page navigation) as it existed in the pre-rework DataGrid.

#### Scenario: Media pagination parity

- GIVEN the rebuilt Media table is rendered with more rows than one page
- WHEN a user changes the page size and navigates between pages
- THEN the visible rows, total count, and page index update consistently with the pre-rework behavior

### Requirement: TanStack Table — row selection preserved

The rebuilt tables MUST preserve their existing row-selection behavior (checkbox selection model) where it existed pre-rework.

#### Scenario: Row selection works on Media

- GIVEN the rebuilt Media table is rendered
- WHEN a user selects and deselects rows via the selection control
- THEN the selection state is maintained across pagination and matches the pre-rework row-selection model

#### Scenario: Row selection works on FileBrowser

- GIVEN the rebuilt FileBrowser table is rendered
- WHEN a user selects rows via the selection control
- THEN the selection state is maintained and matches the pre-rework model

### Requirement: TanStack Table — row click behavior preserved

The rebuilt tables MUST preserve their existing row-click behavior. On Media, clicking a row MUST open the file browser at the item's path. On FileBrowser, clicking a row MUST select that file for ffprobe preview, matching the pre-rework behavior.

#### Scenario: Media row click opens file browser

- GIVEN the rebuilt Media table is rendered
- WHEN a user clicks a media row
- THEN navigation occurs to the file browser targeted at the clicked item's path, as before the rework

#### Scenario: FileBrowser row click selects file for preview

- GIVEN the rebuilt FileBrowser table is rendered
- WHEN a user clicks a file row
- THEN that file is selected for ffprobe preview, as before the rework

### Requirement: Observability parity preserved (thin dashboard)

The Observability surface MUST continue to render Alertmanager alerts, Prometheus target health, monitoring-machine status, and Grafana deep-link cards (kiosk iframe URLs and Explore links). The rework MUST NOT introduce any in-app chart, and MUST preserve all existing Grafana deep-link affordances.

#### Scenario: Alerts and target health still shown

- GIVEN the Observability page is rendered
- WHEN Alertmanager and Prometheus data are available
- THEN Alertmanager alerts and Prometheus target health are displayed as before the rework

#### Scenario: Grafana deep-links preserved

- GIVEN the Observability page is rendered
- WHEN a Grafana deep-link card is inspected
- THEN the outbound kiosk/explore URL with instance variables is preserved
- AND an external-link affordance is present and consistent across the surface

#### Scenario: No in-app chart on observability

- GIVEN the Observability page is rendered
- WHEN metric surfaces are inspected
- THEN no in-app chart is rendered; metrics are numbers, status Badges, or Grafana deep-links only

### Requirement: Component test harness introduced and maintained

Slice 1 MUST introduce a **Vitest** + **@testing-library/react** component test harness. Every component migrated by this rework MUST have real component tests asserting the migrated behavior. The existing `node --test` suites in `frontend/tests` (e.g. `users.test.mjs`, `userState.test.mjs`) MUST continue to run and pass.

#### Scenario: Vitest harness is present

- GIVEN the foundation slice is applied
- WHEN `frontend/package.json` and config are inspected
- THEN Vitest and `@testing-library/react` are installed
- AND a Vitest test script is configured

#### Scenario: Migrated components have component tests

- GIVEN a slice migrates a component
- WHEN that slice is applied
- THEN at least one component test exercising the migrated behavior exists and passes

#### Scenario: Legacy node:test suites keep passing

- GIVEN the rework is applied
- WHEN the `frontend/tests/*.mjs` suites are executed with `node --test`
- THEN all pre-existing assertions still pass

### Requirement: Per-slice build and lint green gate

Every slice in the delivery chain MUST leave `npm run build` (which runs `tsc -b` then `vite build`) and `npm run lint` (eslint) green as a hard, non-negotiable gate. No slice may be merged with a failing build or lint.

#### Scenario: A slice leaves the build green

- GIVEN any slice in the chain is applied in isolation
- WHEN `npm run build` is executed in `frontend/`
- THEN the command exits successfully with no TypeScript or Vite errors

#### Scenario: A slice leaves lint green

- GIVEN any slice in the chain is applied in isolation
- WHEN `npm run lint` is executed in `frontend/`
- THEN the command exits successfully with no eslint errors

### Requirement: Eight-slice delivery strategy (per-slice scope and gate)

The rework MUST be delivered as the chained eight-slice strategy at the requirement level, with each slice independently reviewable and leaving build + lint green: (1) **Foundation** — add the missing shadcn primitives and `@tanstack/react-table`, remove `recharts`/`d3`, delete `theme.ts`, introduce the Vitest harness; (2) **Shared components** — migrate the reusable building blocks (`SectionCard`, `SelectionRailCard`, `TabbedCard`, `MetricCard`, `DiskSpaceCard`, `HoverEditButton`, `DialogFooter`, `ConfirmDialog`, `LibraryOverview`, `NowPlaying`/`SessionActivityPanel`); (3) **Backups cluster** (and surface `/backups` in nav); (4) **Dashboard + Media/Applications surface**; (5) **Settings + Actions**; (6) **Users** (largest consumer; may sub-split); (7) **DataGrid → TanStack Table** (Media + FileBrowser; highest risk, sequenced last); (8) **Cleanup + docs** — remove `@mui/*` + `@emotion/*`, final typecheck/lint pass, update `docs/REQUIREMENTS.md`.

#### Scenario: Foundation slice enables later slices

- GIVEN slice 1 is applied
- WHEN the shared primitives, `@tanstack/react-table`, Vitest harness are present and `recharts`/`d3`/`theme.ts` are removed
- THEN `npm run build` and `npm run lint` are green and the foundation is in place for subsequent slices

#### Scenario: Backups slice surfaces nav

- GIVEN slice 3 is applied
- WHEN the Backups cluster is migrated
- THEN the `/backups` route is reachable as a top-level nav item and the build + lint are green

#### Scenario: Final cleanup slice removes all MUI

- GIVEN slice 8 is applied
- WHEN a recursive search for `@mui/*` and `@emotion/*` imports is performed in `frontend/src`
- THEN zero matches remain
- AND the cleanup slice leaves build + lint green

### Requirement: Documentation updated to reflect the new UX and architecture

`docs/REQUIREMENTS.md` MUST be updated to reflect the post-rework UX and architecture (single design system, thin-dashboard observability, TanStack tables, reconciled IA, removed dependencies).

#### Scenario: Requirements doc reflects the rework

- GIVEN the final slice is applied
- WHEN `docs/REQUIREMENTS.md` is inspected
- THEN it documents the shadcn/ui + Tailwind + lucide-react stack, the thin-dashboard observability model (no in-app charts), the `/media` route with `/applications` redirect, the Backups top-level nav item, and the removal of MUI/`@emotion`/`recharts`/`d3`

### Requirement: No backend API or frontend data-contract changes

The rework MUST NOT change any backend API contract or any type in `frontend/src/types/*`. If a UI simplification forces a contract change, that change MUST be flagged separately and approved outside this spec.

#### Scenario: Frontend data contracts unchanged

- GIVEN the rework is applied
- WHEN `frontend/src/types/*` and the backend API surface are compared to the pre-rework state
- THEN no backend endpoint, response shape, or shared frontend type is altered by this change (unless a separate, flagged change is approved)