initiative/specs/019-combatant-row-declutter/plan.md

Implementation Plan: Combatant Row Declutter

Branch: 019-combatant-row-declutter | Date: 2026-03-06 | Spec: spec.md Input: Feature specification from /specs/019-combatant-row-declutter/spec.md

Summary

Replace always-visible HP adjustment controls (QuickHpInput with delta input + Sword/Heart buttons) and AC input field with compact, on-demand interaction patterns. HP becomes a clickable value that opens a popover for damage/healing. AC becomes a static shield+number display with click-to-edit inline editing. This is purely a web adapter (UI) change — domain and application layers are untouched.

Technical Context

Language/Version: TypeScript 5.8 (strict mode, verbatimModuleSyntax) Primary Dependencies: React 19, Vite 6, Tailwind CSS v4, Lucide React (icons) Storage: N/A (no storage changes — existing localStorage persistence unchanged) Testing: Vitest (unit tests for pure functions; UI behavior verified manually) Target Platform: Desktop and tablet-width browsers Project Type: Web application (monorepo with domain/application/web layers) Performance Goals: N/A (no performance-sensitive changes) Constraints: Keyboard-accessible, no domain/application layer modifications Scale/Scope: 1 component modified (CombatantRow), 1 component removed (QuickHpInput), 1 new component (HpAdjustPopover). AC and Max HP click-to-edit are implemented inline within CombatantRow (no separate component files)

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

Principle	Status	Notes
I. Deterministic Domain Core	PASS	No domain changes
II. Layered Architecture	PASS	All changes in adapter layer (apps/web) only
III. Agent Boundary	N/A	No agent features involved
IV. Clarification-First	PASS	Feature description was fully specified, no ambiguities
V. Escalation Gates	PASS	All changes within spec scope
VI. MVP Baseline Language	PASS	No permanent bans introduced
VII. No Gameplay Rules	PASS	No gameplay mechanics in plan

Pre-design gate: PASS — no violations.

Project Structure

Documentation (this feature)

specs/019-combatant-row-declutter/
├── plan.md              # This file
├── research.md          # Phase 0 output
├── data-model.md        # Phase 1 output
├── quickstart.md        # Phase 1 output
└── tasks.md             # Phase 2 output (/speckit.tasks command)

Source Code (repository root)

apps/web/src/components/
├── combatant-row.tsx        # MODIFY: replace CurrentHpInput with clickable display + popover,
│                            #         replace AcInput with click-to-edit static display
├── hp-adjust-popover.tsx    # NEW: popover with numeric input + Damage/Heal buttons
├── quick-hp-input.tsx       # REMOVE: replaced by hp-adjust-popover
└── ui/
    ├── button.tsx           # existing (used by popover)
    └── input.tsx            # existing (used by popover and AC inline edit)

Structure Decision: All changes are confined to apps/web/src/components/. No new directories needed. The existing monorepo structure (domain → application → web) is preserved. No contracts directory needed since this is an internal UI refactor with no external interfaces.

Post-Design Constitution Re-Check

Principle	Status	Notes
I. Deterministic Domain Core	PASS	No domain changes
II. Layered Architecture	PASS	Only adapter-layer files touched
IV. Clarification-First	PASS	No new ambiguities introduced
V. Escalation Gates	PASS	All within spec scope

Post-design gate: PASS — no violations.