# Feature Specification: Combat Conditions **Feature Branch**: `017-combat-conditions` **Created**: 2026-03-06 **Status**: Draft **Input**: User description: "Add combat conditions to combatants with icon tags, compact picker, and Lucide icon mapping" ## User Scenarios & Testing *(mandatory)* ### User Story 1 - Add a Condition to a Combatant (Priority: P1) As a DM running an encounter, I want to quickly apply a condition to a combatant so I can track status effects during combat. **Why this priority**: Core functionality -- without the ability to add conditions, the feature has no value. **Independent Test**: Can be fully tested by clicking the "+" button on a combatant, selecting a condition, and verifying it appears as an icon tag under the combatant's name. **Acceptance Scenarios**: 1. **Given** a combatant with no active conditions, **When** I look at the combatant row, **Then** I see a small "+" button in the condition area below the combatant name. 5. **Given** a combatant with one or more active conditions, **When** I look at the combatant row, **Then** I see the active condition icon tags followed by a "+" button. 2. **Given** a combatant row, **When** I click the "+" button, **Then** a compact picker opens showing all 15 available conditions, each displayed as an icon with a label. 3. **Given** the condition picker is open, **When** I click a condition entry, **Then** the condition is toggled on and appears as a colored icon tag under the combatant name in the combat row. 4. **Given** the condition picker is open with some conditions already active, **When** I view the picker, **Then** active conditions are visually distinguished from inactive ones. --- ### User Story 2 - Remove a Condition from a Combatant (Priority: P1) As a DM, I want to quickly remove a condition from a combatant when the effect ends so the tracker stays accurate. **Why this priority**: Equally critical as adding -- conditions must be removable to reflect combat state changes. **Independent Test**: Can be tested by clicking an active condition icon tag and verifying it is removed. **Acceptance Scenarios**: 1. **Given** a combatant with one or more active conditions, **When** I click an active condition icon tag in the combat row, **Then** the condition is removed and the icon tag disappears. 2. **Given** a combatant with one active condition, **When** I remove that condition, **Then** only the "+" button remains in the condition area. 3. **Given** the condition picker is open, **When** I click an active condition in the picker, **Then** the condition is toggled off and removed from the combatant row. --- ### User Story 3 - View Condition Details via Tooltip (Priority: P2) As a DM, I want to hover over a condition icon to see its name so I can quickly identify conditions without memorizing icons. **Why this priority**: Important for usability but the feature is functional without it. **Independent Test**: Can be tested by hovering over an active condition icon tag and verifying the tooltip displays the condition name. **Acceptance Scenarios**: 1. **Given** a combatant with an active condition, **When** I hover over the condition icon tag, **Then** a tooltip appears showing the condition's name (e.g., "Blinded", "Poisoned"). 2. **Given** I am hovering over a condition icon, **When** I move the cursor away, **Then** the tooltip disappears. --- ### User Story 4 - Multiple Conditions on One Combatant (Priority: P2) As a DM, I want to apply multiple conditions to a single combatant so I can track complex combat situations. **Why this priority**: Common in D&D play but the feature works with single conditions first. **Independent Test**: Can be tested by applying multiple conditions and verifying all appear as icon tags. **Acceptance Scenarios**: 1. **Given** a combatant with one active condition, **When** I open the picker and add another condition, **Then** both conditions appear as icon tags under the combatant name. 2. **Given** a combatant with multiple active conditions, **When** I view the combat row, **Then** all condition icons are displayed compactly without increasing the row width. 3. **Given** a combatant with many conditions (e.g., 5+), **When** I view the combat row, **Then** the row may grow slightly taller to accommodate wrapping condition icons but does not grow wider. 4. **Given** a combatant has "poisoned" applied first and "blinded" applied second, **When** I view the combat row, **Then** "blinded" appears before "poisoned" (fixed definition order, not insertion order). --- ### Edge Cases - What happens when all 15 conditions are applied to a single combatant? The icons wrap within the row, increasing row height but not width. - What happens when a combatant is removed from the encounter? Its conditions are removed with it (no orphaned condition data). - What happens when the picker is open and I click outside of it? The picker closes. - What happens when a condition is toggled on then immediately toggled off in the picker? The condition does not appear in the combat row. ## Requirements *(mandatory)* ### Functional Requirements - **FR-001**: The MVP MUST support the following 15 standard D&D 5e conditions: blinded, charmed, deafened, exhaustion, frightened, grappled, incapacitated, invisible, paralyzed, petrified, poisoned, prone, restrained, stunned, unconscious. MVP baseline does not include additional or homebrew conditions. - **FR-002**: Each condition MUST have a fixed icon and color mapping as follows: | Condition | Icon | Color | | -------------- | --------- | ------- | | Blinded | EyeOff | neutral | | Charmed | Heart | pink | | Deafened | EarOff | neutral | | Exhaustion | BatteryLow | amber | | Frightened | Siren | orange | | Grappled | Hand | neutral | | Incapacitated | Ban | gray | | Invisible | Ghost | violet | | Paralyzed | ZapOff | yellow | | Petrified | Gem | slate | | Poisoned | Droplet | green | | Prone | ArrowDown | neutral | | Restrained | Link | neutral | | Stunned | Sparkles | yellow | | Unconscious | Moon | indigo | - **FR-003**: Active conditions MUST appear as small icon tags below the combatant name in the combat row, displayed in the fixed definition order from FR-001 (blinded first, unconscious last), regardless of the order in which they were applied. - **FR-004**: The condition area MUST always display a small "+" button, regardless of whether the combatant has active conditions. When conditions are active, the "+" button appears after the last condition icon tag. - **FR-005**: Clicking the "+" button MUST open a compact condition picker showing all conditions as icon + label pairs. - **FR-006**: Clicking a condition in the picker MUST toggle it on or off for that combatant. - **FR-007**: Clicking an active condition icon tag in the combat row MUST remove that condition. - **FR-008**: Hovering over an active condition icon tag MUST display a tooltip with the condition name. - **FR-009**: Condition icons MUST NOT increase the width of the combat tracker; row height may increase slightly to accommodate wrapping. - **FR-010**: Conditions MUST be persisted as part of the combatant's state (surviving page reload via existing persistence). - **FR-011**: The condition data model MUST be extensible to support future additions (e.g., tooltips with descriptions, mechanical effects). - **FR-012**: No emoji icons may be used; all icons MUST come from the Lucide icon library. ### Key Entities - **Condition**: A status effect that can be applied to a combatant. Defined by a unique identifier (string literal), a display name, an associated icon, and a color category. - **CombatantConditions**: The set of active conditions on a given combatant. Stored as part of the combatant's state. A combatant may have zero or more active conditions; each condition can appear at most once per combatant. ## Success Criteria *(mandatory)* ### Measurable Outcomes - **SC-001**: A condition can be added to a combatant in 2 clicks or fewer (click "+", click condition). - **SC-002**: A condition can be removed from a combatant in 1 click (click the active icon tag). - **SC-003**: All 15 D&D 5e conditions are available and visually distinguishable by icon and color. - **SC-004**: The combat tracker maintains its current width when conditions are displayed; only row height may increase. - **SC-005**: Condition state survives a full page reload without data loss. - **SC-006**: Users can identify any condition by hovering over its icon to see the name tooltip. ## Clarifications ### Session 2026-03-06 - Q: In which order should active conditions be displayed in the combat row? -> A: Fixed definition order (blinded, charmed, ..., unconscious) as listed in FR-001. Order does not depend on when a condition was applied. - Q: Should the "+" button remain visible when conditions are already active? -> A: Yes, the "+" button is always visible alongside active condition tags, appearing after the last icon. ## Assumptions - The 15 conditions listed are the standard D&D 5e conditions and represent the complete set for MVP. Additional conditions (e.g., homebrew) are not included but the data model should not prevent future extension. - Color categories (neutral, pink, amber, orange, gray, violet, yellow, slate, green, indigo) map to subtle color classes already available in the project's design system. - The existing persistence mechanism will transparently handle the new condition data as part of combatant serialization. - The condition picker closes when a user clicks outside of it or when the user navigates away. - Conditions have no mechanical effects in MVP (e.g., "blinded" does not auto-impose disadvantage). The spec is purely for visual tracking.