# 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**: 1. **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. 2. **Given** combatants with varying name lengths, **When** displayed, **Then** columns remain aligned and do not shift or overlap. 3. **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**: 1. **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). 2. **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**: 1. **Given** the encounter screen, **When** viewing controls, **Then** the "Add Combatant" input and "Next Turn" button are grouped in a visually distinct action bar. 2. **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**: 1. **Given** a combatant row, **When** I click the name, **Then** it transitions to an inline text input styled consistently with the design system. 2. **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**: 1. **Given** a combatant row, **When** viewing the actions column, **Then** the remove action is displayed as a small icon button (not a text label). 2. **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**: 1. **Given** the encounter screen, **When** inspecting typography, **Then** headings, labels, and body text use a consistent type scale. 2. **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).