initiative/specs/027-ui-polish/spec.md

Feature Specification: Combatant Row UI Polish

Feature Branch: 027-ui-polish Created: 2026-03-10 Status: Draft Input: User description: "UI/UX improvements to the combatant row — inline conditions, hover-only remove button, row-click stat block, AC shield shape, expanded concentration click target, larger d20 icon"

User Scenarios & Testing (mandatory)

User Story 1 - Inline Conditions (Priority: P1)

As a DM running an encounter, I want condition icons to appear inline next to the creature name so that each combatant row takes up minimal vertical space while conditions remain visible at a glance.

Why this priority: Conditions below each row are the largest source of visual clutter and wasted vertical space. This single change will have the most visible impact on the tracker's compactness and readability.

Independent Test: Can be tested by adding conditions to combatants and verifying they appear on the same line as the name, with the "+" button visible only on hover.

Acceptance Scenarios:

1. Given a combatant has no conditions, When the row is not hovered, Then no condition UI is visible on that row.
2. Given a combatant has no conditions, When the user hovers over the row, Then a "+" button appears inline after the creature name.
3. Given a combatant has conditions applied, When viewing the tracker, Then condition icons appear inline after the creature name on the same row (no second line).
4. Given a combatant has conditions applied, When the user hovers over the row, Then a "+" button appears after the last condition icon.
5. Given a combatant has many conditions, When the row is displayed, Then the conditions wrap gracefully within the name column without overlapping other columns.
6. Given conditions are displayed inline, When the user clicks a condition icon, Then the condition is removed (existing behavior preserved).
7. Given conditions are displayed inline, When the user clicks the "+" button, Then the condition picker dropdown opens (existing behavior preserved).

---

User Story 2 - Row Click Opens Stat Block (Priority: P1)

As a DM, I want to click anywhere on a combatant row to open its stat block so that I have a larger click target and a cleaner row without a dedicated book icon.

Why this priority: Removing the BookOpen icon and making the row clickable simultaneously reduces visual clutter and improves usability. Tightly coupled with inline conditions (both change the name area).

Independent Test: Can be tested by clicking various non-interactive areas of a bestiary combatant row and verifying the stat block panel opens.

Acceptance Scenarios:

1. Given a combatant has a linked creature (bestiary entry), When the user clicks on the name text, Then the stat block panel opens for that creature.
2. Given a combatant has a linked creature, When the user clicks on empty space within the row (not on an interactive element), Then the stat block panel opens.
3. Given the user clicks on an interactive element (initiative, HP, AC, condition icon, "+", "×", concentration), Then the stat block does NOT open; the element's own action fires instead.
4. Given a combatant does NOT have a linked creature (custom combatant), When the user clicks on the row, Then nothing happens (no stat block to show).
5. Given a combatant row is displayed, When viewing the row, Then no dedicated book/stat-block icon is visible (the BookOpen icon is removed).
6. Given a bestiary combatant row, When the user hovers over non-interactive areas, Then the cursor indicates the row is clickable.

---

User Story 3 - Hover-Only Remove Button (Priority: P2)

As a DM, I want the remove (×) button to only appear when I hover over a combatant row so that the tracker looks cleaner during play and I'm less likely to accidentally remove a combatant.

Why this priority: Reduces persistent visual noise. Lower priority than layout changes since it's a simpler visibility toggle.

Independent Test: Can be tested by hovering and unhovering combatant rows and verifying the × button appears/disappears.

Acceptance Scenarios:

1. Given a combatant row is not hovered, When viewing the tracker, Then the remove button is not visible.
2. Given a combatant row is hovered, When the user moves the mouse over the row, Then the remove button becomes visible.
3. Given the remove button is visible on hover, When the user clicks it, Then the combatant is removed (existing behavior preserved).
4. Given the remove button is hidden, When viewing the row layout, Then the row does not shift or reflow when the button appears on hover (space is reserved).

---

User Story 4 - AC Shield Shape (Priority: P2)

As a DM, I want the AC number displayed inside a shield-shaped outline so that AC is instantly recognizable as armor class — matching the visual language of D&D character sheets.

Why this priority: High visual impact and strong thematic resonance, but independent of the layout restructuring in P1 stories.

Independent Test: Can be tested by viewing any combatant with AC set and verifying the number appears inside a shield-shaped visual element.

Acceptance Scenarios:

1. Given a combatant has an AC value, When viewing the row, Then the AC number is displayed inside a shield-shaped outline.
2. Given a combatant has an AC value, When viewing the shield, Then the current separate shield icon is no longer displayed (replaced by the shield shape around the number).
3. Given a combatant has no AC value set, When viewing the row, Then the shield shape is still displayed with a placeholder or empty state.
4. Given the AC shield is displayed, When the user clicks on it, Then the AC editing interaction works as before (existing edit behavior preserved).
5. Given the AC shield is displayed at various AC values (single-digit, double-digit, triple-digit), When viewing the shield, Then the number is centered and the shield scales appropriately.

---

User Story 5 - Expanded Concentration Click Target (Priority: P3)

As a DM, I want the concentration toggle to have a larger clickable area — filling the gutter between the purple active-turn border and the initiative column — so that toggling concentration is easier to hit during fast-paced play.

Why this priority: Quality-of-life improvement that doesn't change visual design, only interaction area. Lower impact than layout and visual changes.

Independent Test: Can be tested by clicking in the gutter area left of the initiative number and verifying concentration toggles.

Acceptance Scenarios:

1. Given a combatant row, When the user clicks anywhere in the space between the left border and the initiative column, Then the concentration toggle is activated.
2. Given the concentration button has an expanded click target, When viewing the row, Then the visual appearance of the brain icon remains unchanged.
3. Given a concentrating combatant receives damage, When the shake/glow animation plays, Then the animation still works correctly with the expanded click target.

---

User Story 6 - Larger D20 Icon (Priority: P3)

As a DM, I want the d20 roll-initiative button to be slightly larger so that the icosahedron shape is clearly recognizable as a d20 die rather than an ambiguous icon.

Why this priority: Minor visual refinement. Enabled by the vertical space savings from inline conditions.

Independent Test: Can be tested by viewing a bestiary combatant without initiative set and verifying the d20 icon is visually recognizable.

Acceptance Scenarios:

1. Given a bestiary combatant has no initiative set, When viewing the row, Then the d20 icon is displayed at a larger size than the current 20×20 pixels.
2. Given the d20 icon is larger, When viewing the row, Then the icon does not overflow or misalign with the initiative column.
3. Given the d20 icon is larger, When the user clicks it, Then initiative is rolled as before (existing behavior preserved).

---

Edge Cases

• What happens when a combatant has so many conditions that they exceed the available inline space? They wrap within the name column; the row height increases to accommodate.
• How does the condition picker dropdown position itself when opened from an inline "+" button? It positions relative to the "+" button, flipping vertically if near the viewport edge (existing flip logic preserved).
• What happens on touch devices where hover is not available? The "+" condition button and "×" remove button remain accessible via tap (they appear on touch/focus rather than requiring hover).
• What happens when the stat block panel is already open for a creature and the user clicks the same row again? The panel closes (toggle behavior).
• How does the row-click stat block interact with initiative editing? Clicking the initiative area starts editing; it does not open the stat block.

Requirements (mandatory)

Functional Requirements

• FR-001: Condition icons MUST render inline after the creature name within the same row, not on a separate line below the row.
• FR-002: The "+" condition button MUST be hidden by default and appear only on row hover (or touch/focus on touch devices).
• FR-003: The remove (×) button MUST be hidden by default and appear only on row hover (or touch/focus on touch devices).
• FR-004: The row MUST reserve layout space for the remove button so that appearing/disappearing does not cause layout shifts.
• FR-005: Clicking non-interactive areas of a bestiary combatant row MUST open the stat block panel for that creature.
• FR-006: Clicking interactive elements (initiative, HP, AC, conditions, "+", "×", concentration) MUST NOT trigger the stat block panel — only the element's own action.
• FR-007: The BookOpen icon MUST be removed from the combatant row.
• FR-008: The AC value MUST be displayed inside a shield-shaped visual element (outline or background) replacing the separate shield icon.
• FR-009: The concentration toggle's clickable area MUST extend to fill the full gutter between the left border and the initiative column.
• FR-010: The d20 roll-initiative icon MUST be displayed at a larger size than the current 20×20px while remaining contained within the initiative column.
• FR-011: All existing interactions (condition add/remove, HP adjustment, AC editing, initiative editing/rolling, concentration toggle, combatant removal) MUST continue to work as before.
• FR-012: Bestiary combatant rows with a linked creature MUST show a pointer cursor on hover over non-interactive areas to indicate clickability.
• FR-013: Browser scrollbars MUST be styled to match the dark UI theme — using thin, dark-colored scrollbar thumbs instead of the browser's default light/grey appearance.
• FR-014: The top bar's Roll All (d20) and Clear Encounter (trash) icons MUST be sized proportionally to the bar (d20 at 24px, trash at 20px) and visually grouped together, separated from the turn navigation controls by spacing.
• FR-016: Turn navigation (Previous/Next) MUST use StepBack/StepForward icons in outline button style with foreground-colored borders, replacing the previous text+chevron buttons. Utility actions (d20/trash) MUST use ghost button style to create a clear visual hierarchy.
• FR-017: The Previous and Next turn buttons MUST be positioned at the far left and far right of the top bar respectively, with the round/combatant info centered between them.
• FR-015: The "Initiative Tracker" heading MUST be removed to maximize vertical space for combatants. The turn navigation bar provides sufficient context.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: Each combatant row without conditions takes up exactly one line height (no empty second row).
• SC-002: All six visual/interaction improvements are implemented without breaking any existing tracker functionality.
• SC-003: The DM can open a stat block by clicking anywhere on the combatant name area — no need to locate a small icon.
• SC-004: The AC number is visually identifiable as "armor class" without a separate icon label, through the shield shape alone.
• SC-005: The d20 icon is recognizable as a twenty-sided die at its displayed size.
• SC-006: No layout shift occurs when hovering/unhovering rows (remove button and "+" button appear without reflowing content).