# Feature Specification: Combatant Armor Class Display **Feature Branch**: `016-combatant-ac` **Created**: 2026-03-06 **Status**: Draft **Input**: User description: "Display Armor Class for each combatant using a small shield icon with the AC value (e.g., shield 17) next to the name in the encounter list." ## User Scenarios & Testing ### User Story 1 - Set AC for a Combatant (Priority: P1) A game master sets an Armor Class value on a combatant using the inline AC input in the encounter list so it is stored and visible in the tracker. **Why this priority**: AC must exist on the combatant before it can be displayed. This is the foundational data entry path. **Independent Test**: Can be tested by setting an AC value on an existing combatant and confirming the value persists in the encounter state. **Acceptance Scenarios**: 1. **Given** a combatant exists in the encounter, **When** the user clicks the AC area next to the combatant's name and enters 17, **Then** the combatant's AC is set to 17 and the shield icon with "17" appears. 2. **Given** a combatant exists in the encounter without an AC value, **When** the encounter list is displayed, **Then** no AC input or shield icon is visible until the user activates the AC field. --- ### User Story 2 - Display AC in the Encounter List (Priority: P1) A game master views the encounter list and sees each combatant's Armor Class displayed as a shield icon with the numeric value (e.g., shield icon followed by 17) next to the combatant's name. **Why this priority**: This is the core visual feature requested by the user, tied with Story 1 since both are needed for the feature to be useful. **Independent Test**: Can be tested by loading an encounter with combatants that have AC values and verifying the shield icon and number appear next to each name. **Acceptance Scenarios**: 1. **Given** a combatant has AC 17, **When** the encounter list is displayed, **Then** a shield icon and the value "17" appear next to the combatant's name. 2. **Given** a combatant has no AC set, **When** the encounter list is displayed, **Then** no shield icon or AC value is shown for that combatant. 3. **Given** multiple combatants with different AC values, **When** the encounter list is displayed, **Then** each combatant shows its own correct AC value. --- ### User Story 3 - Edit AC for an Existing Combatant (Priority: P2) A game master edits an existing combatant to add, change, or remove their Armor Class value. **Why this priority**: Editing supports corrections and mid-session changes but is secondary to initial entry and display. **Independent Test**: Can be tested by editing a combatant's AC and confirming the updated value appears in the encounter list. **Acceptance Scenarios**: 1. **Given** a combatant has AC 15, **When** the user edits the combatant and changes AC to 18, **Then** the displayed AC updates to 18. 2. **Given** a combatant has AC 15, **When** the user edits the combatant and clears the AC field, **Then** no AC is displayed for that combatant. 3. **Given** a combatant has no AC, **When** the user edits the combatant and sets AC to 12, **Then** the shield icon and "12" appear next to the combatant's name. --- ### Edge Cases - What happens when AC is 0? The system displays the shield icon with "0" (AC 0 is a valid value in tabletop RPGs). - What happens when AC is a very large number (e.g., 99)? The display accommodates up to two-digit values without layout issues. - What happens when AC is negative? The system does not accept negative AC values; AC must be a non-negative integer. ## Requirements ### Functional Requirements - **FR-001**: The combatant data model MUST support an optional Armor Class field that holds a non-negative integer. - **FR-002**: The system MUST allow users to set an AC value on any combatant via an inline input in the encounter list. - **FR-003**: The system MUST allow users to edit the AC value for an existing combatant (add, change, or remove). - **FR-004**: The encounter list MUST display each combatant's AC as a shield icon followed by the numeric value, positioned next to the combatant's name. - **FR-005**: The encounter list MUST NOT display a shield icon or AC value for combatants without an AC set. - **FR-006**: The system MUST persist AC values through the existing storage mechanism (same as other combatant fields). - **FR-007**: AC values MUST be validated as non-negative integers (0 or greater). ### Key Entities - **Combatant**: Gains an optional Armor Class attribute, a non-negative integer. Relates to existing combatant fields (name, initiative, HP). ## Success Criteria ### Measurable Outcomes - **SC-001**: Users can set an AC value for any combatant within the existing add/edit workflows with no additional steps beyond filling in the field. - **SC-002**: AC values are visible at a glance in the encounter list without expanding or hovering over any element. - **SC-003**: Combatants without AC display no visual clutter — the shield icon only appears when AC is set. - **SC-004**: All existing functionality (HP tracking, initiative, turn navigation) continues to work without regression. ## Assumptions - AC is always a non-negative integer (consistent with D&D 5e and most tabletop RPG systems). - The shield icon is rendered using the project's existing icon library (Lucide React), not an emoji character. - The AC display is read-only in the encounter list row; editing AC uses the existing combatant edit flow. - MVP baseline does not include AC-based calculations (e.g., to-hit comparisons) or conditional formatting based on AC thresholds.