initiative/specs/016-combatant-ac/spec.md

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.