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

Tasks: Semantic Hover Tokens

Input: Design documents from /specs/028-semantic-hover-tokens/ Prerequisites: plan.md, spec.md, research.md, data-model.md, quickstart.md

Tests: No test tasks — feature is purely presentational with manual visual verification.

Organization: Tasks grouped by user story. US1 and US2 are both P1 and share implementation work (defining tokens + migrating components), so they are combined into one phase.

Format: [ID] [P?] [Story] Description

• [P]: Can run in parallel (different files, no dependencies)
• [Story]: Which user story this task belongs to (e.g., US1, US2, US3)
• Include exact file paths in descriptions

Phase 1: Setup (Theme Token Definitions)

Purpose: Define the six semantic hover tokens in the theme

• T001 Add six --color-hover-* CSS custom properties to the @theme block in apps/web/src/index.css: --color-hover-neutral: var(--color-foreground), --color-hover-action: var(--color-primary), --color-hover-destructive: var(--color-destructive), --color-hover-neutral-bg: var(--color-card), --color-hover-action-bg: var(--color-muted), --color-hover-destructive-bg: transparent

Checkpoint: Tokens defined — Tailwind now generates text-hover-neutral, bg-hover-neutral-bg, etc. utility classes

---

Phase 2: User Story 1 + User Story 2 — Token Migration (Priority: P1)

Goal: Migrate all hover color references in affected components from hardcoded values to the semantic tokens, ensuring correct tier assignment per element

Independent Test: Hover over every interactive element and verify: editable fields show grey-to-white (neutral), navigation/add buttons show blue (action), remove/clear buttons show red (destructive). Then change each token value in DevTools and confirm all elements in that tier update.

Neutral-Interactive Tier

• T002 [P] [US1] Migrate combatant-row.tsx neutral hovers: replace 5× hover:text-primary with hover:text-hover-neutral on EditableName, MaxHpDisplay, ClickableHp, initiative d20 button, and initiative value button in apps/web/src/components/combatant-row.tsx
• T002b [P] [US1] Migrate ac-shield.tsx neutral hover: replace hover:text-primary with hover:text-hover-neutral on the AC shield button in apps/web/src/components/ac-shield.tsx
• T003 [P] [US1] Migrate condition-tags.tsx neutral hovers: replace hover:bg-card with hover:bg-hover-neutral-bg on condition icon buttons, and replace hover:text-foreground hover:bg-card with hover:text-hover-neutral hover:bg-hover-neutral-bg on the add condition (+) button in apps/web/src/components/condition-tags.tsx
• T004 [P] [US1] Migrate condition-picker.tsx neutral hover: replace hover:bg-card with hover:bg-hover-neutral-bg on condition row items in apps/web/src/components/condition-picker.tsx
• T005 [P] [US1] Migrate action-bar.tsx neutral hover: replace hover:bg-accent/10 with hover:bg-hover-neutral-bg on bestiary search result items in apps/web/src/components/action-bar.tsx
• T006 [P] [US1] Migrate stat-block-panel.tsx neutral hovers: replace 2× hover:text-foreground with hover:text-hover-neutral on the desktop close button and mobile close button in apps/web/src/components/stat-block-panel.tsx
• T007 [P] [US1] Migrate bestiary-search.tsx neutral hovers: replace hover:text-foreground with hover:text-hover-neutral on the close button, and replace hover:bg-accent/10 with hover:bg-hover-neutral-bg on search result items in apps/web/src/components/bestiary-search.tsx

Primary-Action Tier

• T008 [P] [US2] Migrate turn-navigation.tsx action hovers: replace hover:text-primary hover:border-primary hover:bg-muted with hover:text-hover-action hover:border-hover-action hover:bg-hover-action-bg on Previous/Next buttons, and replace hover:text-primary with hover:text-hover-action on the Roll All button in apps/web/src/components/turn-navigation.tsx

Destructive-Action Tier

• T009 [P] [US2] Migrate combatant-row.tsx destructive hover: replace hover:text-destructive with hover:text-hover-destructive on the remove button (X) in apps/web/src/components/combatant-row.tsx
• T010 [US2] Migrate turn-navigation.tsx destructive hover: replace hover:text-destructive with hover:text-hover-destructive on the Clear button in apps/web/src/components/turn-navigation.tsx

Checkpoint: All components use semantic hover tokens. Hovering shows correct tier colors. Changing any token in DevTools updates all elements in that tier.

---

Phase 3: User Story 3 — Eliminate One-Off Hover Colors (Priority: P2)

Goal: Verify no hardcoded hover color values remain in the affected components and eliminate any one-offs (e.g., amber)

Independent Test: Search all affected component files for hover:text- and hover:bg- classes that don't reference hover-neutral, hover-action, or hover-destructive tokens. Zero matches expected.

• T011 [US3] Audit all affected components for remaining hardcoded hover colors: grep for hover:text- and hover:bg- patterns in apps/web/src/components/{combatant-row,condition-tags,condition-picker,turn-navigation,action-bar,stat-block-panel,bestiary-search}.tsx and replace any remaining non-token hover colors (including any amber one-off) with the appropriate semantic token

Checkpoint: Zero hardcoded hover color values in affected components

---

Phase 4: Polish & Cross-Cutting Concerns

Purpose: Validate everything passes and no regressions

• T012 Run pnpm check to verify all linting, formatting, type checking, and tests pass
• T013 Visual regression check: start dev server with pnpm --filter web dev and manually verify all hover states per quickstart.md scenarios

---

Dependencies & Execution Order

Phase Dependencies

• Setup (Phase 1): No dependencies — start immediately
• US1+US2 (Phase 2): Depends on T001 (tokens must exist before components can reference them)
• US3 (Phase 3): Depends on Phase 2 completion (audit after migration)
• Polish (Phase 4): Depends on all previous phases

User Story Dependencies

• US1 (P1): Needs tokens defined (T001), then component migrations (T002–T007)
• US2 (P1): Needs tokens defined (T001), then component migrations (T008–T010). Can run in parallel with US1 tasks.
• US3 (P2): Depends on US1+US2 completion — audit step

Parallel Opportunities

• T002–T010 are all [P] — different files, no dependencies between them. All can run in parallel after T001.
• T008+T010 both modify turn-navigation.tsx but are sequential (T008 handles action tier, T010 handles destructive tier in the same file).

---

Parallel Example: Phase 2

# After T001 completes, launch all component migrations in parallel:
Task: "T002 - combatant-row neutral hovers"
Task: "T002b - ac-shield neutral hover"
Task: "T003 - condition-tags neutral hovers"
Task: "T004 - condition-picker neutral hover"
Task: "T005 - action-bar neutral hover"
Task: "T006 - stat-block-panel neutral hover"
Task: "T007 - bestiary-search neutral hovers"
Task: "T008 - turn-navigation action hovers"
Task: "T009 - combatant-row destructive hover"
# Then T010 after T008 (same file: turn-navigation.tsx)

---

Implementation Strategy

MVP First (US1 + US2)

1. Complete Phase 1: Define tokens (T001)
2. Complete Phase 2: Migrate all components (T002–T010)
3. STOP and VALIDATE: Verify all hover tiers visually
4. Complete Phase 3: Audit for remaining hardcoded hovers (T011)
5. Complete Phase 4: Run checks and visual regression

Notes

• [P] tasks = different files, no dependencies
• T008 and T010 both touch turn-navigation.tsx — run T010 after T008
• T002 and T009 both touch combatant-row.tsx — run T009 after T002
• Commit after each phase or logical group
• No domain/application layer changes needed