588 lines
18 KiB
Markdown
588 lines
18 KiB
Markdown
# 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
|
|
- 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 action: brass
|
|
- 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
|
|
|
|
## 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`
|
|
|
|
## 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
|
|
|
|
## 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
|
|
|
|
## 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
|
|
|
|
## 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
|
|
|
|
## 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
|
|
|
|
## 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
|