Files

Lukas 99d1ba1bcd Implement the 028-semantic-hover-tokens feature that unifies hover colors across all interactive UI components via six CSS custom property tokens (three text, three background) defined in the Tailwind v4 theme, replacing hardcoded hover classes in 9 component files plus the shared Button primitive with semantic token references so all hover colors can be globally reconfigured from one place

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-03-10 19:50:22 +01:00

7.8 KiB

Raw Blame History

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)

Complete Phase 1: Define tokens (T001)
Complete Phase 2: Migrate all components (T002–T010)
STOP and VALIDATE: Verify all hover tiers visually
Complete Phase 3: Audit for remaining hardcoded hovers (T011)
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

7.8 KiB Raw Blame History Unescape Escape