RolemasterDB/docs/tables_ux_bible.md

Tables UX Bible

Scope

Blueprint for the frontend overhaul of the webapp.

First fully specified target: /tables.

Constraints:

• keep current tech stack
• keep current backend and API contracts
• build on the current critical-table data model and curation workflow

Product Stance

• fast enough for live play
• clear enough for first-time players
• efficient enough for curator batch work
• separated enough that developer tools never pollute player-facing surfaces
• consistent enough that every future page can inherit the same shell, spacing, navigation, and interaction rules

Current Audit

• /tables currently combines table selection, table reading, curation, and full editing in one dense surface
• the table picker is hidden behind a dropdown with no search, no recent history, no pinned tables, and no batch-work affordances
• every populated cell carries visible action chrome, which raises noise and slows scanning
• reading help, legend, status, and edit hints compete with the actual table canvas
• hover is overloaded as a discovery mechanism even though hover is weak on touch and unnecessary for expert users
• the app-level navigation reflects implementation buckets, not user goals
• /diagnostics and /api are useful, but they should behave as tools, not as peer destinations for everyday play
• the visual system is coherent but too uniform; task priority is not expressed strongly enough through contrast, density, and layout

North Star

/tables is the canonical reference surface for critical tables.

One glance answers three questions:

1. where am I
2. what table / variant / roll band / severity am I looking at
3. what is the next most likely action

The page should feel like a high-speed tabletop reference board, not a CRUD grid.

Core Rules

• one page, one primary job
• one control cluster per decision
• one stable location for primary actions
• zero hover-only actions
• zero mandatory nested navigation for normal use
• search before browse when the item count is high
• read mode first, maintenance mode on demand
• sticky context beats repeated labels
• progressive disclosure beats always-visible chrome
• keyboard paths must be first-class, not fallback
• mobile keeps the same task model, not a reduced mental model

Stakeholders

Stakeholder	Primary goal	Typical session style	Must optimize for
Gamemaster	Resolve outcomes during live play	fast, repeated, interrupt-driven	minimum clicks, minimum scan time, stable controls
Player	Read and understand a result	occasional, low-system-mastery	clarity, legibility, low jargon, easy sharing
Curator	Repair and validate imported content	batch, accuracy-driven, repetitive	queue flow, source visibility, low context switching
Developer	Diagnose parser, payload, and rendering issues	investigative, detail-heavy	deep inspection without cluttering normal UX

App Model

Primary destinations:

• Play
• Tables
• Curation
• Tools

Rules:

• Play is the default landing area for live use
• Tables is the primary reference library and manual browsing surface
• Curation is a dedicated workflow surface for uncurated or suspect content
• Tools contains diagnostics, API surface documentation, and future import/admin surfaces
• no primary destination should require a submenu before becoming useful

Route Strategy

Target route map:

Destination	Purpose	Route direction
Play	live lookup and fast resolution	keep / as the primary entry
Tables	browse and inspect critical tables	keep /tables
Curation	queue-based content repair	add /curation
Tools	diagnostics, API docs, future admin/import tools	group under /tools

Rules:

• current backend endpoints stay as they are
• route changes are presentation-level, not API-level
• tools routes stay bookmarkable but visually separated from play-facing routes
• cross-links between Play, Tables, Curation, and Tools preserve object context

Page Families

Every future page should fit one of these patterns:

Page family	Example	Primary interaction
Resolver	Play	enter inputs, get answer fast
Reference	Tables	scan, jump, inspect
Workflow	Curation	repeat queue actions with low friction
Tooling	Diagnostics, API	inspect, compare, debug

Rules:

• do not mix page families inside one surface unless the secondary family is hidden behind progressive disclosure
• resolver pages prioritize input speed
• reference pages prioritize scanning and context retention
• workflow pages prioritize save-and-advance loops
• tooling pages prioritize depth and traceability

Global Navigation

Desktop shell:

• top app bar
• left page rail only when the current destination needs a collection index
• right inspector only when object detail is active

Top app bar contents, left to right:

• app mark
• primary nav tabs: Play, Tables, Curation, Tools
• omnibox: search tables, jump to commands, open recent items
• recent/pinned shortcut slot
• role-safe utility actions: settings, help, profile

Mobile shell:

• compact top bar with omnibox trigger
• bottom nav with the same four primary destinations
• contextual sheets instead of persistent side rails

Navigation rules:

• never expose more than one level of persistent navigation at a time
• if a left rail exists, it replaces page-local dropdowns for collection switching
• deep links always preserve the active object and mode
• every page remembers last relevant context per destination

Global Presentation

Visual direction:

• archival reference tool, not fantasy theme park
• explicit light and dark themes with parity, not one theme treated as secondary
• warm neutral base, dark ink text, brass accent, moss success, rust warning, slate utility
• strong typographic hierarchy
• generous whitespace around decision points
• dense data areas only where density helps speed

Type system:

• display and section titles: Fraunces
• UI labels and body: IBM Plex Sans
• code and diagnostics: IBM Plex Mono

Color roles:

• background: warm paper
• surface: lifted ivory
• primary accent: restrained blue-teal or muted cobalt family that does not clash with red, orange, or green semantic colors
• selection: deep slate-blue
• curated/safe: moss
• needs attention: rust/amber
• developer/tooling: cool slate

Component rules:

• cards for decisions
• chips for filters and state
• tabs only for mutually exclusive page modes
• drawers for inspect/edit context
• modals only for destructive confirmation or focused form tasks that must block

Theming Strategy

Theme modes:

• Light
• Dark
• System

Rules:

• theme selection is available from the global app bar
• the chosen theme persists across sessions
• System is the default for first-time users
• both themes must feel deliberately designed, not algorithmically inverted
• all major surfaces in Play, Tables, Curation, and Tools must support both themes equally

Color System

Principles:

• accent color communicates brand and focus, not validation or danger
• semantic colors communicate outcome and risk
• color hierarchy supports scan speed but never becomes the only signal
• dense data surfaces use restrained color, not decorative color noise

Required color roles:

• neutral scale for backgrounds, surfaces, borders, and text
• one central accent ramp for brand, focus, selected state, and non-destructive emphasis
• success ramp for curated/success feedback
• warning ramp for caution, reset-risk, and disruptive-but-recoverable actions
• danger ramp for destructive and irreversible actions
• info ramp for tooling and system messaging when needed

Rules:

• accent color must remain distinct from success green, warning orange, and danger red
• accent should be moderately saturated, not loud
• semantic colors override accent when user risk must be communicated
• success green should be used for state and feedback, not as the default primary CTA color
• table symbols and effect badges must be checked against both themes to avoid collisions with system colors

Depth And Hierarchy

Principles:

• brightness helps communicate nesting, but it is a guide, not a universal law
• hierarchy is conveyed through brightness, border contrast, spacing, typography, and elevation together
• table canvases and other high-density data regions use fewer depth steps than inspectors, drawers, and forms

Light mode guidance:

• deeper or nested surfaces usually become slightly darker than their parent surface
• the page background stays brightest, then main surfaces, then nested cards, then inset wells

Dark mode guidance:

• deeper or nested surfaces usually become slightly brighter than their parent surface
• the page background stays darkest, then main surfaces, then nested cards, then inset wells

Rules:

• avoid stacking too many surface steps inside the table grid
• do not rely on background brightness alone to indicate nesting
• selected state must remain obvious even when surface-depth differences are subtle

CSS Variable Guidance

Base token families:

• --bg-*
• --surface-*
• --text-*
• --border-*
• --focus-*
• --shadow-*

Accent token families:

• --accent-50 through --accent-900
• --accent-solid
• --accent-contrast
• --accent-soft
• --accent-gradient-subtle
• --accent-gradient-strong

Semantic token families:

• --success-*
• --warning-*
• --danger-*
• --info-*

Rules:

• gradients are optional support tokens, not the foundation of the UI
• subtle accent gradients may be used for shell-level highlights, primary CTAs, selected states, and hero surfaces
• gradients should not be used as the default fill for dense data regions, table cells, or most neutral panels
• component styling should consume semantic tokens by meaning, not by page

Button And Action Hierarchy

Color and emphasis map to user consequence, not to database mutation as an implementation detail.

Action levels:

Level	Purpose	Typical examples	Color behavior
Neutral	navigation and dismissal	Back, Cancel, Close, Collapse	neutral surface or ghost treatment
Soft accent	safe helper actions	Calculate, Preview, Inspect, Jump, Open source	low-to-medium emphasis with restrained accent
Strong accent	primary commit actions with expected positive outcome	Save, Apply, Mark curated, Import, Confirm	highest non-danger emphasis using accent ramp
Warning	risky but recoverable actions	Reset fields, Replace, Bulk reparse	amber/orange semantic treatment
Danger	destructive or irreversible actions	Delete, Overwrite, Destructive reset	red semantic treatment

Rules:

• the strongest visible button on a surface should be the most likely intended action
• neutral actions should visually recede
• non-destructive helper actions should never compete with commit actions
• strong accent is for commitment, not for danger
• warning and danger styles must remain reserved for meaningful risk
• saturation and contrast increase with action consequence
• labels still carry the meaning; color reinforces it

Button Styling Rules

• primary buttons use filled treatment
• secondary buttons use toned or outline treatment
• tertiary actions use ghost or text treatment
• the same action hierarchy must work in both light and dark themes
• disabled buttons reduce contrast and saturation but remain legible
• loading states preserve the original action color to avoid meaning shifts
• icon-only buttons are reserved for universally recognizable actions

Shared Interaction Model

Every major page follows the same anatomy:

Region	Purpose	Rules
Page header	title, mode, primary action, summary	sticky when it reduces context loss
Context bar	object picker, search, filters, recents	one horizontal control cluster
Main canvas	the main work surface	one dominant visual object
Inspector	selected object details and secondary actions	collapsible, never required for basic reading
Feedback rail	toasts, save state, warnings	never blocks the main scan path

/tables Target Definition

Primary job:

• browse and read critical tables fast

Secondary jobs:

• inspect a result in detail
• jump directly to a known cell
• curate results
• open the full editor

Jobs that do not belong as first-class clutter on /tables:

• raw diagnostics
• API documentation
• engineering payload inspection

/tables Information Architecture

Desktop:

Region	Contents	Notes
Left rail	searchable table index, pinned tables, recents, collection filters	replaces current dropdown
Sticky context bar	table title, variant picker, severity set, roll jump, mode switch, filter chips	always above the canvas
Table canvas	sticky row headers, sticky column headers, clean cells, active cell highlight	the visual priority
Right inspector	selected cell summary, symbols, branches, source state, actions	opens on selection, not on hover

Mobile:

Region	Contents	Notes
Top bar	current table, omnibox trigger, mode switch	compact
Sticky context row	variant, roll jump, filters	horizontal scroll allowed
Canvas	table grid with sticky headers	horizontal pan preserved
Bottom sheet	cell inspector and actions	replaces right drawer

/tables Modes

Three explicit modes:

• Reference
• Curate
• Inspect

Rules:

• default mode for normal users is Reference
• Curate only appears to users who need it
• Inspect is a detail emphasis mode for small screens and dense results
• mode switches are tabs, not hidden toggles
• the selected cell persists across modes when possible

/tables Context Bar

Required controls, ordered by frequency:

1. table search / picker
2. recent and pinned table shortcuts
3. variant selector only when the table has groups
4. roll jump input
5. optional severity focus
6. mode tabs
7. filter chips: All, Needs curation, Curated, Has branches, Has symbols

Rules:

• all high-frequency controls live in one sticky strip
• no control opens far away from the invoking pointer or focus position
• roll jump highlights the matching row immediately
• severity focus narrows visual emphasis without hiding context
• filters change emphasis first, visibility second

Table Index

The left rail is not a file tree.

It is a fast selector.

Required behavior:

• search-as-you-type
• keyboard arrow navigation
• enter to open
• pinned group
• recent group
• all tables list
• status chip per table: curated percentage
• optional quick filters by family: standard, variant-column, grouped-variant

Rules:

• no nested folders unless the table count eventually justifies them
• sort defaults to most recently used for fast repeat access
• labels stay human-readable; slugs never become primary UI text

Table Canvas

Principles:

• the grid is the hero
• row and column context never disappear during scroll
• active focus is obvious
• non-active cells stay visually quiet

Required behavior:

• sticky top headers
• sticky left roll-band column
• active row and active column emphasis on cell selection
• selected cell highlight with clear focus ring
• optional roll-jump line marker
• optional density toggle: Comfortable / Dense

Cell content rules:

• description first
• symbols second
• branches summarized, not expanded by default
• no full action button stack visible in every resting cell
• state color is subtle in Reference, stronger in Curate
• theme changes must not reduce row/column legibility or active-cell contrast
• nested cell treatments should rely mostly on border, spacing, and focus, not stacked fills

Cell Actions

Resting cell:

• no visible button clutter
• only semantic state hint

Selected cell:

• stable action tray in the inspector
• optional compact inline quick actions in the cell corner on desktop

Action priority:

1. inspect
2. mark curated or start quick parse when relevant
3. open full editor
4. open source image
5. copy deep link

Rules:

• one click selects the cell
• second click on the selected cell opens inspect detail if needed
• double-click is not a required behavior
• touch uses the same one-tap select model
• action color follows the global action hierarchy: neutral for dismissal, soft accent for inspect/open, strong accent for save/mark curated, warning for risky bulk actions, danger only for destructive actions

Inspector

Contents:

• roll band
• group / variant
• column / severity
• full prose description
• parsed symbols/effects
• branch cards
• curation state
• source image preview
• primary actions

Rules:

• opens without obscuring the selected cell on desktop
• can be pinned open or collapsed
• keeps primary actions in the same vertical position
• never requires opening the full editor just to understand the result
• nested inspector sections follow the theme depth rules with restrained surface stepping

Reference Flow: Gamemaster

Success criteria:

• open the needed table in one search action
• jump to the needed row in one roll action
• read the result without opening a modal

Flow:

1. open Tables
2. use omnibox or left-rail search to find a table
3. set variant only if required
4. enter roll in the sticky roll-jump field
5. the matching row highlights immediately
6. click the target cell or use arrow keys
7. read the result in the inspector
8. copy or share the deep link if needed

Optimizations:

• remember last used tables
• keep roll-jump near the table title
• keep selection in the same screen area while changing rows by keyboard
• provide open from Play deep links when a lookup resolves to a critical result

Reference Flow: Player

Success criteria:

• understand a result with minimal system jargon
• avoid maintenance controls

Flow:

1. open a shared deep link or land on a table already chosen by the gamemaster
2. see the selected row, column, and result highlighted immediately
3. read plain-language description first
4. expand branch details only if relevant
5. ignore curator and developer actions entirely

Optimizations:

• hide curation status by default for non-maintenance users
• show branch conditions in plain language
• support compact sharing URLs that preserve table, variant, row, column, and mode

Curation Flow: Curator

Success criteria:

• move through uncurated cells with near-zero navigation overhead
• see source and parsed result side by side
• save and continue in one repeated gesture

Flow:

1. open Curation
2. land in a queue-first view, not the general browse view
3. choose table scope: all tables, selected table, pinned set
4. open the next uncurated cell
5. inspect source image and parsed result side by side
6. choose Mark curated, Quick parse, or Full edit
7. save
8. auto-advance to the next queue item in the same context

Optimizations:

• batch queue lives in Curation, not as ambient clutter across all cells in Tables
• Next uncurated is always in the same spot
• quick parse happens in the inspector or split pane before falling back to full editor
• save keeps the cursor in the working lane and avoids re-opening context
• warning styling is reserved for disruptive repair actions; standard save-and-advance remains strong accent, not warning

Diagnostics Flow: Developer

Success criteria:

• inspect parser provenance and payloads without degrading the play-facing experience

Flow:

1. open Tools
2. choose Diagnostics
3. locate the relevant table/cell through the same shared table selector patterns
4. inspect parser metadata, raw payload, source image, and reparse output
5. jump back to Tables or Curation with preserved selection when needed

Optimizations:

• reuse object selection patterns from /tables
• keep raw JSON and diagnostics in tooling surfaces only
• preserve deep links across tools and reference views

Editing Model

• Tables is browse-first
• Curation is queue-first
• full editor is form-first

Rules:

• quick actions should solve the common curation case without opening the full editor
• full editor opens in a focused drawer on wide screens and a full-screen sheet on small screens
• no stacked modal-on-modal flows
• save feedback is inline and immediate
• cancel and navigation actions remain neutral even inside forms
• destructive edit operations require danger styling and explicit confirmation

Search and Deep Links

Every important object needs a stable URL.

Minimum /tables deep link state:

• table slug
• group key when present
• column key when present
• roll band or roll jump value
• selected cell result id when present
• mode

Search must support:

• table labels
• common aliases
• recent history
• slash commands for power users

Examples:

• /slash
• /large creature magic
• /curation next
• /table puncture

Accessibility

• WCAG AA contrast minimum
• all actions keyboard reachable
• visible focus ring on cells, chips, tabs, and drawer actions
• ARIA grid semantics only if keyboard behavior matches true grid expectations
• no information communicated by color alone
• no hover-only discovery
• sticky headers must not trap screen-reader or keyboard order
• mobile hit targets minimum 44 by 44 px
• theme parity must preserve contrast and distinguish accent from semantic colors in both modes

Content Rules

• table names use human labels
• maintenance labels use plain verbs: Inspect, Mark curated, Quick parse, Open editor
• avoid internal implementation terms in player-facing copy
• instructional text appears only when needed and disappears once the user has context
• legends explain symbols in the inspector and on demand, not as permanent page noise

Performance Rules

• perceived table switch under 150 ms after initial load
• preserve scroll and selection state per table
• virtualize only if table size requires it; do not break sticky headers or keyboard navigation
• render non-selected cells with low chrome and cheap DOM
• delay heavy inspector content until selection

Metrics

• table switch in two interactions or fewer after first visit
• jump from known roll to matching row in one interaction
• read a result without opening a modal in the default flow
• curator save-to-next-item in one primary action
• zero player-facing exposure to diagnostics or raw parser payloads

Rollout Sequence

Phase 1:

• new global shell
• new top-level navigation
• omnibox
• table index patterns

Phase 2:

• /tables reference mode
• sticky context bar
• left rail
• inspector
• deep links

Phase 3:

• dedicated Curation surface
• queue model
• quick parse in split view
• save-and-advance loop

Phase 4:

• Tools consolidation for diagnostics and API docs
• preserved cross-links between tools and reference surfaces

Phase 5:

• apply the same shell and interaction system to all future pages
• make Play and Tables feel like one connected product, not separate demos

Non-Negotiables

• no implementation-driven primary navigation
• no cell-level button clutter in resting state
• no required hover behavior
• no modal stack for normal curation work
• no deep nested sidebars unless future scale proves they are necessary
• no mixing of developer diagnostics into player and gamemaster workflows

Definition Of Done For The /tables Overhaul

• a gamemaster can find a table and resolve a result with minimal scan and pointer travel
• a player can understand the selected result without maintenance noise
• a curator can move through uncurated cells in a stable queue flow
• a developer can reach diagnostics from Tools without polluting the reference experience
• the page establishes the layout, navigation, and interaction grammar for the rest of the webapp