initiative/specs/028-semantic-hover-tokens/plan.md

Implementation Plan: Semantic Hover Tokens

Branch: 028-semantic-hover-tokens | Date: 2026-03-10 | Spec: spec.md Input: Feature specification from /specs/028-semantic-hover-tokens/spec.md

Summary

Unify inconsistent hover color usage across all interactive UI components by introducing six semantic CSS custom property tokens (three text, three background) in the Tailwind v4 theme, then migrating all affected components from hardcoded hover classes to the new token-based classes. Purely presentational — no domain or application layer changes.

Technical Context

Language/Version: TypeScript 5.8 (strict mode, verbatimModuleSyntax) + React 19, Tailwind CSS v4, Vite 6 Primary Dependencies: Tailwind CSS v4 (CSS-native @theme theming), Lucide React (icons) Storage: N/A (no storage changes — purely presentational) Testing: Vitest (existing), manual visual verification for hover states Target Platform: Web (modern browsers) Project Type: Web application (React SPA) Performance Goals: N/A (no runtime behavior change) Constraints: Must preserve existing visual appearance with default token values Scale/Scope: 9 component files + 1 theme file + 1 UI primitive (button.tsx)

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	Changes confined to adapter layer (web UI)
III. Agent Boundary	N/A	No agent layer involvement
IV. Clarification-First	PASS	Spec has zero [NEEDS CLARIFICATION] markers; scope decisions documented in research.md
V. Escalation Gates	PASS	Research expanded scope to 8 files (from 5) based on audit — documented in R-002
VI. MVP Baseline Language	PASS	Three-tier system is MVP baseline; additional tiers not permanently excluded
VII. No Gameplay Rules	PASS	Purely presentational feature

Post-Phase 1 re-check: All gates still pass. The expanded component scope (stat-block-panel, bestiary-search, ac-shield) remains within adapter layer and serves the same hover unification goal.

Project Structure

Documentation (this feature)

specs/028-semantic-hover-tokens/
├── spec.md
├── plan.md              # This file
├── research.md          # Phase 0 output
├── data-model.md        # Phase 1 output
├── quickstart.md        # Phase 1 output
└── checklists/
    └── requirements.md  # Spec quality checklist

Source Code (repository root)

apps/web/src/
├── index.css                          # Theme tokens (add 6 new --color-hover-* properties)
└── components/
    ├── combatant-row.tsx              # 6× neutral text, 1× destructive text
    ├── condition-tags.tsx             # neutral text + bg
    ├── condition-picker.tsx           # neutral bg
    ├── turn-navigation.tsx            # 2× action text/border/bg, 1× action text, 1× destructive text
    ├── action-bar.tsx                 # neutral bg
    ├── ac-shield.tsx                  # neutral text
    ├── stat-block-panel.tsx           # neutral text (close buttons ×2)
    ├── bestiary-search.tsx            # neutral text + bg
    └── ui/button.tsx                  # outline + ghost variant hovers → neutral tokens

Structure Decision: No new files or directories. All changes are edits to existing theme and component files within the existing apps/web/src/ structure.