feat(a11y): remediate axe violations, add live regions, keyboard nav, reduced-motion

Author: Debbys-design

.github/workflows/ci.yml

@@ -167,3 +167,37 @@ jobs:
       - run: npm run check-docs
       - run: npm run build
       - run: npm test
+
+  # ── Accessibility (axe) ───────────────────────────────────────────────────
+  accessibility:
+    name: Accessibility (axe / Playwright)
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: frontend
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+
+      - run: npm ci
+      - run: npm run build
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps chromium
+
+      - name: Run axe accessibility checks
+        run: npx playwright test tests/accessibility.spec.ts --reporter=list
+        env:
+          BASE_URL: http://localhost:3000
+
+      - uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: axe-report-${{ github.sha }}
+          path: frontend/playwright-report/
+          retention-days: 14

CONTRIBUTING.md

@@ -0,0 +1,81 @@
+# Contributing to NiffyInsur
+
+## Accessibility Testing
+
+Accessibility is a first-class requirement. Every PR that touches UI must pass the checks below before merge.
+
+### Automated axe checks (CI)
+
+The `accessibility` CI job runs `@axe-core/playwright` against the quote, policy, claims, and vote routes. **No critical violations are permitted.** The job uploads a Playwright report as an artifact on failure.
+
+Run locally:
+
+```bash
+cd frontend
+npm install
+npm run build
+npx playwright test tests/accessibility.spec.ts
+```
+
+### Manual axe spot-check
+
+1. Install the [axe DevTools browser extension](https://www.deque.com/axe/devtools/).
+2. Open each targeted route: `/quote`, `/policy`, `/claims`, `/claims/<id>`.
+3. Run the full-page scan. Resolve any **critical** or **serious** violations before opening a PR.
+
+### Keyboard-only walkthrough
+
+Verify these flows using only the keyboard (no mouse):
+
+| Flow | Steps |
+|------|-------|
+| Get a quote | Tab through all form fields → submit → confirm quote preview updates |
+| Purchase policy | Complete all 4 wizard steps using Tab / Shift+Tab / Enter / Space |
+| File a claim | Complete all 4 wizard steps; confirm focus moves to new step heading on advance |
+| Cast a vote | Tab to Approve / Reject buttons → Enter to open confirm modal → Tab within modal → confirm or cancel |
+| Connect wallet | Tab to "Connect Wallet" button → Enter → confirm status announced |
+
+Focus must always be visible. After a modal opens, focus must move inside it. After a modal closes, focus must return to the trigger.
+
+### Screen reader spot-check (per major release)
+
+Test at minimum one major flow per release with a screen reader:
+
+- **macOS / iOS**: VoiceOver (`Cmd+F5` to toggle)
+- **Windows**: NVDA (free) or Narrator
+- **Android**: TalkBack
+
+Checklist:
+- [ ] Transaction status updates are announced (aria-live regions on wizard and policy pages)
+- [ ] Step changes in wizards are announced (focus moves to hidden `<h2>` with step name)
+- [ ] Quote preview updates are announced on the quote page
+- [ ] Vote tally countdown is announced via `aria-live="polite"`
+- [ ] Modal title is read when dialog opens
+- [ ] Icon-only buttons have accessible names (aria-label or sr-only text)
+- [ ] Claim status badges convey outcome via text/shape, not color alone
+
+### Reduced-motion
+
+Verify that setting `prefers-reduced-motion: reduce` (OS accessibility setting or DevTools emulation) stops all non-essential animations. Loading spinners should become static; slide/fade transitions should be instant.
+
+### Heading hierarchy
+
+Each page must have exactly one `<h1>`. Use the browser Accessibility Tree panel (DevTools → Accessibility) or the [HeadingsMap extension](https://rumoroso.bitbucket.io/headingsmap/) to verify a logical heading order with no skipped levels.
+
+### Landmarks
+
+Every page must have at minimum: `<main>`, `<nav>` (if navigation present), and `<footer>` (if present). Verify with the Accessibility Tree or axe.
+
+### Color contrast
+
+All text must meet WCAG AA contrast ratios (4.5:1 normal text, 3:1 large text). Use the axe scan or the browser color-contrast checker. Claim outcomes (Approved / Rejected / Pending) must not rely on color alone — shape indicators and text labels are required.
+
+### Adding new UI
+
+When adding new interactive components:
+
+1. Icon-only controls **must** have `aria-label` or a visually hidden label.
+2. Async state changes (transactions, loading) **must** update an `aria-live` region.
+3. Multi-step wizards **must** move focus to a step heading on step change.
+4. Modals **must** trap focus and return it to the trigger on close (Radix Dialog handles this automatically).
+5. Animations **must** respect `prefers-reduced-motion` via the global CSS rule in `globals.css`.

frontend/package.json

@@ -45,6 +45,8 @@
     "postcss": "^8.5.8",
     "tailwindcss": "^4.2.2",
     "ts-jest": "^29.4.6",
-    "typescript": "^5"
+    "typescript": "^5",
+    "@axe-core/playwright": "^4.10.1",
+    "@playwright/test": "^1.49.0"
   }
 }

frontend/playwright.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests',
+  timeout: 30_000,
+  use: {
+    baseURL: process.env.BASE_URL ?? 'http://localhost:3000',
+    headless: true,
+  },
+  webServer: process.env.BASE_URL
+    ? undefined
+    : {
+        command: 'npm run build && npx next start',
+        url: 'http://localhost:3000',
+        reuseExistingServer: !process.env.CI,
+        timeout: 120_000,
+      },
+});

frontend/src/app/globals.css

@@ -121,4 +121,10 @@
     transition-duration: 0.01ms !important;
     scroll-behavior: auto !important;
   }
+
+  /* Tailwind animate-spin is used on loading spinners — keep it visible but
+     instant so the element is still present for screen readers without motion */
+  .animate-spin {
+    animation: none !important;
+  }
 }

frontend/src/components/claims/ClaimWizard.tsx

@@ -1,14 +1,14 @@
 'use client';
 
-import React, { useState } from 'react';
+import React, { useState, useRef, useEffect } from 'react';
 import { useRouter } from 'next/navigation';
 import { Stepper, StepContent, Card, CardHeader, CardTitle, CardDescription, CardContent, Button, useToast } from '@/components/ui';
 import { AmountStep } from './steps/AmountStep';
 import { NarrativeStep } from './steps/NarrativeStep';
 import { EvidenceStep } from './steps/EvidenceStep';
 import { ReviewStep } from './steps/ReviewStep';
 import { ClaimAPI } from '@/lib/api/claim';
-import { useWallet } from '@/hooks/use-wallet'; // Assuming this exists based on common patterns
+import { useWallet } from '@/hooks/use-wallet';
 import { Loader2, ArrowLeft, ArrowRight, CheckCircle } from 'lucide-react';
 
 interface ClaimWizardProps {
@@ -30,13 +30,22 @@ export function ClaimWizard({ policyId, maxCoverage }: ClaimWizardProps) {
   const [activeStep, setActiveStep] = useState(0);
   const [isSubmitting, setIsSubmitting] = useState(false);
   const [isSuccess, setIsSuccess] = useState(false);
+  const [txStatus, setTxStatus] = useState<string>('');
+  const stepHeadingRef = useRef<HTMLHeadingElement>(null);
 
   const [formData, setFormData] = useState({
     amount: '',
     details: '',
     imageUrls: [] as string[],
   });
 
+  // Move focus to step heading when step changes
+  useEffect(() => {
+    if (stepHeadingRef.current) {
+      stepHeadingRef.current.focus();
+    }
+  }, [activeStep]);
+
   const handleNext = () => {
     if (activeStep < STEPS.length - 1) {
       setActiveStep(prev => prev + 1);
@@ -65,7 +74,7 @@ export function ClaimWizard({ policyId, maxCoverage }: ClaimWizardProps) {
 
     setIsSubmitting(true);
     try {
-      // 1. Build unsigned transaction on backend
+      setTxStatus('Building transaction…');
       const { unsignedXdr } = await ClaimAPI.buildTransaction({
         holder: address,
         policyId: parseInt(policyId),
@@ -74,28 +83,29 @@ export function ClaimWizard({ policyId, maxCoverage }: ClaimWizardProps) {
         imageUrls: formData.imageUrls,
       });
 
-      // 2. Sign with wallet
+      setTxStatus('Waiting for wallet signature…');
       const signedXdr = await signTransaction(unsignedXdr);
 
-      // 3. Submit signed transaction
+      setTxStatus('Submitting transaction to network…');
       await ClaimAPI.submitTransaction(signedXdr);
 
-      // 4. Success handling
+      setTxStatus('Claim submitted successfully.');
       setIsSuccess(true);
       toast({
         title: 'Claim Submitted!',
         description: 'Your claim has been successfully filed on-chain.',
       });
 
-      // Redirect after a delay
       setTimeout(() => {
         router.push(`/policy/${policyId}`);
       }, 3000);
     } catch (error) {
+      const msg = error instanceof Error ? error.message : 'An unexpected error occurred.';
+      setTxStatus(`Submission failed: ${msg}`);
       console.error('Submission failed:', error);
       toast({
         title: 'Submission Failed',
-        description: error instanceof Error ? error.message : 'An unexpected error occurred.',
+        description: msg,
         variant: 'destructive',
       });
     } finally {
@@ -107,7 +117,10 @@ export function ClaimWizard({ policyId, maxCoverage }: ClaimWizardProps) {
     return (
       <Card className="mx-auto max-w-2xl text-center py-12">
         <CardContent className="space-y-6">
-          <div className="mx-auto flex h-20 w-20 items-center justify-center rounded-full bg-green-100 text-green-600 dark:bg-green-900/30">
+          <div
+            className="mx-auto flex h-20 w-20 items-center justify-center rounded-full bg-green-100 text-green-600 dark:bg-green-900/30"
+            aria-hidden="true"
+          >
             <CheckCircle className="h-12 w-12" />
           </div>
           <div className="space-y-2">
@@ -126,6 +139,11 @@ export function ClaimWizard({ policyId, maxCoverage }: ClaimWizardProps) {
 
   return (
     <Card className="mx-auto max-w-3xl">
+      {/* Live region announces tx progress to screen readers */}
+      <div role="status" aria-live="polite" aria-atomic="true" className="sr-only">
+        {txStatus}
+      </div>
+
       <CardHeader>
         <div className="flex items-center justify-between">
           <div>
@@ -137,11 +155,21 @@ export function ClaimWizard({ policyId, maxCoverage }: ClaimWizardProps) {
           <Stepper
             steps={STEPS.map((s, i) => ({ ...s, status: i < activeStep ? 'completed' : i === activeStep ? 'active' : 'pending' as const }))}
             currentStep={activeStep}
+            aria-label="Claim filing steps"
             className="hidden md:flex"
           />
         </div>
       </CardHeader>
       <CardContent className="space-y-6">
+        {/* Visually hidden heading receives focus on step change */}
+        <h2
+          ref={stepHeadingRef}
+          tabIndex={-1}
+          className="sr-only focus:not-sr-only focus:outline-none"
+        >
+          Step {activeStep + 1} of {STEPS.length}: {STEPS[activeStep].title}
+        </h2>
+
         <StepContent title={STEPS[0].title} isActive={activeStep === 0} isCompleted={activeStep > 0}>
           <AmountStep
             amount={formData.amount}
@@ -169,32 +197,33 @@ export function ClaimWizard({ policyId, maxCoverage }: ClaimWizardProps) {
         </StepContent>
 
         <div className="flex justify-between pt-4 border-t">
-          <Button 
-            variant="ghost" 
+          <Button
+            variant="ghost"
             onClick={handleBack}
             disabled={isSubmitting}
           >
-            <ArrowLeft className="mr-2 h-4 w-4" />
+            <ArrowLeft className="mr-2 h-4 w-4" aria-hidden="true" />
             {activeStep === 0 ? 'Cancel' : 'Back'}
           </Button>
-          <Button 
+          <Button
             onClick={handleNext}
             disabled={
-              isSubmitting || 
+              isSubmitting ||
               (activeStep === 0 && !formData.amount) ||
               (activeStep === 1 && !formData.details) ||
               (activeStep === 3 && isSubmitting)
             }
+            aria-busy={isSubmitting}
           >
             {isSubmitting ? (
               <>
-                <Loader2 className="mr-2 h-4 w-4 animate-spin" />
-                Processing...
+                <Loader2 className="mr-2 h-4 w-4 animate-spin" aria-hidden="true" />
+                Processing…
               </>
             ) : (
               <>
                 {activeStep === STEPS.length - 1 ? 'Sign & Submit' : 'Next'}
-                <ArrowRight className="ml-2 h-4 w-4" />
+                <ArrowRight className="ml-2 h-4 w-4" aria-hidden="true" />
               </>
             )}
           </Button>