feat(frontend): comprehensive WCAG 2.1 AA accessibility improvements by Richardkingz2019 · Pull Request #356 · AetherEdu/AetherMint

Richardkingz2019 · 2026-07-25T21:15:35Z

Description

This PR delivers a comprehensive suite of WCAG 2.1 AA accessibility (a11y) improvements across the AetherMint frontend, establishing a strong foundation for inclusive design. Every change is auditable via the new axe-core E2E test suite and enforced through a dedicated CI job.

Closes #271

Summary of Changes

1. New: Accessibility Statement Page (`/accessibility`)

A fully accessible, WCAG-compliant public-facing statement page that communicates our commitment and conformance status:

Conformance Status — documents partial conformance with WCAG 2.1 Level AA
Accessibility Features — keyboard nav, screen reader support, color blindness filters, adaptive settings
Known Limitations — third-party wallet integrations, 3D/WebGL components, legacy course content
Measures Taken — CI audits, manual keyboard testing, screen reader testing (NVDA/JAWS/VoiceOver), color contrast validation
Assessment Approach — automated axe-core scanning, manual audits, focus order verification
Feedback & Contact — email and GitHub issue links with response-time SLAs
Technical Specifications — HTML5, WAI-ARIA, CSS, React/Next.js, Web Speech API

2. New: Automated A11y E2E Test Suite (`e2e/accessibility.spec.ts`)

Uses @axe-core/playwright to scan 12 key pages for WCAG 2.1 A/AA violations
Asserts zero critical violations on every page
Tests: skip-to-content link presence, keyboard focus visibility, color contrast (4.5:1 ratio), ARIA landmarks (main, navigation, banner), image alt text, button accessible names
Outputs JSON, HTML, and JUnit reports for CI artifact collection

3. New: CI Job — `test-a11y` (`.github/workflows/ci.yml`)

Runs after build-frontend in parallel with existing E2E tests
Installs Playwright Chromium, runs accessibility.spec.ts
Uploads a11y-test-report artifact (retained 7 days)

4. CSS/Design System: Accessibility Modes (`frontend/src/app/globals.css`)

Feature	WCAG Criterion	Description
Focus Management	2.4.7 (Focus Visible)	`:focus-visible` with 3px blue ring + offset; `:focus:not(:focus-visible)` removes mouse-only outlines
Reduced Motion	2.3.3 (Animation from Interactions)	`prefers-reduced-motion` media query + `.reduce-motion` class override
High Contrast Mode	1.4.6 (Contrast Enhanced)	`.high-contrast` class forces black-on-white with underlined links and visible borders
Color Blind Filters	1.4.1 (Use of Color)	`.colorblind-protanopia`, `.colorblind-deuteranopia`, `.colorblind-tritanopia` SVG filter classes
Simplified UI	Cognitive Accessibility	`.simplified-ui` hides decorative elements and disables animations
Keyboard Nav Mode	2.1.1 (Keyboard)	`.keyboard-nav-enabled` forces thick outlines on all focused elements
Visual Indicators	2.4.7	`.visual-indicators-enabled` adds glow to focus-visible on interactive elements

5. Tailwind Config Extension (`tailwind.config.js`)

WCAG color palette (primary-50 to primary-950) ensuring 4.5:1 minimum contrast
Responsive type scale — display, h1–h3, body, body-sm with proper line heights
Touch-friendly minimum target sizes — touch: 2.75rem (44px, WCAG 2.5.5)

6. Component Accessibility Upgrades

`AdminSidebar.tsx`

role="navigation" with aria-labelledby pointing to sidebar title
Sidebar items wrapped in <ul role="list"> / <li role="listitem">
aria-expanded on collapsible items, aria-current="page" for active item
aria-label on collapse/expand toggle button
Icons marked aria-hidden="true"

`AdminHeader.tsx`

aria-label and aria-expanded on notification bell and user menu buttons
aria-haspopup="true" on dropdown triggers
Notification list uses role="list" / role="listitem" with aria-labelledby
Search icon marked aria-hidden="true", input has <label htmlFor> + sr-only label
All buttons have visible focus rings

`AdminLayout.tsx` (`admin/layout.tsx`)

Removed redundant <html>/<body> wrapper (handled by root layout)
Added skip-to-content link (#admin-main-content)
<aside role="navigation"> wrapping sidebar
<header role="banner"> wrapping admin header
<main id="admin-main-content" role="main" tabIndex={-1}> for focus management

`ErrorBoundary.tsx`

Container uses role="alert" and aria-live="assertive"
Error icon marked aria-hidden="true"
Error title has id="error-boundary-title"
Details <summary> has visible focus ring
<pre> block is keyboard-focusable (tabIndex={0})
Retry button has aria-label="Try again"

`LoadingFallback.tsx` / `LoadingSpinner`

role="status" and aria-live="polite" for dynamic content announcements
aria-label set to loading message
Hidden <span className="sr-only"> for screen readers
Spinner icon marked aria-hidden="true"

7. Root Layout (`layout.tsx`)

Added footer with role="contentinfo" and aria-label="Site footer"
Accessibility Statement link (/accessibility)
Report Issue link (opens GitHub Issues in new tab with rel="noopener noreferrer")

8. Configuration & Dependencies

next.config.js: Added default Stellar testnet receiver address for local dev/CI environments
package.json: Added @axe-core/playwright dev dependency

Files Changed

File	Status	Lines
`.github/workflows/ci.yml`	Modified	+40
`frontend/e2e/accessibility.spec.ts`	New	+158
`frontend/next.config.js`	Modified	+6
`frontend/package.json`	Modified	+1
`frontend/src/app/accessibility/page.tsx`	New	+210
`frontend/src/app/admin/layout.tsx`	Modified	+29 / -22
`frontend/src/app/globals.css`	Modified	+138 / -12
`frontend/src/app/layout.tsx`	Modified	+22
`frontend/src/components/Admin/AdminHeader.tsx`	Modified	+21 / -11
`frontend/src/components/Admin/AdminSidebar.tsx`	Modified	+33 / -19
`frontend/src/components/ErrorBoundary.tsx`	Modified	+12 / -7
`frontend/src/components/LoadingFallback.tsx`	Modified	+16 / -4
`frontend/tailwind.config.js`	Modified	+29
`package-lock.json`	Modified	+24

Total: 14 files, +766 / −65 lines

Type of Change

New feature (non-breaking change which adds functionality)
Bug fix (accessibility gaps)
CI/CD enhancement

Testing

Automated

axe-core E2E: Scans 12 pages for WCAG 2.1 A/AA violations; fails on critical violations
Keyboard navigation: Tab order, focus visibility, skip-to-content link verification
Color contrast: WCAG AA ratio (4.5:1) enforcement
ARIA landmarks: main, navigation, banner role presence
Screen reader: Image alt text and button accessible name checks

CI Pipeline

New test-a11y job runs on every PR push
Artifacts uploaded and retained for 7 days

Manual Validation Checklist

Keyboard-only navigation works on all 12 audited pages
Screen reader (NVDA/JAWS/VoiceOver) reads page content correctly
High contrast mode renders all elements with sufficient contrast
Reduced motion disables all animations
Color blindness filters apply correctly
Skip-to-content links function on root and admin layouts

Checklist

My code follows the style guidelines of this project
I have performed a self-review of my own code
I have commented my code, particularly in hard-to-understand areas
All icons are marked aria-hidden="true"
All interactive elements have visible focus indicators
All pages have proper ARIA landmark roles
Color palette meets WCAG 2.1 AA contrast ratios
Touch targets are at least 44×44px

- Add accessibility statement page (/accessibility) with conformance status, features list, known limitations, contact info & assessment approach - Add axe-core/Playwright E2E a11y audit suite covering 12 key pages - Add test-a11y CI job for automated WCAG 2.1 AA compliance checks - Add WCAG-compliant focus management with :focus-visible outlines - Add prefers-reduced-motion support and .reduce-motion class - Add high-contrast mode, color blindness filters (protanopia, deuteranopia, tritanopia), and simplified UI mode for cognitive accessibility - Add keyboard navigation mode with visible focus indicators - Add ARIA landmarks, labels, roles across Admin layout, sidebar, header, ErrorBoundary, and LoadingFallback components - Add skip-to-content links for admin and root layouts - Add accessible footer with accessibility statement & issue report links to root layout - Extend Tailwind config with WCAG color palette, responsive type scale, and touch-friendly minimum target sizes (2.75rem / 44px) - Add default testnet Stellar receiver address for local dev / CI - Add @axe-core/playwright dev dependency Closes AetherEdu#271

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(frontend): comprehensive WCAG 2.1 AA accessibility improvements#356

feat(frontend): comprehensive WCAG 2.1 AA accessibility improvements#356
Richardkingz2019 wants to merge 1 commit into
AetherEdu:mainfrom
Richardkingz2019:feat/comprehensive-a11y-improvements

Richardkingz2019 commented Jul 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

Richardkingz2019 commented Jul 25, 2026

Description

Summary of Changes

1. New: Accessibility Statement Page (/accessibility)

2. New: Automated A11y E2E Test Suite (e2e/accessibility.spec.ts)

3. New: CI Job — test-a11y (.github/workflows/ci.yml)

4. CSS/Design System: Accessibility Modes (frontend/src/app/globals.css)

5. Tailwind Config Extension (tailwind.config.js)

6. Component Accessibility Upgrades

AdminSidebar.tsx

AdminHeader.tsx

AdminLayout.tsx (admin/layout.tsx)

ErrorBoundary.tsx

LoadingFallback.tsx / LoadingSpinner

7. Root Layout (layout.tsx)

8. Configuration & Dependencies

Files Changed

Type of Change

Testing

Automated

CI Pipeline

Manual Validation Checklist

Checklist

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

1. New: Accessibility Statement Page (`/accessibility`)

2. New: Automated A11y E2E Test Suite (`e2e/accessibility.spec.ts`)

3. New: CI Job — `test-a11y` (`.github/workflows/ci.yml`)

4. CSS/Design System: Accessibility Modes (`frontend/src/app/globals.css`)

5. Tailwind Config Extension (`tailwind.config.js`)

`AdminSidebar.tsx`

`AdminHeader.tsx`

`AdminLayout.tsx` (`admin/layout.tsx`)

`ErrorBoundary.tsx`

`LoadingFallback.tsx` / `LoadingSpinner`

7. Root Layout (`layout.tsx`)