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](D:\Code\RolemasterDB\src\RolemasterDb.App\Components\Pages\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](D:\Code\RolemasterDB\src\RolemasterDb.App\Components\Shared\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](D:\Code\RolemasterDB\src\RolemasterDb.App\Components\Pages\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](D:\Code\RolemasterDB\src\RolemasterDb.App\Components\Shared\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](D:\Code\RolemasterDB\src\RolemasterDb.App\Components\Shared\CompactCriticalCell.razor) and [app.css](D:\Code\RolemasterDB\src\RolemasterDb.App\wwwroot\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 result editor with automatic re-parse support.

### Editing goal

A curator should be able to type the minimum required raw text and let the system fill the normalized card structure automatically.

### Default editor content

Show:

- a live preview of the resulting critical card
- raw cell text
- description text when manual override is needed
- affix chips/effects
- branch cards

Hide from default editing:

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

### Editor structure

1. Result preview
2. Raw text input
3. Parsed sections the user can adjust
4. Save actions

The preview should always answer, "What card will the GM/player actually see?"

### 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

### 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 overriden

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 affixes as chips
- include a chip with a plus icon
- clicking the plus chip opens a compact inline editor
- user chooses the affix type from a dropdown
- user enters the numeric value or expression when needed
- saving immediately creates the new chip

### 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 chip

### 6. Condition And Branch Editing UX

Branch editing should follow the same interaction model as affixes.

### Proposed interaction

- branches render as condition cards
- include a plus chip or plus button for "Add condition"
- user selects condition type from a dropdown
- user enters the condition value or free text when required
- the branch card is created immediately

### 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](D:\Code\RolemasterDB\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 the rendered card preview and raw text input.
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 card preview 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.

## Proposed Rollout Phases

### Phase 1: Strip visible technical noise

Status:

- implemented in the web app on March 15, 2026

Scope:

- simplify home page copy
- simplify lookup result card
- remove technical metadata from default visible surfaces

Acceptance criteria:

- no SQLite/import/debug references in primary play flows
- lookup result card shows gameplay outcome first

### Phase 2: Clean up critical table browsing

Status:

- implemented in the web app on March 15, 2026

Scope:

- reframe tables page around reading and selecting outcomes
- bottom-align branch stacks inside critical cells
- keep the affix legend but present it as play help, not import metadata

Acceptance criteria:

- dense table rows remain visually aligned
- the page reads as a usable table browser during play

### Phase 3: Redesign the cell editor

Status:

- implemented in the web app on March 15, 2026

Scope:

- add live result preview
- remove parse/debug/import fields from default editing
- add chip-based affix and condition editing

Acceptance criteria:

- editing focuses on the resulting card
- common corrections require materially less scrolling and fewer fields

### Phase 4: Shared parsing assembly

Scope:

- extract shared parser/normalizer logic from the import tool
- consume it from the web app
- support single-cell re-parse from raw text

Acceptance criteria:

- import tool and web app produce the same normalized result for equivalent raw cell input
- raw text changes can regenerate card fields automatically

### Phase 5: Advanced curation and diagnostics split

Scope:

- move debug/import details into a separate advanced surface
- optionally add diff/compare tools for generated vs overridden values

Acceptance criteria:

- primary editing surface stays clean
- engineering diagnostics remain available without polluting live-play 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 1 and Phase 2 first. They offer immediate UX improvement with low architectural risk and create the visual foundation for the editor redesign and shared parsing work that follow.