A Client Asked Me to Make Their Site Accessible. Here's What I Learned.

A few months ago, a client asked me to audit their website for accessibility. I'd heard of WCAG, I knew alt text was a thing, but I'd never done a proper audit. How hard could it be?

Turns out — harder than I expected. And the problem is much bigger than I realized.

The Scale of the Problem

When I started researching, the numbers stopped me cold.

WebAIM's Million 2025 report tested the top 1 million websites and found that 94.8% fail basic accessibility standards. An average of 51 errors per page. A user with a disability hits a barrier roughly every 24 elements.

I checked my client's site. It had dozens of issues I'd never noticed — low contrast text, missing alt attributes, no keyboard navigation, heading levels that jumped from h1 to h4. Things that are invisible to a sighted mouse user but make the site unusable for someone with a screen reader.

What Is Accessibility, Really?

For those unfamiliar: web accessibility means making websites usable by everyone, including people with visual, auditory, motor, or cognitive disabilities. The standard is called WCAG (Web Content Accessibility Guidelines), and the legal minimum in most jurisdictions is Level AA.

WCAG is organized around four principles — POUR:

• Perceivable — Can users perceive the content? (alt text, contrast, captions, resizable text)
• Operable — Can users navigate and interact? (keyboard access, skip links, enough time)
• Understandable — Can users understand the interface? (clear language, predictable behavior, error help)
• Robust — Does it work with assistive tech? (valid HTML, ARIA, compatibility)

There are 50+ individual criteria under these four principles. Checking them manually is tedious and error-prone.

Why Most Developers Don't Do It

I think the honest answer is: we don't see the problems. If you can see the screen and use a mouse, an inaccessible site looks fine. You have to actively test with a keyboard, a screen reader, or a contrast checker to find the issues.

Automated tools like Lighthouse or axe catch some violations — but studies show they only detect 30–40% of WCAG issues. The rest require human judgment: Is this alt text actually descriptive? Does this heading hierarchy make sense? Is this error message helpful?

And then there are overlay widgets — tools that promise one-line accessibility fixes. They don't work. 25% of accessibility lawsuits in 2024 explicitly cited overlay widgets as barriers, not solutions. The FTC fined the largest overlay company $1 million for deceptive marketing. Overlays patch the surface without fixing the underlying code, and screen readers often conflict with their modifications.

Where AI Actually Helps

Here's what I found genuinely useful: using AI not as a checker, but as an explainer and fixer.

When I pointed an AI assistant at my client's code, the difference from traditional tools was clear:

• Lighthouse says: "Image element does not have an alt attribute"
• AI says: "This hero image shows a product comparison chart. Add alt='Comparison of Standard and Pro plans showing pricing, features, and storage limits' — describe the data the image conveys, not just 'chart image'"

That's the gap. Automated tools tell you what's wrong. AI tells you why it matters and how to fix it properly — in the context of your actual code.

For the audit, I structured the AI's knowledge as a skill — a reusable set of instructions that covers all 50 WCAG criteria with examples, common mistakes, and fix patterns. Instead of me remembering whether contrast ratio should be 3:1 or 4.5:1 (it depends on text size), the skill knows.

The result: the AI walks through each POUR principle systematically, flags issues by severity (critical / major / minor), and provides specific code changes — not generic advice, but patches for my actual markup and CSS.

See It for Yourself

I built a demo to show the difference accessibility makes: a11y.bshk.app

It's the same article rendered two ways:

• Bad version — 10 deliberate WCAG violations (no landmarks, low contrast, missing alt text, broken focus, heading skips)
• Good version — the same content, fully accessible (semantic HTML, proper contrast, keyboard navigation, skip links)

Try tabbing through both pages with your keyboard. On the bad version, you can't tell where you are. On the good version, every interactive element has a visible focus ring and the skip link lets you jump past navigation.

Each violation and fix is annotated with a numbered badge explaining what's wrong (or right) and which WCAG criterion it relates to.

The Bigger Picture

While researching, I discovered this isn't just a "nice to have" problem. Accessibility is becoming a legal requirement worldwide:

I'm not a lawyer and this isn't legal advice. But the trend is clear — accessibility is moving from voluntary best practice to enforced requirement. AI tools that help developers actually understand and fix issues (rather than just flag them) can make a real difference here.

Try It Yourself

The accessibility skills I built during this project are open source. Here's how to try them in Claude:

Step 1. Download the skill file: ada-compliance/SKILL.md

Step 2. Open claude.ai/customize/skills and add the downloaded file

Step 3. Ask Claude to audit your site — the skill activates automatically:

"Check my site for ADA compliance"

The ada-compliance skill covers US requirements (ADA, WCAG 2.1 AA). There are also skills for other jurisdictions:

The skill files are structured Markdown — they also work as a system prompt in any LLM, or simply as a checklist for manual audits.

Data sources: WebAIM Million 2025, Accessibility.Works, AudioEye, Seyfarth Shaw ADA Title III, Level Access EAA