Accessibility Deep-Dive

Step 1: Maya's review

Maya Torres reviews your site. She's a senior frontend engineer who specializes in accessibility architecture.

Her feedback is direct: "Lighthouse says 95. That means you've handled the easy 30%. The automated tools check whether your HTML has the right attributes. They don't check whether a real person using a keyboard can search your collection, open an artifact, and close the detail view without getting trapped. They don't check whether a screen reader user knows when search results update. Go test it yourself -- keyboard only, no mouse."

She's right. Lighthouse checks structural accessibility. It verifies that images have alt text, that headings follow a hierarchy, that color contrast meets the ratio. But the interaction accessibility -- whether the site actually works for people who navigate differently -- requires manual testing.

Step 2: Audit the collection search

Put your mouse aside. Navigate the collection page using only the keyboard.

Tab to the search bar. Type "compass." Tab to the results. Can you reach an artifact card? Can you press Enter to open the detail view? Can you close it and return to where you were?

Now try the category filters. Can you select "Nautical Instruments" using the keyboard? Do the results update? Does anything announce that the results changed, or does a screen reader user have to guess?

Document every gap. Common problems:

• Filter buttons that work on click but not on Enter or Space
• No aria-live region to announce when search results update
• Focus lost after a filter is applied (focus returns to the top of the page instead of staying in the results area)
• Artifact cards that are clickable divs with no keyboard event handlers

Fix every one. AI generates interactive components with mouse-only interaction patterns. The keyboard equivalents are yours to verify and add.

Step 3: Implement focus management

Three focus management patterns your site needs:

Focus traps for modals. When the artifact detail view opens as a modal, focus must move inside the modal and stay there. Tab and Shift+Tab cycle through the modal's interactive elements. Pressing Escape closes the modal. Without a focus trap, a keyboard user tabs out of the modal and into the page behind it -- they can't close the modal, can't get back to it, and may not know it's still open.

Focus return when modals close. When the artifact detail modal closes, focus must return to the element that opened it -- the artifact card that was clicked or activated. If focus goes to the top of the page instead, the keyboard user loses their place in a grid of 150 artifacts.

Live regions for dynamic content. When search results update (because the user typed a query or applied a filter), add an aria-live="polite" region that announces the change: "24 artifacts found" or "No results for your search." Without this, a screen reader user submits a search and hears nothing -- they don't know whether results loaded, whether the search failed, or whether the page is still loading.

Direct Claude to implement all three patterns. Then test each one with the keyboard.

Step 4: Check color contrast

Color contrast affects every page. WCAG AA requires:

• 4.5:1 ratio for normal text (below 18pt / 24px)
• 3:1 ratio for large text (18pt / 24px and above)
• 3:1 ratio for interactive element boundaries and focus indicators

Check the entire site. Pay attention to:

• Navigation links against the background
• Focus indicators against the background
• Form input borders
• Button text
• Placeholder text in the search bar (placeholders often fail contrast)

Use Chrome DevTools' color picker -- it shows the contrast ratio when you inspect an element's color. Fix any failures.

AI generates Tailwind classes that look reasonable but can fail programmatic accessibility. A light gray on white might look subtle and elegant but produce a 2.3:1 contrast ratio -- well below the 4.5:1 minimum.

Step 5: Integrate axe-core

Automated accessibility testing should run as part of your test suite, not as a manual step you remember to do. The build should fail if an accessibility violation is introduced.

axe-core is an accessibility testing engine. @axe-core/playwright integrates it into your Playwright test suite. Every page gets an automated accessibility check.

Install @axe-core/playwright:

npm install -D @axe-core/playwright

Direct Claude to write Playwright tests that run axe-core on every page: the home page, the collection browsing page, an artifact detail page, the login page, and the members dashboard (when authenticated).

Run the tests. axe-core catches programmatically detectable violations -- missing alt text, broken ARIA, invalid roles. It does not catch the interaction problems you fixed in Steps 2-3. That's why manual testing comes first and automated testing acts as a regression guard.

Step 6: Manual keyboard walkthrough

Do a complete keyboard-only walkthrough of the entire site. Start from the first page. Tab through everything. Use every feature: search, filter, open detail views, close them, navigate to the members login.

Document any remaining issues. Fix them.