From a188aa9c6301b198becba475f759b6c931f24da0 Mon Sep 17 00:00:00 2001 From: Frank Tovar Date: Sat, 21 Mar 2026 12:54:51 +0100 Subject: [PATCH] Add tables frontend overhaul plan --- ...s_frontend_overhaul_implementation_plan.md | 532 ++++++++++++++++++ 1 file changed, 532 insertions(+) create mode 100644 docs/tables_frontend_overhaul_implementation_plan.md diff --git a/docs/tables_frontend_overhaul_implementation_plan.md b/docs/tables_frontend_overhaul_implementation_plan.md new file mode 100644 index 0000000..a832be8 --- /dev/null +++ b/docs/tables_frontend_overhaul_implementation_plan.md @@ -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.