RolemasterDB/docs/tables_frontend_overhaul_implementation_plan.md

# Tables Frontend Overhaul Implementation Plan

## Purpose

This document turns the vision in [tables_ux_bible.md](./tables_ux_bible.md) into an execution plan for the current Blazor Web App frontend in `src/RolemasterDb.App`.

It is intentionally implementation-focused:

- clear task breakdown
- explicit acceptance criteria
- concrete definition of done
- reasonable implementation order
- minimal churn to the existing backend and API contracts

## Source Inputs

- [tables_ux_bible.md](./tables_ux_bible.md)
- current Blazor app shell and routes in `src/RolemasterDb.App/Components`
- current API and view models in `src/RolemasterDb.App/Features`

## Constraints

- keep the current tech stack
- keep the current backend and API contracts
- keep the current critical-table data model and curation workflow as the domain foundation
- treat route and UI changes as frontend/presentation refactors unless an additive backend endpoint is explicitly approved later
- keep changes incremental and shippable by phase

## Target Outcomes

The overhaul is complete when the app behaves as one coherent product with four clear destination families:

- `Play` for live lookup and fast resolution
- `Tables` for reference and inspection
- `Curation` for queue-based repair work
- `Tools` for diagnostics and API documentation

The new shell, navigation, spacing, theming, and interaction grammar must be reusable for future pages.

## Overall Definition Of Done

The frontend overhaul is done when all of the following are true:

- the app uses a shared design system with explicit light, dark, and system themes
- the primary navigation matches the UX bible and no longer reflects implementation buckets
- `/tables` is browse-first, selection-driven, and free of resting-state cell action clutter
- `Curation` is a dedicated queue-first workflow rather than ambient clutter inside `Tables`
- diagnostics and API docs are grouped under `Tools`
- `Play` and `Tables` share the same shell and interaction model
- deep links preserve object context for key user journeys
- keyboard, focus, contrast, responsive behavior, and sticky layout behavior meet the UX bible rules
- the solution is maintainable, with the current monolithic `Tables` page split into reusable components and services

## Delivery Strategy

Implement in vertical slices, not by page-wide rewrites. Each phase should leave the app in a buildable, reviewable, and partially usable state.

Recommended order:

1. foundation and shell
2. shared state and deep-link infrastructure
3. `Tables` reference experience
4. `Curation` workflow
5. `Tools` consolidation
6. `Play` alignment
7. hardening, QA, and rollout cleanup

## Phase 0: Discovery And Technical Baseline

### Goal

Create the implementation foundation so the visual overhaul does not start with uncontrolled edits in page files.

### Tasks

- `P0.1` Audit current component ownership in `Components/Layout`, `Components/Pages`, and `Components/Shared`.
- `P0.2` Identify which behaviors already exist and should be preserved:
  - selected table persistence
  - cell editor and curation dialogs
  - diagnostics selection model
  - lookup forms and result cards
- `P0.3` Define the target frontend structure for the overhaul.
- `P0.4` Decide the new route map and compatibility redirects.
- `P0.5` Define a shared frontend state strategy for:
  - theme
  - recent tables
  - pinned tables
  - selected table context
  - deep-link parsing and serialization
- `P0.6` Define component boundaries for shared primitives before major page work starts.

### Deliverables

- agreed route map
- agreed component and state boundaries
- agreed migration path from current shell and pages

### Acceptance Criteria

- every planned frontend surface has an explicit owner component or service area
- route compatibility is defined before navigation work begins
- there is a clear plan for what stays in page components versus what moves to shared services/components

### Definition Of Done

- no unresolved structural ambiguity remains around shell, routes, state ownership, or shared primitives

## Phase 1: Design System And Application Shell

### Goal

Establish the shared shell, tokens, typography, and theme system that every destination will inherit.

### Tasks

- `P1.1` Replace the current token set in `wwwroot/app.css` with a semantic token system aligned to the UX bible:
  - `--bg-*`
  - `--surface-*`
  - `--text-*`
  - `--border-*`
  - `--focus-*`
  - `--shadow-*`
  - accent ramp
  - success ramp
  - warning ramp
  - danger ramp
  - info ramp
- `P1.2` Update typography to:
  - `Fraunces` for display and section titles
  - `IBM Plex Sans` for body and UI labels
  - `IBM Plex Mono` for diagnostics and code
- `P1.3` Implement theme modes:
  - `Light`
  - `Dark`
  - `System`
- `P1.4` Persist theme preference in browser storage.
- `P1.5` Replace the current sidebar-first layout with a responsive shell:
  - top app bar on desktop
  - mobile top bar
  - mobile bottom nav
- `P1.6` Add global shell slots for:
  - app mark
  - primary destination nav
  - omnibox trigger or field
  - recent/pinned shortcut slot
  - theme/settings/help utilities
- `P1.7` Add a skip link and ensure main-content landmarks are valid.
- `P1.8` Keep tools visually separated from play-facing surfaces through styling and labeling, not a separate app.

### Deliverables

- global shell component(s)
- theme service or equivalent state holder
- revised design token layer
- updated app typography

### Acceptance Criteria

- the app no longer depends on the old permanent navigation rail for primary navigation
- theme selection survives reload
- light and dark themes are intentionally designed, not simple inversion
- sticky top navigation does not obscure page content
- the shell works at 375px, 768px, 1024px, and 1440px without horizontal overflow

### Definition Of Done

- all pages render inside the new shell
- primary navigation shows `Play`, `Tables`, `Curation`, and `Tools`
- the app has a stable theme system and global spacing/typography rules

## Phase 2: Shared Navigation, Search, And State Infrastructure

### Goal

Build the shared interaction infrastructure needed by multiple destinations before page-specific UI work deepens.

### Tasks

- `P2.1` Implement the frontend route structure:
  - keep `/`
  - keep `/tables`
  - add `/curation`
  - add `/tools`
  - move diagnostics and API docs under `/tools/...`
- `P2.2` Add compatibility redirects or navigation helpers for old `/diagnostics` and `/api` links.
- `P2.3` Implement a shared recent-items model for critical tables.
- `P2.4` Implement pinned tables state and persistence.
- `P2.5` Implement deep-link parsing and URL serialization for table context:
  - table slug
  - group key
  - column key
  - roll band or roll jump
  - selected cell result id
  - mode
- `P2.6` Build an omnibox foundation that can support:
  - table search
  - recent items
  - pinned items
  - slash commands
- `P2.7` Create shared primitives for:
  - chips
  - tabs
  - app-bar actions
  - drawers or sheets
  - inspector sections
  - status indicators
- `P2.8` Create a shared table-selection service or helper so `Tables`, `Curation`, and `Tools` do not each reinvent selection logic.

### Deliverables

- route updates
- local storage persistence helpers
- omnibox/search primitives
- shared state services/helpers

### Acceptance Criteria

- direct links into a selected table context can be opened and restored reliably
- recent and pinned tables are available to any page that needs them
- diagnostics and API docs remain reachable via new tools routes
- shared controls exist before page-specific implementations duplicate them

### Definition Of Done

- common navigation and state concerns are implemented once and consumed from shared code

## Phase 3: `Tables` Reference Experience

### Goal

Turn `/tables` into the canonical reference surface for reading and inspecting critical tables quickly.

### Tasks

- `P3.1` Split the current `Tables.razor` into smaller components:
  - page header
  - table index rail
  - sticky context bar
  - table canvas
  - inspector
  - filter and mode controls
- `P3.2` Replace the current dropdown table picker with a searchable left rail.
- `P3.3` Add table index behavior:
  - search-as-you-type
  - keyboard arrow navigation
  - enter to open
  - pinned group
  - recent group
  - all tables list
  - status chip showing curated percentage
  - optional family filters
- `P3.4` Build the sticky context bar with:
  - current table title
  - variant selector when applicable
  - roll jump input
  - optional severity focus
  - mode tabs
  - filter chips
- `P3.5` Rework the table canvas for reference reading:
  - sticky top headers
  - sticky left roll-band column
  - active row emphasis
  - active column emphasis
  - selected cell focus treatment
  - optional roll-jump marker
  - density toggle
- `P3.6` Remove resting-state button clutter from cells.
- `P3.7` Move cell actions to a selection-driven inspector and optional compact selected-cell affordances.
- `P3.8` Build the right inspector on desktop and bottom-sheet inspector on mobile.
- `P3.9` Rework legend/help so it is on-demand and secondary to the canvas.
- `P3.10` Hide maintenance and developer noise in default `Reference` mode.
- `P3.11` Preserve the current full editor and curation entry points, but expose them from the inspector instead of per-cell button stacks.
- `P3.12` Ensure one-tap or one-click selection works the same on desktop and touch.

### Deliverables

- new `Tables` page composition
- left rail selector
- sticky context bar
- selection-driven inspector
- deep-link-aware table state

### Acceptance Criteria

- a user can open a table in one search action from the index rail or omnibox
- a user can jump to a roll using a dedicated roll field
- the selected row, column, and cell are visually obvious
- a result can be read without opening a modal
- no action in `Tables` depends on hover-only discovery
- non-selected cells remain visually quiet
- mobile keeps the same task model using sheets instead of a persistent inspector

### Definition Of Done

- `/tables` is browse-first, not edit-first
- the grid is visually dominant and the inspector is secondary
- resting cells contain state hints, not visible action stacks

## Phase 4: `Curation` Workflow Surface

### Goal

Create a dedicated queue-first curation workflow so repair work is fast and does not pollute the reference experience.

### Tasks

- `P4.1` Create the new `/curation` page and route.
- `P4.2` Reuse shared table/context selection patterns from Phase 2 and Phase 3.
- `P4.3` Define queue scopes:
  - all tables
  - selected table
  - pinned set
- `P4.4` Build a stable queue-first layout with:
  - current queue item summary
  - source image
  - parsed preview
  - quick parse area
  - save-and-advance actions
- `P4.5` Move the current “next uncurated” logic into the dedicated workflow surface.
- `P4.6` Keep full editor access available, but make quick parse and mark curated the fast path.
- `P4.7` Ensure save-and-advance keeps the user in the same workflow lane without reopening context.
- `P4.8` Use warning styling only for disruptive repair actions, not for normal save flow.
- `P4.9` Hide developer-only diagnostics from the normal curation workflow.

### Deliverables

- `/curation` page
- queue-first layout
- integrated save-and-advance flow
- quick parse in-context workflow

### Acceptance Criteria

- a curator can move from one uncurated cell to the next with one primary action after save
- source and parsed result are visible side by side on wide screens
- quick parse can be completed without opening the full editor for common cases
- `Tables` no longer carries the primary queue-work burden

### Definition Of Done

- curation is a dedicated workflow page with a stable repeated interaction loop

## Phase 5: `Tools` Consolidation

### Goal

Separate diagnostic and developer tooling from player-facing flows without losing deep-link usefulness.

### Tasks

- `P5.1` Create a `Tools` landing page.
- `P5.2` Move diagnostics to `/tools/diagnostics`.
- `P5.3` Move API documentation to `/tools/api`.
- `P5.4` Reuse shared selection and table-context patterns so tooling feels related but distinct.
- `P5.5` Add cross-links back to `Tables` and `Curation` preserving object context where possible.
- `P5.6` Keep raw JSON, parser provenance, and deep inspection limited to tooling surfaces.
- `P5.7` Style tooling surfaces with the shared system but with the subdued “cool slate” tooling emphasis defined by the UX bible.

### Deliverables

- `Tools` hub
- migrated diagnostics page
- migrated API docs page
- context-preserving navigation back into reference and curation views

### Acceptance Criteria

- diagnostics and API docs remain bookmarkable
- player-facing pages no longer expose raw payload inspection
- a developer can inspect a cell in tools and jump back to its reference or curation context

### Definition Of Done

- developer-facing tools are clearly separated in both navigation and presentation

## Phase 6: `Play` Alignment

### Goal

Make the default landing experience feel like part of the same product and connect it to the new reference surfaces.

### Tasks

- `P6.1` Reframe the current home page as `Play`.
- `P6.2` Apply the new shell, typography, spacing, token, and action hierarchy to lookup forms and results.
- `P6.3` Reorganize the page to prioritize fast resolution over dashboard-like symmetry.
- `P6.4` Add deep links from lookup outcomes into `Tables` where the user wants to inspect the underlying critical result.
- `P6.5` Ensure player-facing copy avoids maintenance terminology.
- `P6.6` Preserve current lookup behavior and contracts while improving layout, clarity, and action priority.

### Deliverables

- updated `/` page within the new shell
- unified visual and interaction system
- result-to-table deep-link paths

### Acceptance Criteria

- a lookup result can lead directly into the relevant table context
- `Play` shares the same design language as `Tables` and `Curation`
- the primary action on the page is always obvious

### Definition Of Done

- `Play` and `Tables` feel connected, not like separate demos

## Phase 7: Hardening, Accessibility, Performance, And Rollout Cleanup

### Goal

Stabilize the overhaul and ensure the final UX matches the bible under real usage conditions.

### Tasks

- `P7.1` Review keyboard reachability for all app-bar actions, chips, tabs, table index items, table cells, inspector actions, and drawers.
- `P7.2` Verify visible focus states across light and dark themes.
- `P7.3` Verify contrast and accent-vs-semantic color distinction in both themes.
- `P7.4` Test sticky headers, sticky context bars, inspectors, and sheets across target breakpoints.
- `P7.5` Verify no page content is obscured by fixed or sticky shell elements.
- `P7.6` Verify deep links round-trip correctly across `Play`, `Tables`, `Curation`, and `Tools`.
- `P7.7` Verify last-used context persistence per destination.
- `P7.8` Measure table-switch and inspector-open performance and optimize obvious hotspots.
- `P7.9` Introduce virtualization only if profiling shows it is required and sticky behavior remains intact.
- `P7.10` Remove obsolete CSS and component paths left behind by the old shell or old `/tables` flow.
- `P7.11` Update documentation to reflect the final route map and shell model.

### Deliverables

- accessibility review pass
- responsive review pass
- performance review pass
- cleaned-up documentation and obsolete styles/components removed

### Acceptance Criteria

- keyboard-only usage is viable for the major reference and curation flows
- the app has no hover-only critical actions
- mobile hit targets are at least 44x44 px on primary controls
- there is no horizontal page overflow except intentional table-canvas panning
- table switching feels fast after initial load

### Definition Of Done

- the overhaul is stable, accessible, responsive, and cleaned up for future extension

## Cross-Cutting Technical Tasks

These tasks should be scheduled alongside the phases above rather than saved for the end.

### Component Architecture

- extract new classes and services into their own files
- keep page components thin and move reusable logic into helpers/services
- favor shared components over repeated markup in page files

### State Management

- centralize local storage keys
- avoid duplicating route parsing logic across pages
- keep selection state deterministic and serializable

### Visual Consistency

- use shared button hierarchy and chip patterns
- reserve warning and danger styles for true risk states
- ensure tools, curation, and reference surfaces differ through emphasis, not through unrelated styling systems

### Accessibility

- use semantic headings in order
- use true button and link elements for interactions
- only use grid semantics if keyboard behavior matches the semantics

### Documentation

- update related docs when route names, page responsibilities, or user flows materially change

## Proposed Task Sequencing Within The Repo

This is the recommended execution order at file and module level.

1. create shared theme, shell, and app-bar primitives
2. update root app layout and route structure
3. add shared state helpers for theme, recents, pins, and deep links
4. migrate diagnostics and API routes into the `Tools` shape with compatibility handling
5. split `Tables.razor` into focused components and land the new reference mode
6. add the dedicated `Curation` page reusing shared selectors and editor flows
7. align `Home.razor` into `Play`
8. remove obsolete shell and `/tables` implementation fragments
9. complete accessibility, responsive, and performance hardening

## Milestone-Based Acceptance Summary

### Milestone A

Foundation is accepted when the new shell, theme system, and route structure are in place without breaking basic navigation.

### Milestone B

`Tables` is accepted when a gamemaster can locate a table, jump to a result, and read it without modal friction or cell-level chrome clutter.

### Milestone C

`Curation` is accepted when a curator can save and advance through a stable queue flow without using `Tables` as the primary repair surface.

### Milestone D

`Tools` is accepted when diagnostics and API documentation are grouped under tooling routes and do not pollute player-facing flows.

### Milestone E

The overhaul is fully accepted when `Play`, `Tables`, `Curation`, and `Tools` all share the same shell, theme, navigation grammar, and deep-link model.

## Non-Goals For This Plan

- changing the backend data model
- redesigning API contracts
- adding speculative admin surfaces not described in the UX bible
- introducing a new frontend framework
- forcing virtualization before actual profiling justifies it

## Recommended First Implementation Slice

Start with a narrow but high-leverage slice:

1. semantic tokens and theme persistence
2. top app bar and mobile bottom nav
3. route restructuring for `Tools`
4. shared state helpers for recents, pins, and deep links
5. extraction of `/tables` shell pieces without yet rewriting every detail of the canvas

This sequence reduces risk because it establishes the shared infrastructure before the most complex page rewrite.