Skip to main content

The Initial Audit

Beginneraxe-corePlaywrightLighthouseWCAG 2.2React

Audit the ShopSmart homepage and fix critical WCAG 2.2 accessibility violations before the initial compliance review.

Mission Objective

  • Remove all serious and critical axe-core violations from the ShopSmart homepage.
  • Provide meaningful alternative text for every informative image.
  • Ensure the menu and primary call-to-action are semantic, keyboard-focusable controls.
  • Add visible focus indicators for interactive elements.
  • Achieve a Lighthouse accessibility score of at least 95.

Key Learnings

  • How to interpret automated axe-core accessibility reports.
  • How semantic HTML affects keyboard and assistive-technology behavior.
  • How to identify and correct WCAG color-contrast failures.
  • How to provide useful text alternatives for images.
  • How to verify accessibility outcomes with Playwright and Lighthouse.

Best Suited For

Frontend developers who understand basic HTML, CSS, React, and browser developer tools but are new to systematic accessibility testing.

The Story

ShopSmart has received an urgent legal notice about accessibility barriers on its public storefront.

Customers cannot reliably navigate the page by keyboard, important images have no text alternatives, several controls use incorrect semantics, and the visual design does not meet WCAG contrast requirements.

Your task is to audit the homepage, understand the failures, and repair the most serious problems before regulators escalate the case.

Architecture

A React and Vite storefront runs on port 5173 inside the Dev Container.

Playwright launches Chromium and uses axe-core to scan the rendered homepage.

Lighthouse CI measures the accessibility category and requires a score of 95 or higher.

Players edit src/App.jsx and src/styles.css. The tests and verification scripts define the required outcomes and should not be weakened or bypassed.

Ready to start?

Launch in a preconfigured devcontainerdevelopment container: a portable, reproducible coding environment defined by a configuration file

Open in Codespaces

Free GitHub account required

Walkthrough

  1. Get Started

    Open in GitHub Codespaces. The devcontainerdevelopment container: a portable, reproducible coding environment defined by a configuration file is pre-configured and starts automatically. When you push from Codespaces, GitHub forks the repository to your account automatically.

    Prefer working locally? Clone the repo and open it in any editor that supports the Dev Containers specification (VS CodeVisual Studio Code, JetBrains, and others). The devcontainer config will be detected automatically.

  2. Start ShopSmart

    Start the application:

    make app

    Then open port 5173 in your browser.

  3. Explore the UIs

    Open the Ports tab and navigate to each service:

    • Port 5173: ShopSmart. The intentionally inaccessible React storefront.
  4. Explore the Broken Storefront

    Open ShopSmart on port 5173 and navigate the page using only the keyboard.

    Run the automated checks:

    npm run test:a11y
npm run test:lighthouse

    Review the reported axe rule IDs, affected elements, keyboard failures, and Lighthouse score before changing the implementation.

  5. Repair the Accessibility Failures

    Work primarily in:

    src/App.jsx
src/styles.css

    Correct the semantic controls, image alternatives, contrast problems, keyboard behavior, and focus appearance.

    Do not remove tests, lower score thresholds, disable axe rules, or weaken the verification logic.

    When ready, run:

    ./verify.sh

Complete Your Challenge

  • When you push from Codespaces, GitHub forks the repository to your account automatically. If you are working locally, fork the repository on GitHub before pushing.
  • Verify your solution:
    ./verify.sh
    If it passes, it generates a Certificate of Completion you can paste into the discussion.
  • Share your solutions in the challenge thread on community.offon.dev.

Completed the challenge? Share your achievement on LinkedIn

Toolbox

  • axe-core - Automated accessibility engine used to detect WCAG violations.
  • Playwright - Browser automation framework used for accessibility and keyboard tests.
  • Lighthouse - Browser audit tool used to measure the final accessibility score.
  • WCAG 2.2 - Accessibility standard that defines the success criteria for this level.

Helpful Documentation

Know someone who'd enjoy this?