Enterprise Accessibility Standards (WCAG 2.1 AA)

This document is the authoritative engineering specification for accessibility (a11y) design, component engineering, screen reader compatibility, and automated auditing across the Debelu platform. Grounded directly in [DESIGN.md](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/DESIGN.md), [playwright.config.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/playwright.config.ts), and [@axe-core/playwright](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/package.json), this specification guarantees full digital inclusion for university students and merchants of all abilities.

---

1. Compliance Standard & Legal Mandate

Debelu commits to meeting Web Content Accessibility Guidelines (WCAG) 2.1 Level AA standards across all digital surfaces (app.debelu.com, debelu.com, and native mobile shells). Ensuring inclusive commerce across Nigerian university campuses guarantees that visually impaired, neurodivergent, and motor-impaired students have equitable access to marketplace goods, financial escrow, and student services.

graph TD
    WCAG[WCAG 2.1 Level AA Standard] --> P1[1. Perceivable: Contrast & Media Alternatives]
    WCAG --> P2[2. Operable: Keyboard Navigation & Touch Targets]
    WCAG --> P3[3. Understandable: Predictable Forms & Clear Error Messages]
    WCAG --> P4[4. Robust: Radix Primitives & Screen Reader Semantics]

    P1 --> Audit[Automated Axe-Core Auditing in CI]
    P2 --> Audit
    P3 --> Audit
    P4 --> Audit

---

2. Color Contrast & Visual Design Standards

All visual tokens defined in @debelu/ui/src/theme.css must pass contrast validation algorithms before deployment:

Visual Element	Minimum Contrast Ratio	Implementation Standard (from DESIGN.md)
Normal Body Text ($< 18$pt)	$\ge 4.5:1$	Dark slate #1E293B on light neutral #F5F5F7 ($12.8:1$).
Large Headings ($\ge 18$pt / $\ge 14$pt bold)	$\ge 3.0:1$	Brand emerald #1B5E20 on pure white surface #FFFFFF ($7.4:1$).
UI Components & Graphical Icons	$\ge 3.0:1$	Input borders #CBD5E1 and active icon fills on backgrounds.
Active Focus Rings	$\ge 3.0:1$	High-visibility focus indicator ring token (--ring: #16A34A).
Form Error Validation Messages	$\ge 4.5:1$	Crimson red #DC2626 on input field surfaces ($5.2:1$).

2.1 Light and Dark Theme Contrast Verification

Theme toggles dynamically switch CSS variables without altering semantic text contrast:

• Light Theme: Deep slate text on soft gray background.
• Dark Theme: Crisp off-white text (#F8FAFC) on rich obsidian background (#0F172A), maintaining a minimum ratio of $14.2:1$.

---

3. Keyboard Navigation & Focus Management

Every interactive user journey—from product discovery to checkout and Delivery PIN verification—must be completely operable without a mouse or touch screen.

sequenceDiagram
    autonumber
    participant User as Keyboard User (Tab / Shift+Tab)
    participant DOM as Browser DOM
    participant Modal as Radix Dialog / Drawer

    User->>DOM: Presses Tab (Traverses Focusable Elements)
    DOM->>DOM: Applies :focus-visible { outline: 2px solid var(--ring); outline-offset: 2px; }
    User->>DOM: Enters Product Card -> Presses Enter
    DOM->>Modal: Opens Product Detail Sheet
    Note over Modal: Focus trapped inside modal; initial focus set to close button
    User->>Modal: Presses Escape Key
    Modal->>DOM: Modal closes; focus restored to triggering Product Card

3.1 Focus Indicator Specifications

1. Focus Ring Invariant: Focus rings must never be disabled with outline: none without providing an accessible alternative.
2. CSS Standard:

   :focus-visible {
     outline: 2px solid var(--ring);
     outline-offset: 2px;
     border-radius: var(--radius-sm);
   }

3. Skip to Main Content: All page layouts provide a hidden skip link as the very first focusable element:

   <a href="#main-content" class="sr-only focus:not-sr-only focus:fixed focus:top-4 focus:left-4 focus:z-50 focus:p-4 focus:bg-white focus:shadow-lg">
     Skip to main content
   </a>

---

4. Mobile Touch Targets & Hit Areas

Conforming to mobile accessibility standards and ergonomic use on handheld campus devices:

• Primary Interactive Targets: Minimum bounding box of $48 \times 48$ CSS pixels (class="touch-target"). Includes checkout buttons, category pills, navigation tabs, and floating Nduzi chat triggers.
• Secondary / Dense Targets: Minimum bounding box of $44 \times 44$ CSS pixels (class="touch-target-sm"). Applied to inline pagination buttons, item quantity counters, and modal dismiss buttons.
• Touch Spacing: Interactive elements maintain a minimum separation of 8 CSS pixels to prevent unintended adjacent taps.

---

5. Motion Reduction & Cognitive Accessibility

Debelu enforces respectful motion handling conforming to user operating system preferences:

5.1 Respecting prefers-reduced-motion

When a student has enabled reduced motion in their OS or browser settings:

1. Framer Motion layout animations and spring physics transition to instantaneous cross-fades or static state changes.
2. Looping carousel banners and pulse badges freeze.
3. The custom React hook useReducedMotion() returns true:

   import { useReducedMotion } from '@debelu/ui';
   
   export function FlashSaleCountdown() {
     const shouldReduceMotion = useReducedMotion();
     return (
       <motion.div animate={shouldReduceMotion ? {} : { scale: [1, 1.05, 1] }}>
         Flash Sale Live
       </motion.div>
     );
   }

---

6. Semantic HTML & Screen Reader Semantics

Debelu utilizes Radix UI primitives as the structural foundation for all dynamic components, ensuring built-in WAI-ARIA compliance:

• Modals & Drawers (@radix-ui/react-dialog): Manages aria-modal="true", dynamic aria-labelledby, and automated focus traps.
• Screen Reader Only Text (.sr-only): Inlines accessible contextual text for icon-only buttons (e.g., <button><HeartIcon /><span class="sr-only">Add to favorites</span></button>).
• Live Regions (aria-live="polite"): Real-time Nduzi chat responses and in-app order status updates emit alerts through polite ARIA live regions so screen readers announce changes without interrupting user speech.

---

7. Automated Accessibility Auditing in CI/CD

Accessibility verification is fully automated within our continuous integration pipeline:

flowchart TD
    PR[Pull Request Submitted] --> AxeE2E[Playwright + @axe-core/playwright Smoke Audit]
    AxeE2E --> Lighthouse[Lighthouse CI Accessibility Budget]
    
    AxeE2E -->|Violations Found| Fail[PR Blocked: Detailed a11y Report Generated]
    Lighthouse -->|Score < 95| Fail
    
    AxeE2E -->|0 Violations| Pass[Accessibility Gate Cleared]
    Lighthouse -->|Score >= 95| Pass

7.1 Running Playwright Accessibility Audits

# Execute the full automated accessibility audit suite
npm run a11y --workspace=@debelu/storefront

The test harness analyzes rendered DOM structures against wcag2a, wcag2aa, wcag21a, and wcag21aa rulesets, halting on any detectable violation.

7.2 Lighthouse CI Thresholds (lighthouserc.json)

Lighthouse audits enforce a minimum accessibility score threshold of 95/100 across all public pages.

---

8. Document Revision History

Revision	Date	Lead Author	Scope of Changes	Status
1.0.0	2026-10-05	Principal Accessibility Engineer	Complete enterprise accessibility specification covering WCAG 2.1 AA compliance, contrast algorithms, keyboard focus traps, touch targets, and automated Axe-core CI gates.	Active Living Standard