We Wrote an Accessibility Article Then Failed Our Own Audit

Posted by on · Topic: WCAG 2.2 AA

WCAG 2.2 AA web

TL;DR

Built an 84-citation article about Apple’s accessibility history. Then audited the hosting site and found it failed WCAG on every single page. The irony wrote itself.

What the audit found

Five parallel agents audited every layout and page file. The results were brutal:

Systemic failures (every page):

  • No skip link anywhere (except the new palimpsest page)
  • .sr-only class used in 5 places but never defined
  • outline: none on 4 search inputs with no replacement focus ring
  • scroll-behavior: smooth not gated behind prefers-reduced-motion
  • No forced-colors support for Windows High Contrast Mode
  • No aria-pressed on any filter/toggle button

Contrast (the biggest category):

  • Dark-themed pages used rgba(255,255,255,0.2-0.45) for secondary text — ratios of 1.3:1 to 2.7:1 against 4.5:1 requirement
  • Parchment-themed pages used rgba(100,70,35,0.3-0.55) — ratios of 1.6:1 to 1.9:1
  • Whiteboard marker-colored titles all failed on light card backgrounds (red 2.5:1, blue 3.5:1)
  • Even the “passing” colors were borderline — doc date at 3.8:1, citation items at 4.3:1

Keyboard access:

  • Clickable <div> elements in the reading year modal unreachable by keyboard
  • Scope creep modal had no focus trap (only modal missing it)
  • Shelf trigger button at 0.25 opacity — effectively invisible
  • .sticky-doc-link was 11x11px, well under 24px minimum touch target

Semantic HTML:

  • ForgeLayout used <div class="forge-article"> instead of <article>
  • Guide labels were <div> instead of <h3>
  • 404 page had no <h1>

What we fixed

Fixed everything in Layout.astro first (skip link, .sr-only, global focus indicators, reduced-motion, forced-colors) so every page inherited the fix. Then four parallel agents fixed contrast across all layouts and pages simultaneously.

The key insight: fixing accessibility at the layout level is a force multiplier. One file change fixed 15+ pages.

Contrast fix pattern

The fix was mechanical but tedious. On dark backgrounds (#0f1117, #2a3a2a), white text needs at least 0.65 alpha to hit 4.5:1. On parchment (#f0e6d0), brown text needs solid colors around #6b4d25. We switched from rgba to solid hex where possible — rgba is harder to reason about for contrast.

Developer takeaway

If you’re building a site about accessibility, audit it before you publish. We had the humility to run the audit and the irony was instructive: the design choices that make a site feel “atmospheric” (low-opacity text, subtle UI, hidden triggers) are exactly the choices that fail WCAG. Atmosphere and accessibility are in tension, but they’re not incompatible — you just need to find the floor and stay above it.