RolemasterDB/docs/tables_frontend_overhaul_implementation_plan.md

Tables Frontend Overhaul Implementation Plan

Purpose

This document turns the vision in 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
• 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.