xTr1m/RolemasterDB
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add tables frontend overhaul plan

Browse Source
This commit is contained in:
Frank Tovar
2026-03-21 12:54:51 +01:00
parent 6e0a899b57
commit a188aa9c63
1 changed files with 532 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

532
docs/tables_frontend_overhaul_implementation_plan.md Normal file
View File

@@ -0,0 +1,532 @@
# 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.