RolemasterDB/docs/player_gm_ux_redesign_plan.md

Player And Gamemaster UX Redesign Plan

Purpose

This document defines a frontend UX direction for the Rolemaster web app with players and gamemasters as the primary audience during play.

The current UI exposes too much implementation detail:

• importer ownership
• tech stack details
• import source details
• SQLite and storage details
• table counts and reference-data counts
• parse/debug fields
• raw JSON artifacts
• technical labels that matter to development but not to play

That information is useful for engineering and data curation, but it is noise during a session. The redesign should make the gameplay outcome the center of the experience and move technical detail behind developer-only tooling.

Audience Priority

Primary

• gamemasters resolving attacks and criticals quickly during a session
• players checking the resulting card and consequences without reading import metadata

Secondary

• curators repairing imported cells

Tertiary

• developers working on importer/debug workflows

The key design rule is that secondary and tertiary needs must not dominate the primary experience.

Current UX Problems

The current app structure already shows the main issues.

Home page

The current landing page in Home.razor emphasizes:

• starter dataset wording
• importer-managed wording
• attack table count
• critical table count
• armor type count
• SQLite file name

This is system status, not gameplay guidance.

Lookup result card

The current lookup card in CriticalLookupResultCard.razor exposes:

• table key
• column role
• parse status
• critical family
• source document
• roll band internals
• raw imported cell
• parsed JSON

Only a small subset of that is useful to a player or GM during play.

Critical tables page

The current tables page in Tables.razor presents the page as an importer authority surface and frames the legend, groups, columns, and full matrix primarily from a data-management perspective.

Cell editor popup

The current edit dialog in CriticalCellEditorDialog.razor exposes nearly the full persistence model, including internal fields such as:

• ParseStatus
• ParsedJson
• branch ConditionJson
• branch ParsedJson
• effect SourceType
• raw affix text everywhere

That makes the editor feel like a database inspector instead of a card editor.

Critical table cell layout

The current cell layout in CompactCriticalCell.razor and app.css already pushes affix badges downward with margin-top: auto, but branch stacks are not explicitly bottom-aligned as part of the same card layout contract. That weakens visual consistency in dense table rows.

UX Design Principles

1. Gameplay first

The first screenful must answer:

• what happened
• how many hits
• what critical applies
• what effects matter now
• what optional follow-up input is still needed

2. Remove technical noise

Do not show implementation details in player/GM flows unless the user has explicitly entered an advanced curation mode.

3. Edit the result, not the database row

When a critical cell is edited, the main object is the rendered card the user wants to fix. The underlying import/debug representation should be derived where possible, not manually curated in parallel by default.

4. Fastest common action wins

During play, the most common action is a direct resolution flow. The interface should reduce required reading, scrolling, and field-by-field interpretation.

5. Progressive disclosure

Show simple information by default. Reveal advanced detail only when the user asks for it.

6. Shared parsing logic

The same import interpretation rules should drive the import tool and the web editor. The user should not need to manually keep the raw text and normalized fields in sync.

Target Information Architecture

The application should separate into three user-facing layers.

Layer 1: Session tools

Primary navigation for live play:

• Attack lookup
• Critical lookup
• Critical tables

This layer must contain no importer/debug framing.

Layer 2: Curation tools

Accessible to advanced users:

• Edit critical cell
• Re-parse from raw text
• Compare rendered result before and after changes

This layer is still user-focused, not developer-focused.

Layer 3: Engineering diagnostics

Hidden from normal users and placed in a separate developer/admin surface:

• parse status
• parsed JSON
• source document internals
• import artifacts
• schema/debug diagnostics

Proposed UX Direction By Surface

1. Landing Page / Main Lookup

Replace the current technically framed hero with a task-first entry point.

Proposed hero

• title focused on fast resolution during play
• one sentence of instruction
• immediate access to the two main lookup actions

Remove from the hero and main summary

• tech stack references
• SQLite references
• import source references
• table counts
• importer-managed wording
• starter dataset wording
• reference-data framing

Proposed attack lookup flow

Fields:

• attack table
• armor type
• attack roll
• enemy db (attack malus)
• optional critical roll

Controls:

• resolve button
• dice button beside attack roll
• dice button beside critical roll

Behavior:

• if attack roll is present and critical roll is empty, stop after attack result
• if a critical is produced and no critical roll is entered, show a prominent next-step prompt
• if critical roll exists, show the full critical card inline

Proposed direct critical lookup flow

Fields:

• critical table
• column
• optional group, only when required
• critical roll

Controls:

• resolve button
• dice button beside critical roll

Behavior:

• hide irrelevant group controls when the selected table has no groups
• use human-readable labels, not implementation terminology

2. Lookup Result Card

The lookup card should become a gameplay card, not a parser inspection panel.

Keep visible by default

• critical table name
• chosen severity or column label
• group label when relevant
• roll used
• main prose result
• normalized effect chips
• branch cards with conditions and effects

Remove from default card

• parse status
• critical family
• source document
• column key
• column role
• raw imported cell
• parsed JSON
• roll band implementation details

Optional advanced disclosure

If advanced users still need provenance, place it behind a collapsed "Technical details" disclosure that is hidden by default and not present in the main lookup flow for ordinary users.

Visual direction

• result prose should be the dominant element
• effects should scan as chips/badges
• branch cards should read as conditional outcomes, not nested records
• warning and follow-up effects should be grouped by urgency if possible

3. Critical Tables Page

The tables browser should support reading and choosing results quickly.

Reframe the page

Current framing centers imported data. The new framing should center reading the table during play and correcting a result when necessary.

Page goals

• pick a table quickly
• scan a row and column intersection quickly
• open a clean card editor when correction is needed

Remove or demote

• importer authority language
• source-document-first labeling
• any explanation centered on how the data was loaded

Keep

• table name
• notes only if they help interpret the table in play
• affix legend because it helps users read chip meaning

Cell layout requirement

.critical-branch-stack should be bottom-aligned with .critical-cell.

Practical CSS intent:

• make .critical-cell a full-height column flex container
• reserve flexible vertical space above branches
• ensure the branch stack sits at the bottom edge of the cell card
• keep affix badges and branch cards visually anchored

This creates a stable reading rhythm across rows with uneven prose length.

4. Critical Cell Editing

The edit popup should become a compact result editor with automatic re-parse support.

Editing goal

A curator should be able to correct a result quickly in a dense popup without giving up space to a separate preview panel.

Default editor content

Show:

• raw cell text
• one-line result text editing when manual override is needed
• compact inline affix/effect rows with the same badges/icons used in read mode
• compact inline condition rows with their own effect chips

Hide from default editing:

• parse status
• parsed JSON
• condition JSON
• effect source type
• other importer/debug-only properties

Editor structure

1. Raw text input
2. Compact inline parsed sections the user can adjust
3. Save actions
4. Optional advanced diagnostics disclosure

There should be no dedicated preview panel in the popup. The edit rows themselves should carry the same affix badges, branch labels, and visible wording that the final result uses.

Re-import / re-parse behavior

When the user edits RawCellText:

• allow manual re-parse with a clear button
• optionally support debounced auto-parse after input stabilizes
• regenerate description, effects, branches, and conditions from shared parser logic
• preserve user edits only where the user explicitly overrode generated values
• surface parser notes in advanced disclosure instead of spending default popup space on them

Manual override model

A critical result should support two states:

• imported from the pdf
• raw input manually overridden and derived fields generated from raw input or also manually overridden

This avoids the current problem where re-imports using the tool discards user curations.

5. Affix Editing UX

Adding affixes should not require editing raw structured records.

Proposed interaction

• show each effect as a compact inline row with its affix badge and dropdown
• keep add/remove actions small and local to the row
• let the user choose the effect type from the same row they are editing
• show only the minimum value input needed for that effect type
• update the visible badge and label directly in the row without a separate preview area

Requirements

• chip labels must use user-facing terminology
• the affix legend and effect codes must map cleanly
• the editor should support symbol-driven and numeric affixes
• deleting an affix should be one click from the row
• do not waste space on a redundant title when the dropdown already identifies the effect
• do not show a Target field for direct_hits
• do not show a Permanent checkbox in the default editor
• keep source metadata and internal links out of the default row layout

6. Condition And Branch Editing UX

Branch editing should follow the same interaction model as affixes.

Proposed interaction

• branches render as compact inline condition rows
• include a small add button for Add condition
• user selects or types the condition text directly in the row
• user enters optional outcome prose inline
• branch effects are edited with the same compact affix rows used on the base result

Branch card contents

• condition label
• optional prose outcome
• effect chips

Remove from default branch editing

• condition JSON
• parsed JSON
• internal branch kind values unless required by the UX

If internal branch kinds remain necessary in the model, map them to friendly labels and keep raw values hidden.

7. Dice Button Support

Both lookup flows need an alternative to manual roll entry.

Automatic Attack Lookup

Add dice buttons beside:

• attack roll input
• critical roll input

Direct Critical Lookup

Add a dice button beside:

• critical roll input

Behavior

• clicking the button fills the corresponding input with a random legal value
• for attack roll, use the supported app range
• for critical roll, use 1-100
• allow reroll without extra confirmation

UX value

This supports fast table use at the table and removes the need to type known random values manually.

Shared Import Assembly Direction

The import tool and the web app should stop duplicating or bypassing import logic.

Goal

Move critical parsing, normalization, and re-parse behavior into a shared assembly consumed by both:

• RolemasterDb.ImportTool
• RolemasterDb.App

Candidate shared responsibilities

Based on the current importer structure under src/RolemasterDb.ImportTool, the shared assembly should own:

• raw cell parsing
• affix legend interpretation
• affix-to-effect normalization
• branch extraction
• condition key normalization
• parsed artifact creation for a single cell or branch
• validation rules for structurally invalid cells

Why this matters

Today the import tool is the authority for generating normalized critical content, but the web editor exposes many of the final persisted fields directly. That encourages manual edits to derived data instead of reusing the parser.

A shared assembly would allow the web app to:

• re-parse a single cell from raw text
• regenerate effects and branches consistently with bulk import
• reduce manual entry
• remove most debug/import fields from the user-facing editor

Proposed architecture

New shared project

Create a new assembly for critical import/domain transformation logic, for example:

• src/RolemasterDb.CriticalParsing

Move or extract into the shared assembly

• parsing contracts for cell-level input and output
• affix parsing logic
• branch extraction logic
• normalization helpers
• validation logic

Keep in the import tool

• CLI command surface
• manifest loading
• artifact extraction from PDFs
• batch import orchestration
• artifact writing for diagnostics

Keep in the app

• HTTP endpoints
• Blazor UI
• persistence orchestration for save/update flows

Web editor workflow after shared parsing

1. User opens a critical cell.
2. The app shows raw text and compact inline edit rows for the visible result.
3. User edits raw text.
4. The app calls shared parsing logic for that cell.
5. The parser returns normalized description, affixes, conditions, branches, and validation messages.
6. The UI updates the inline editing rows automatically.
7. The user makes small manual fixes only where generation is insufficient.
8. Save persists both raw text and the normalized result.

This is the key UX shift: the system does the import work again at cell scope instead of forcing the curator to manually edit every derived field.

Implemented Foundation

The following groundwork is already implemented in the web app as of March 15, 2026:

• visible technical chrome has been removed from the primary lookup and table flows
• lookup result cards now lead with gameplay outcome instead of parse metadata
• the critical table browser is framed for play use rather than import administration
• critical cells support re-parse from shared parser logic
• advanced diagnostics have been separated from the primary editing flow
• advanced curation now includes a generated-versus-current comparison view for re-parse review

These changes are real and complete, but they are no longer the active roadmap because the detailed acceptance checklist still has unfinished items.

Remaining Implementation Phases

Phase 1: Complete live lookup flow ergonomics

Status:

• implemented in the web app on March 15, 2026

Scope:

• add dice buttons to the attack and direct critical lookup inputs
• support fast reroll without manual typing
• tighten any remaining lookup prompts so a first-time GM can move through the flow without reading extra copy

Acceptance criteria:

• both lookup flows support random roll entry without typing
• the main lookup page fully satisfies the live-play checklist item for random lookup support

Phase 2: Compact inline cell editor

Status:

• implemented in the web app on March 15, 2026

Scope:

• remove the dedicated preview panel from the critical cell popup
• convert effect editing to dense inline rows with badges/icons and minimal controls
• convert branch editing to the same compact inline model
• remove redundant effect titles and any non-essential controls from the default edit surface

Acceptance criteria:

• the popup spends its space on actual editing rather than preview duplication
• common effect and branch corrections require less scrolling than the current popup
• direct_hits has no unused Target field in the default editor
• the default editor has no Permanent checkbox

Phase 3: Generated versus overridden state model

Status:

• implemented in the web app on March 15, 2026

Implemented model:

• result-level override flags separate generated description and collection state from manual edits
• effect rows and condition rows carry explicit origin keys plus override markers
• re-parse now merges generated parser output with the current override state instead of replacing the whole editor payload
• saved editor state is persisted so later edit sessions keep the same generated-versus-overridden boundaries

Scope:

• explicitly track which values are parser-generated and which values were manually overridden
• ensure re-parse refreshes generated values without silently discarding intentional edits
• define how save and future import refresh flows respect manual overrides

Acceptance criteria:

• shared parsing can regenerate derived data without clobbering preserved overrides
• the manual override model described in this document is implemented rather than only implied

Phase 4: Compare and review workflow

Status:

• implemented in the web app on March 15, 2026

Implemented model:

• re-parse now returns the freshly generated parser output alongside the merged editor state
• the editor captures the pre-reparse card as a review baseline before applying the merged state
• advanced curation shows side-by-side cards for the prior edit, the fresh generated parse, and the merged post-reparse result when available
• diff summary chips call out result-text, base-effect, and condition changes without requiring raw JSON inspection

Scope:

• add a clear comparison surface for generated result versus current edited result
• let curators review what changed after re-parse before accepting or keeping overrides
• keep this comparison workflow in advanced curation, not in the primary live-play path

Acceptance criteria:

• curators can inspect generated-versus-current differences without reading raw JSON first
• compare tooling exists for the override workflow described above

Phase 5: Final tooling boundary cleanup

Scope:

• verify that normal curation mode contains only user-facing correction tools
• move any remaining engineering-only diagnostics into a separate developer or admin surface if they still leak into curation mode
• leave advanced curation available without forcing ordinary users through engineering concepts

Acceptance criteria:

• the primary play flow stays clean
• compact curation remains available
• engineering diagnostics remain accessible without defining the normal correction UX

Detailed Acceptance Checklist

The redesign should be considered successful when all of the following are true.

• A first-time GM can resolve an attack or critical without reading technical copy.
• The main result card shows gameplay consequences without raw JSON or parse details.
• The critical table browser feels usable during a session, not like an import admin screen.
• Editing a critical cell starts from the rendered card and raw text, not persistence internals.
• Adding an affix or condition is a small chip-driven action.
• Shared parsing logic can regenerate most derived data from minimal raw input.
• Dice buttons support random lookup flows without manual typing.

Risks And Tradeoffs

Risk: loss of technical visibility

If technical detail is removed completely, curation becomes harder.

Mitigation:

• move technical detail to an advanced mode, not the primary mode

Risk: parser and UI divergence

If the web app implements its own light parser, it will drift from the import tool.

Mitigation:

• one shared parsing assembly
• one canonical normalized result contract

Risk: override complexity

Generated fields and manual overrides can conflict.

Mitigation:

• explicit generated vs overridden state for editable sections

Recommended Next Step

Implement Phase 5 next. The remaining cleanup is to tighten the boundary between compact curation tools and engineering diagnostics so ordinary correction workflows stay user-facing while deeper diagnostics remain available behind an explicit advanced surface.