9.1 KiB
Feature Specification: UI Baseline
Feature Branch: 010-ui-baseline
Created: 2026-03-05
Status: Draft
Input: User description: "Establish a modern UI baseline for the encounter screen using Tailwind + shadcn/ui."
User Scenarios & Testing (mandatory)
User Story 1 - Structured Combatant Layout (Priority: P1)
As a game master viewing the encounter screen, I see each combatant displayed as a structured row with initiative, name, HP, and actions aligned in consistent columns, so I can quickly scan the battlefield state.
Why this priority: The core value of a UI baseline is replacing the unstyled list with a consistent, scannable layout. Every other visual improvement builds on this.
Independent Test: Can be fully tested by adding 3+ combatants and verifying that all data fields (initiative, name, HP, actions) are visually aligned in a grid/table-like layout.
Acceptance Scenarios:
- Given an encounter with multiple combatants, When the screen loads, Then each combatant is displayed as a row with initiative, name, HP, and actions in consistent columns.
- Given combatants with varying name lengths, When displayed, Then columns remain aligned and do not shift or overlap.
- Given a combatant with no initiative or HP set, When displayed, Then placeholder or empty state is shown in the appropriate column without breaking alignment.
User Story 2 - Active Combatant Highlight (Priority: P1)
As a game master during combat, I see the active combatant clearly highlighted so I can instantly identify whose turn it is without reading text markers.
Why this priority: Identifying the active turn is the primary interaction during live play. A clear visual highlight is essential for usability.
Independent Test: Can be tested by advancing turns and verifying the active combatant has a distinct visual treatment (background color, border, or similar).
Acceptance Scenarios:
- Given an encounter in progress, When viewing the combatant list, Then the active combatant's row has a visually distinct highlight (e.g., accent background, left border indicator).
- Given the turn advances, When a new combatant becomes active, Then the highlight moves to the new active combatant and is removed from the previous one.
User Story 3 - Grouped Action Bar (Priority: P2)
As a game master, I see primary encounter controls (add combatant, next turn) grouped in a clearly defined action bar, so controls are easy to find and visually separated from the combatant list.
Why this priority: Grouping controls improves discoverability and reduces visual clutter, but is less critical than the combatant layout itself.
Independent Test: Can be tested by verifying that the "Add Combatant" form and "Next Turn" button are visually grouped in a distinct bar area, separated from the combatant list.
Acceptance Scenarios:
- Given the encounter screen, When viewing controls, Then the "Add Combatant" input and "Next Turn" button are grouped in a visually distinct action bar.
- Given the action bar, When inspecting layout, Then it is clearly separated from the combatant list by spacing, background, or border.
User Story 4 - Inline Editing with Consistent Styling (Priority: P2)
As a game master, I can click on a combatant's name to edit it inline, and all editable controls (including initiative and HP inputs) match the overall visual style of the application.
Why this priority: Inline editing already exists functionally. This story ensures the edit states are visually consistent with the new design system rather than appearing as unstyled browser defaults.
Independent Test: Can be tested by clicking a combatant name to enter edit mode and verifying the input field matches the application's visual style.
Acceptance Scenarios:
- Given a combatant row, When I click the name, Then it transitions to an inline text input styled consistently with the design system.
- Given a combatant row, When I edit initiative or HP values, Then the number inputs are styled consistently with the design system.
User Story 5 - Remove Action as Icon Button (Priority: P3)
As a game master, I see the remove action as a small icon button rather than a full text button, so it takes up less space and reduces visual noise.
Why this priority: This is a refinement that improves information density. The remove action is infrequently used, so a compact icon button is appropriate.
Independent Test: Can be tested by verifying each combatant row has a small icon-sized remove button (e.g., trash or X icon) instead of a text "Remove" button.
Acceptance Scenarios:
- Given a combatant row, When viewing the actions column, Then the remove action is displayed as a small icon button (not a text label).
- Given the icon button, When hovering, Then a tooltip or visual feedback indicates the action is "Remove".
User Story 6 - Consistent Typography and Spacing (Priority: P2)
As a game master, the encounter screen uses consistent font sizes, weights, and spacing throughout, creating a cohesive and professional appearance.
Why this priority: Typography and spacing consistency is foundational to a "modern UI baseline" and affects the perceived quality of every other element.
Independent Test: Can be tested by verifying that heading sizes, body text, input text, and spacing follow a consistent scale across the entire screen.
Acceptance Scenarios:
- Given the encounter screen, When inspecting typography, Then headings, labels, and body text use a consistent type scale.
- Given the encounter screen, When inspecting spacing, Then padding and margins follow a consistent spacing scale.
Edge Cases
- What happens when no combatants exist? The screen should display an empty state message (e.g., "No combatants yet") rather than a blank area.
- What happens with very long combatant names? Names should truncate with ellipsis rather than breaking the layout.
- What happens on narrow viewports? The layout should remain usable, though a fully responsive mobile design is not in the MVP baseline for this feature.
- What happens with 20+ combatants? The list should scroll without the action bar or header disappearing.
Requirements (mandatory)
Functional Requirements
- FR-001: System MUST display combatants in a structured row layout with columns for initiative, name, HP (current/max), and actions. All numeric fields use text inputs with
inputmode="numeric"(no browser spinners), ch-based widths, tabular numerals, and centered text. - FR-002: System MUST visually highlight the active combatant's row with a distinct background, border, or accent treatment.
- FR-003: System MUST group the "Add Combatant" form and "Next Turn" button in a visually distinct action bar area.
- FR-004: System MUST display the remove action as a compact icon button (not a text label) on each combatant row.
- FR-005: System MUST style all form inputs (text fields, number inputs) consistently using the design system's components.
- FR-006: System MUST apply consistent typography (font family, sizes, weights) and spacing (margins, padding) from a defined scale.
- FR-007: System MUST show a round/turn status indicator (current round number and active combatant name) in a header or status area.
- FR-008: System MUST display an empty state message when no combatants are present.
- FR-009: System MUST truncate long combatant names with ellipsis rather than breaking the layout.
- FR-010: System MUST NOT introduce any domain logic changes; all changes are confined to the adapter/UI layer.
- FR-011: System MUST NOT display domain events in the main UI layout.
Success Criteria (mandatory)
Measurable Outcomes
- SC-001: All combatant data fields (initiative, name, HP, actions) are visually aligned in consistent columns across all combatant rows.
- SC-002: The active combatant is identifiable within 1 second of glancing at the screen, without reading text labels.
- SC-003: A new user can locate the "Add Combatant" and "Next Turn" controls within 3 seconds of viewing the screen.
- SC-004: All interactive elements (buttons, inputs) are styled consistently with no browser-default styled controls visible.
- SC-005: The encounter screen presents a cohesive visual appearance with no mismatched fonts, inconsistent spacing, or unstyled elements.
Assumptions
- Tailwind CSS and shadcn/ui will be used as the design system and component library. These are adapter-layer technology choices.
- The existing functional behavior (inline editing, HP controls, add/remove/advance) is preserved exactly; only visual presentation changes.
- A dark theme or theme toggle is not included in the MVP baseline for this feature.
- Full mobile/responsive optimization is not included in the MVP baseline for this feature, though the layout should not be broken on smaller screens.
- Domain events will be removed from the main UI display (they were a development aid, not a user-facing feature).