141 lines
9.1 KiB
Markdown
141 lines
9.1 KiB
Markdown
# 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).
|