manage/openspec/specs/web-ui/spec.md

Web UI

Domain: web-ui · Canonical specification. Synced from change web-ui-rework.

This is the merged end-state of the Manage web-frontend rework. It captures the durable, post-change contracts (the rework's end-state), not the migration steps. The per-slice delivery strategy and per-slice build/lint gate were part of the change's migration process and are intentionally not carried into this canonical spec; they remain in the change record (spec.md / tasks.md) under openspec/changes/web-ui-rework/.

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 a visibility-only feature set (no sorting, no resizing), a reconciled information architecture, and zero @mui/* / @emotion/* / recharts / d3 / theme.ts residue. This spec is acceptance-focused and verifiable; it deliberately does not prescribe implementation.

Requirements

Requirement: Single design system

The frontend MUST render every surface using only shadcn/ui primitives, Tailwind v4 @theme tokens (configured in frontend/src/index.css), and lucide-react icons. The application MUST NOT introduce any additional component or styling library, and MUST NOT retain any @mui/* or @emotion/* import or dependency.

Scenario: No MUI or Emotion remains in source or dependencies

• 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 none of @mui/material, @mui/icons-material, @mui/x-data-grid, @emotion/react, or @emotion/styled is listed in frontend/package.json

Scenario: No additional design system adopted

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

Requirement: No in-app charting and orphaned charting dependencies removed

The frontend MUST NOT render any in-app chart, sparkline, time-series canvas, or log-stream visualization. The unused recharts and d3 dependencies MUST be absent from frontend/package.json, and the no-op frontend/src/theme.ts shim MUST be deleted. Observability metric surfaces MUST be expressed only as numeric values, status Badges, or outbound Grafana deep-link affordances.

Scenario: Charting dependencies are gone

• GIVEN the rework 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 exists

• 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 metric surfaces render only as numeric values, status Badges, or outbound Grafana deep-links

Scenario: Theme shim removed

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

Requirement: Design tokens — primary color and repurposed status cues

The primary color MUST resolve to #4f8cff in both the light and dark themes. The existing chart-1 through chart-5 CSS tokens in frontend/src/index.css MUST be retained and documented as the single source of truth for status / Grafana-link semantic color cues (info / success / warning / destructive / neutral-accent), and MUST NOT be dropped. The Badge component MUST expose success and warning variants that draw color from these 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 the @theme (light) and .dark blocks

Scenario: Chart tokens retained and semantically repurposed

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

Requirement: Comfortable visual density with no compact mode

Every surface MUST use comfortable density: 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 exists

• 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 semantic variants

The Badge component MUST provide variants covering 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 via the repurposed chart-* cues.

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 (from chart-2)

Scenario: Firing alert uses a destructive cue

• GIVEN an Alertmanager alert is firing
• WHEN its status is rendered
• THEN it displays a destructive Badge (from chart-4)

Requirement: Information architecture — Backups top-level navigation

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 route and legacy redirects

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. The OIDC authentication model and the react-router-dom routing structure MUST be otherwise unchanged.

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 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: Data tables use TanStack Table with visibility-only features

The Media and FileBrowser data grids MUST be built on @tanstack/react-table behind a shared DataTable wrapper styled with the shadcn Table primitive. The rebuilt tables MUST reproduce only the features in use: column visibility, pagination (where present), row selection, and row click. The 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 getSortedRowModel, sortable-column behavior, or sort affordance is present

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: Data table interaction parity preserved

The rebuilt tables MUST preserve their pre-rework interaction behavior: column visibility (Media's 15 columns and FileBrowser's 5 columns), pagination (Media, server-driven via the query layer), row selection, and row click.

Scenario: Column visibility preserved

• GIVEN the rebuilt tables are rendered
• WHEN a user toggles the visibility of a column
• THEN on Media the toggleable columns match title, series, season, episode, type, year, runtime, size, bitrate, hdr, video, resolution, date_added, library, path
• AND on FileBrowser the toggleable columns match type, name, ext, size, modified

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 (page index/size drive the query layer's limit/offset)

Scenario: Row selection preserved

• GIVEN the rebuilt tables are 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 model

Scenario: Row click behavior preserved

• GIVEN the rebuilt tables are rendered
• WHEN a user clicks a Media row
• THEN navigation occurs to the file browser at the clicked item's path
• AND WHEN a user clicks a FileBrowser row
• THEN that file is selected for ffprobe preview

Requirement: Thin-dashboard observability parity

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 with Alertmanager and Prometheus data 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 a consistent external-link affordance is present 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: Frontend component test harness

A Vitest + @testing-library/react component test harness MUST be present and configured. Migrated components MUST be covered by behavioral component tests. The legacy frontend/tests/*.mjs node --test suites MUST continue to run and pass.

Scenario: Vitest harness is present

• GIVEN the rework 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: 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: Documentation reflects the post-rework architecture

docs/REQUIREMENTS.md MUST reflect the post-rework UX and architecture: the single design system (shadcn/ui + Tailwind + lucide-react), the thin-dashboard observability model (no in-app charts), TanStack tables, the /media route with /applications redirect, the Backups top-level nav item, and the removal of @mui/*, @emotion/*, recharts, and d3.

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 removed dependencies

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 and approved separately.

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