design: kpi counter reduced-motion variant #492

[RemmyAcee]

Overview

This PR implements a reduced-motion variant for the KPI counter animations. Users who enable reduce motion at the OS level now get the final value rendered immediately with a subtle opacity fade, eliminating the numeric ticking that can be distracting.

Related Issue

Closes #492

Changes

🎯 KPI Counter Reduced-Motion

• [MODIFY] src/components/KpiHeader.tsx
  • AnimatedValue component now gates its
    equestAnimationFrame loop behind useReducedMotion()
  • When reduced motion is active, renders the final value immediately inside .animate-fade-in (opacity-only fade)
  • Handles mid-animation toggles: cancels pending frames when reduced preference flips on, restarts animation when flipped off
• [ADD] src/hooks/useReducedMotion.test.ts
  • Unit tests for prefers-reduced-motion detection: synchronous initial read, live change events, listener teardown, legacy addListener fallback
• [MODIFY] src/components/KpiHeader.test.tsx
  • Added test suites for default counting behaviour, reduced-motion variant, mid-animation toggles, and non-numeric fallback
• [ADD] docs/uiux/kpi-counter-reduced-motion.md
  • Design system documentation covering behaviour table, tokens, usage guidance, and accessibility notes
• [MODIFY] docs/uiux/reduced-motion-guidelines.md
  • Referenced the KPI counter pattern as the canonical example

Verification Results

npm run test -- --run src/components/KpiHeader.test.tsx src/hooks/useReducedMotion.test.ts ✅ 30/30 passed

Acceptance Criteria	Status
Reduced-motion detection uses prefers-reduced-motion	✅ useReducedMotion() hook with live change events
Final value presented immediately (no ticking)	✅ rAF loop gated behind hook
Subtle fade affordance	✅ .animate-fade-in with --transition-base token
Mid-animation toggle handled	✅ Frames cancelled, final value restored
WCAG 2.1 AA compliant	✅ Opacity-only fade, ≤0.4s, screen-reader identical
Design system documented	✅ docs/uiux/kpi-counter-reduced-motion.md

Accessibility

• Supports WCAG 2.1 AA — addresses Success Criterion 2.3.3 Animation from Interactions
• The fade is opacity-only and short (≤0.4s)
• Values are identical text content in both modes
• No information conveyed by the animation itself

[drips-wave]

@RemmyAcee Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits