initiative/specs/034-topbar-redesign/spec.md

Feature Specification: Redesign Top Bar with Dedicated Round and Turn Fields

Feature Branch: 034-topbar-redesign Created: 2026-03-11 Status: Draft Input: User description: "Redesign the encounter top bar to replace the single 'Round 1 — Conjurer' status string with dedicated, separately styled fields for round number and current combatant."

User Scenarios & Testing (mandatory)

User Story 1 - Scanning Round and Combatant at a Glance (Priority: P1)

As a game master running an encounter, I want the round number and current combatant displayed as distinct, visually separated elements so I can instantly identify both without parsing a combined string.

Why this priority: This is the core value of the redesign — making the two most important pieces of encounter state (round and combatant) immediately scannable.

Independent Test: Can be fully tested by starting an encounter and verifying that the round number appears as a compact badge on the left and the combatant name appears as a prominent centered label.

Acceptance Scenarios:

1. Given an active encounter in Round 2 with "Goblin" as the active combatant, When the user views the top bar, Then "Round 2" appears as a muted badge/pill near the left side and "Goblin" appears as a prominent centered label, with no dash or combined string.
2. Given an active encounter in Round 1 at the first combatant, When the encounter starts, Then the round badge shows the round number and the center displays the first combatant's name as separate visual elements.
3. Given the user advances the turn, When the round increments from 3 to 4, Then the round badge updates to reflect the new round number without layout shift.

---

User Story 2 - Consistent Left-Center-Right Layout (Priority: P1)

As a game master, I want the top bar to follow a clear left-center-right structure so that controls are always in predictable positions regardless of combatant name length.

Why this priority: A well-structured layout ensures usability across different name lengths and screen sizes.

Independent Test: Can be tested by loading encounters with varying combatant name lengths (short: "Orc", long: "Ancient Red Dragon Wyrm") and confirming the layout remains balanced.

Acceptance Scenarios:

1. Given an encounter with a short combatant name like "Orc", When viewing the bar, Then the layout maintains the left-center-right structure with the name centered.
2. Given an encounter with a long combatant name like "Ancient Red Dragon Wyrm of the Northern Wastes", When viewing the bar, Then the name truncates gracefully without pushing action buttons off-screen.
3. Given a narrow viewport, When viewing the bar, Then all three zones (round badge, combatant name, action buttons) remain visible and accessible.

---

User Story 3 - No Combatants State (Priority: P2)

As a game master with an empty encounter, I want the top bar to handle the no-combatants state gracefully with the new layout.

Why this priority: Edge case handling — the bar must remain functional and not look broken when there are no combatants.

Independent Test: Can be tested by creating an encounter with no combatants and verifying the bar displays appropriately.

Acceptance Scenarios:

1. Given an encounter with no combatants, When viewing the top bar, Then the round badge still shows the round number and the center area displays a placeholder message indicating no active combatant.

---

Edge Cases

• What happens when the combatant name is extremely long (50+ characters)? The name should truncate with an ellipsis rather than breaking the layout.
• How does the bar behave when transitioning between combatants? The update should be immediate with no intermediate blank state.
• What happens on very narrow viewports? The round badge and action buttons should remain visible; the combatant name may truncate.

Requirements (mandatory)

Functional Requirements

• FR-001: The top bar MUST display the round number as a compact, visually muted badge or pill element positioned after the previous-turn button on the left side.
• FR-002: The top bar MUST display the current combatant's name as a prominent, centered label that is the visual focal point of the bar.
• FR-003: The round number and combatant name MUST be visually distinct elements — not joined by a dash or rendered as a single string.
• FR-004: Action buttons (roll initiative, manage sources, clear encounter) MUST remain grouped on the right side of the bar.
• FR-005: The navigation buttons (previous turn on the far left, next turn on the far right) MUST retain their current positions.
• FR-006: The bar MUST follow a left-center-right layout: [prev] [round badge] — [combatant name] — [action buttons] [next].
• FR-007: The combatant name MUST truncate with an ellipsis when it exceeds the available space rather than causing layout overflow.
• FR-008: When no combatants exist, the center area MUST display a placeholder message and the round badge MUST still show the current round number.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: Users can identify the current round number and active combatant in under 1 second of looking at the bar, without needing to parse a combined string.
• SC-002: The top bar layout remains visually balanced and functional across viewport widths from 320px to 1920px.
• SC-003: All existing top bar functionality (turn navigation, roll initiative, manage sources, clear encounter) remains fully operational after the redesign.
• SC-004: Combatant names up to 40 characters display without layout breakage; longer names truncate gracefully.

Assumptions

• The round badge uses the compact format "R{number}" (e.g., "R1", "R2").
• The visual styling of the badge/pill (color, border radius, font size) follows the existing design language of the application.
• No new data or domain changes are required — this is a purely presentational change to existing UI components.
• The existing turn navigation component will be refactored rather than replaced.