# 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