Where accessibility gets complicated — Alexandra Ignatova

Quick Tip: Recap Changes with Claude Custom Commands

Mon, 30 Mar 2026 00:00:00 GMT

Have you ever come back to a branch after a meeting, a different project, or a few days off — having no idea what you changed? I know you did.

You can create a reusable command to simplify your life (a bit) — here is how I did it with Claude Code /summary and /pr-desc command.

I find it much more useful to get a quick summary of the changes and the reasoning behind them by asking an AI assistant rather than trying to piece it together myself from commit messages and diffs.

Custom `/summary` command

Claude Code supports custom slash commands — markdown files in .claude/commands/ that can act as reusable prompts. I created one for change summaries:

.claude/commands/summary.md

Summarize all changes on the current branch compared to main. Include:

1. A short one-line summary of the overall change
2. A bullet list of each changed file with what was changed and why
3. Any potential concerns or things to watch out for

Use `git diff main --stat` and `git diff main` to get the changes.
Keep it concise and useful.

Now, anytime I forget what I've done in a branch, I type /summary in Claude Code and get a clear breakdown in a human-readable format — no extra setup, no waiting, and no need to waste time typing the same questions to my AI assistant.

After creating a new command, you'll need to restart your Claude Code session for it to show up.

Bonus: `/pr-desc` command

Once I had /summary, I wanted a second command that formats the output as a ready-to-paste PR description. Same idea, a slightly different structure:

.claude/commands/pr-desc.md

Generate a PR description for the current branch compared to main.
Format the output as GitHub-flavored Markdown using this structure:

## Summary
A short 1-3 sentence overview of the change.

## Changes
- **`file-path`** -- what was changed and why

## Concerns
Any potential risks, or "None" if the changes are clean.

Use `git diff main --stat` and `git diff main` to get the changes.
Use `git log main..HEAD --oneline` to see all commits on this branch.

Now I run /pr-desc and get a formatted PR description I can paste straight into GitHub.

Tip: You can also instruct the command to copy the output to your clipboard automatically by adding cat /tmp/pr-desc.md | pbcopy (macOS) to the prompt — then it's just Cmd+V.

You can also skip the clipboard entirely and ask Claude Code to create the PR for you — it runs gh pr create under your GitHub account. But for some reason I prefer to keep this part of the job to myself still :D

I really like custom commands and use them for many more things beyond branch summaries — for example, I have one for post review where I ask AI to check typos and post structure without changing my personal writing style.

Since .claude/commands/ lives in the repo and is committed to git, anyone who clones the project gets the command too — no extra setup needed. Very handy for consistency.

You can also automate PR summaries with a Claude Code GitHub Action that posts a summary comment on every PR automatically (+ additional features). It looks amazing, but as far as I know, this requires an Anthropic API key, and API usage is billed separately from a Claude Pro subscription. I think for solo projects, the custom commands above are simpler.

Can AI Handle Accessibility for Me?

Sun, 22 Mar 2026 00:00:00 GMT

Can AI tools create accessible components for me already? YES or NO?
Here are my 2 cents on the issue :)

AI and accessible code

Is it true that AI models are biased toward inaccessible code?

There might be a fundamental problem with how AI models learn to write code: these models are trained on a huge pool of public code and web content — and most of that code is not very accessible:

The 2025 WebAIM Million report analyzes the home pages of the top 1,000,000 websites for automatically detectable Web Content Accessibility Guidelines (WCAG) failures. In 2025, 94.8% of home pages had detected WCAG failures.

The actual number of issues across the web is likely to be higher because automated scans only catch a subset of WCAG criteria. If the majority of the web is not accessible — AI by default can reproduce exactly the same a11y issues. The old principle still holds: garbage in, garbage out — just at a much larger scale.

Until the quality of code across the web improves — or developers patiently teach their AI tools using verified accessible components and resources — this problem is likely to stay with us.

AI coding assistants

Own experience

By default, AI coding assistants (GitHub Copilot, OpenAI Codex, Claude Code, Cursor etc.) can help generate code that follows basic accessibility principles for simple or typical UI blocks. But based on my experience, they can also introduce a11y issues.

Some examples I noticed just recently:

Adding aria-label to elements that don't support it
Overusing ARIA roles
Creating links and buttons with meaningless labels
Illegally wrapping product/post cards in <a> tags
Choosing colors that don't meet contrast requirements
Poor keyboard navigation and focus management for more complex components (like dropdowns, carousels, menus etc.)
Assistive technology announcements are often missing or incorrect (e.g., no live region updates, or wrong ARIA attributes for dynamic content)

Saying just "make this component accessible" during development helps a bit (especially when you ask to ultrathink :)), but is not enough — unfortunately you need to specify in eeevery detail what you want.

The 2025 WebAIM Million report also highlights increased ARIA usage on pages with higher detected errors. This can suggest that some developers (and likely AI models) are using ARIA as a band-aid for underlying accessibility issues, which can lead to more repetitive problems.

Fixing Accessibility

AI tools and models are progressing very fast — about a year ago I saw AI-generated code that regularly contained inaccessible patterns and ARIA attributes that were not just incorrect but did not even exist (!) in the spec. Today, with the latest models, the situation is noticeably better — the baseline quality of generated HTML has improved.

But even "noticeably better" is not "accessible." I still have to review every component carefully and provide specific instructions to fix issues with semantic HTML, ARIA, keyboard interaction, focus management, and more. If I did not already know what to look for, those issues would have shipped unnoticed.

My overall feeling is that most of the time the code looks right, but the experience is sometimes wrong. When AI generates code that looks complete and correct, it is easy to skip the review — especially if you don't know what to check for.

As more teams adopt AI coding assistants, a new bottleneck is becoming visible: code creation is no longer the most time-consuming part, but code review is. When code is produced faster than it can be thoroughly reviewed, accessibility is one of the first things that might get missed.

MRs Stack

Even Anthropic's engineering blog has some obvious accessibility issues with keyboard navigation, contrast, and valid HTML. I'm sure some of the best engineers work there, which only proves the point: accessibility is very easy to overlook.

Example: Skip link contrast issue (March 2026)

AI-powered accessibility overlays

Own experience + research

AI-powered accessibility overlays — widgets that claim they can "fix" a website automatically — may also give you a dangerous overconfidence in the state of your solution.

A lot has been written about this. Here are some of the examples I found most convincing:

A peer-reviewed study (ACM ASSETS 2024) surveyed 47 blind and low-vision users. Most reported that overlays made accessibility problems worse — overlay screen readers conflicted with their own assistive technology, and users opted to avoid websites with overlays entirely
Overlays joint statement by the European Disability Forum and International Association of Accessibility Professionals (IAAP) stating that overlays “do not make the website accessible or compliant with European accessibility legislation”
Regulators have acted too — in 2025 the FTC required accessiBe to pay $1 million over deceptive claims that its AI-powered product could make websites WCAG-compliant

No overlay can reliably transform non-semantic source code into the semantic structure and interaction model assistive technologies depend on.

In my experience, for web pages with minor visual issues (like text sizing, color, contrast etc.) an overlay might adjust things well enough — but users can already make the same adjustments through their browser or OS settings. For more complex pages, overlays can interfere with JavaScript behavior, break interactions, and make the experience worse than without them (not to mention the performance issues they can cause).

Solving accessibility problems with a simple installation

As a developer, I'd prefer to fix the underlying code. As a user, I'd prefer a website that is accessible from the start — not one that relies on a band-aid I have to work around.

Where does AI help the most?

Own experience, scoped to accessibility

I hope I didn’t come across as too negative about AI tools. Quite the opposite — I’m genuinely optimistic about where they’re headed, and I have to admit I enjoy a good vibe-coding session way more than I probably should :D

As for me, the biggest benefit right now is that it can significantly speed up the implementation of logic and well-established UI and UX patterns, leaving time to focus on more complex user experience problems.

In the scope of a11y, AI is also helpful for:

Drafting alt text — AI can describe what is in an image, but you still need to decide what the purpose of the image is in context (is it decorative? informative? functional?)
Explaining WCAG criteria — AI is good at translating spec language into practical guidance
Generating test configurations — CI setups, linter configs, and testing scripts (like the ones in Automate Accessibility Checks in CI)
Generating test cases — unit and integration tests for accessibility scenarios like keyboard navigation, focus trapping, and ARIA state changes
Finding relevant resources — documentation, examples, and tools for specific accessibility issues
Brainstorming solutions — it can suggest approaches, but you still need to evaluate and test them
Checking against provided checklists — you can ask it to review code against a specific WCAG criterion, but you still need to verify the results

It's important to treat AI output as a starting point, not a final answer.

So, can AI handle accessibility for me?

My answer is...

Sometimes. But not without human verification (yet).

At this moment, no tool (that I know about) can answer the question that actually matters: does this work for a real person using a screen reader, a keyboard, or a switch device? That still requires keyboard testing, testing with assistive technologies, and ideally, feedback from people with disabilities.

What we can do with it now:

Learn the fundamentals. Understand accessibility principles and best practices so you can review AI-generated code and make informed decisions about what to request, accept, modify, or reject.
Tune your AI instructions. It’s worth investing time in tuning the project-level AI instructions and rules (e.g., AGENTS.md, SKILL.md) — the more specific and detailed your instructions, the better the output will be. It’s quite a task — perfect for the pickiest or should I say, detail-obsessed and experienced person on the team. You can also try out skills created by other contributors and adapt them to your project.
Invest in automation. A few years ago, a mid-sized team could get by without a strong automation pipeline. Now that AI can produce code faster than anyone can review it, automated checks — linters, CI, accessibility testing — are a safety net you can’t skip.

All of these take effort and slow you down at first.

That's why the question: are we moving faster than our ability to keep up with accessibility or should I say, quality? (rhetorical question)

When experience makes a difference

See also:

Run Automated Accessibility Tools — browser extensions and manual tools
Automate Accessibility Checks in CI — set up automated validation in your pipeline
Practical accessibility testing — the full testing process
When code stops being the bottleneck by Kelly Vaughn — on the shift from code creation to code review as the new bottleneck

Automate Accessibility Checks in CI

Tue, 17 Mar 2026 00:00:00 GMT

You know that automated tools exist. Now let's wire some of them into our development workflow so every push and every pull request gets checked automatically — no manual clicks, no forgotten scans.

We will look into 2 levels of automated checks:

HTML validation on every push (pre-push hook)
WCAG 2.2 AA accessibility checks on every pull request (GitHub Actions)

Both running against our actual built pages.

This guide uses an Astro project with pnpm as an example, but html-validate and pa11y-ci work with any static site or framework. Adapt the build and serve commands to your stack.

Install the tools

You need 3 packages:

html-validate — lints built HTML files for structural issues, invalid ARIA, and spec violations
pa11y-ci — runs WCAG (Web Content Accessibility Guidelines) accessibility checks against rendered pages using a headless browser
husky — manages git hooks (pre-push, pre-commit)

pnpm add -D html-validate pa11y-ci husky

pa11y-ci needs a running server to check pages. Since Astro has a built-in preview server (astro preview), we use that. Adapt the serve command to your framework's preview server.

Initialize husky:

npx husky init

This creates a .husky/ directory and adds a prepare script to your package.json.

Configure html-validate

Create .htmlvalidate.json in your project root:

{
  "extends": ["html-validate:recommended"],
  "rules": {
    "no-inline-style": "off",
    "no-trailing-whitespace": "off",
    "long-title": "warn",
    "void-style": "off",
    "no-raw-characters": "off",
    "attr-case": ["error", { "ignoreForeign": true }]
    }
}

Why these overrides?

Disabled html-validate rules and reasons
Rule	Why off/warn
`no-inline-style`	Syntax highlighting (Shiki, Prism) generates inline styles in code blocks
`no-trailing-whitespace`	Build tools and formatters may leave trailing spaces — not worth blocking on
`long-title`	Some page titles exceed the recommended length — warn instead of error
`void-style`	MDX renderers may output `{' '}` instead of `{' '}` — both are valid
`no-raw-characters`	Markdown-rendered content may contain `{'>'}` in text — valid in HTML
`attr-case`	SVG attributes like `viewBox` use camelCase — `ignoreForeign` allows this

Run it against your build output:

pnpm build
npx html-validate 'dist/**/*.html'

When you first run html-validate, expect it to find real issues — like aria-label on elements that don't support it, missing type on buttons, or invalid nesting. Fix these before configuring rules to suppress them.

Configure pa11y-ci

Create .pa11yci.json in your project root:

{
  "defaults": {
    "standard": "WCAG2AA",
    "timeout": 10000
  },
  "sitemap": "http://localhost:4321/sitemap-0.xml",
  "sitemapFind": "https://your-domain.com",
  "sitemapReplace": "http://localhost:4321"
}

Instead of listing URLs manually, pa11y-ci reads your sitemap and discovers all pages automatically. sitemapFind and sitemapReplace rewrite the production URLs to point at your local server.

WCAG2AA is the standard most accessibility laws require (EU's EN 301 549, US Section 508). Change to WCAG2AAA if you want stricter checks.

To test locally:

pnpm build
pnpm preview & npx pa11y-ci

To check a single page during development, you can run pa11y directly without the CI config:

npx pa11y http://localhost:4321/blog/your-page/

Set up the hook to validate HTML on every push

Create .husky/pre-push:

pnpm build && npx html-validate 'dist/**/*.html'

Every git push now builds your site and validates the HTML. If validation fails, the push is blocked.

Why only html-validate in the hook?

pa11y-ci needs to start a server, launch a headless browser, and crawl every page — noticeably slower than html-validate, which just reads files from disk. Running the full a11y check in CI is my personal preference — you can also add it to the pre-push hook. Either way, keep it in CI — hooks can be skipped, CI is the last line of defense before code gets merged.

Create the GitHub Actions workflow

Create .github/workflows/validate.yml:

name: HTML & Accessibility Validation

on:
  pull_request:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: pnpm/action-setup@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm

      - run: pnpm install

      - name: Build website
        run: pnpm build

      - name: HTML validation
        run: pnpm validate:html

      - name: Start server & run a11y checks
        run: |
          # Override pa11y-ci config to use system Chrome
          cat > .pa11yci.json <<EOF
          {
            "defaults": {
              "standard": "WCAG2AA",
              "timeout": 10000,
              "chromeLaunchConfig": {
                "executablePath": "/usr/bin/google-chrome-stable",
                "args": ["--no-sandbox"]
              }
            },
            "sitemap": "http://localhost:4321/sitemap-0.xml",
            "sitemapFind": "https://your-domain.com",
            "sitemapReplace": "http://localhost:4321"
          }
          EOF

          pnpm preview &
          SERVER_PID=\$!

          # Wait for server to be ready
          for i in $(seq 1 10); do
            curl -s http://localhost:4321/ > /dev/null && break
            sleep 1
          done

          pnpm validate:a11y
          EXIT_CODE=\$?

          kill \$SERVER_PID
          exit \$EXIT_CODE

What this does:

Builds the website
Runs html-validate against all HTML files
Overrides the pa11y-ci config to use system Chrome (needed in CI)
Starts the preview server, waits for it, runs pa11y-ci against all pages from the sitemap, then cleans up

Add the npm scripts to your package.json:

{
  "scripts": {
    "validate:html": "html-validate 'dist/**/*.html'",
    "validate:a11y": "pa11y-ci"
  }
}

What you now have

html-validate catches structural HTML issues on every git push (pre-push hook)
pa11y-ci runs WCAG 2.2 AA checks against every page on every pull request (GitHub Actions)
Both run against your actual built pages, not source code — so they catch what users will see

Remember: This won't replace manual testing with keyboard and assistive technologies. But they catch them consistently, on every change, without anyone needing to remember.

FAQ

Can I use axe-core instead of pa11y-ci?

Yes. @axe-core/cli is a good alternative. pa11y-ci has stronger multi-page CI support out of the box, including URL-list and sitemap-based runs with CI-friendly failure behavior, while axe-core is the widely adopted accessibility engine behind Deque’s axe tooling and influences Lighthouse accessibility scoring.

What about Lighthouse CI?

Lighthouse CI is strong when you want Lighthouse’s broader audit coverage — performance, SEO, best practices, and accessibility — in one CI workflow. It can be more involved than an accessibility-only runner, especially if you want uploaded reports, historical tracking, or GitHub status checks, but those are optional. For accessibility-only checks, pa11y-ci is typically simpler.

See also:

Run Automated Accessibility Tools — overview of browser extensions and manual tools
Validate Your HTML — why valid markup matters
Practical accessibility testing — the full testing process

Make Your Videos Accessible

Fri, 20 Feb 2026 00:00:00 GMT

Here's everything you need to make your video accessible — from captions to transcripts.

If you need a reminder what accessibility levels A, AA, and AAA mean, check the FAQ section first: What do A, AA, AAA mean?

Provide captions (A)

Ask the question: Does the video have speech or other audio that is needed to understand the content? If yes, you need captions. (WCAG 1.2.2)

You'll need a properly formatted WebVTT (Web Video Text Tracks) file (.vtt).

How to add captions

Add a <track> element with kind="captions" and a language tag:

<video controls>
  <source src="video.mp4" type="video/mp4">
  <track src="captions_en.vtt" kind="captions" srclang="en" label="English" default>
</video>

A basic captions_en.vtt file looks like this:

WEBVTT

00:00:01.000 --> 00:00:04.000
[Narrator]: Welcome to the tutorial.

00:00:05.500 --> 00:00:09.000
Today we'll learn how to make
video content accessible.

00:00:10.000 --> 00:00:13.500
[background music]

The file starts with WEBVTT, followed by caption cues — each with a timecode range and the text to display. Use square brackets for non-speech sounds like [background music] or speaker identification like [Narrator].

Provide alternatives (A)

Alternatives for audio-only and video-only content

Ask the question: Is your media audio-only (e.g., a podcast) or video-only (e.g., a silent tutorial with background music)? (WCAG 1.2.1)

Audio-only (e.g., a podcast, voice recording) — provide a text transcript of everything that is spoken and any meaningful sounds
Video-only (e.g., a tutorial with no narration) — provide a text alternative that describes the visual content, OR an audio description track that narrates what's shown

In both cases, the alternative must be equivalent — a user who can't hear the audio or see the video should get the same information.

Video-only example

Imagine a video showing how to set up an aquarium — no narration, just background music and visual steps. The text alternative must describe each step in enough detail: what equipment to place, where to position it, how much water to add. A vague summary like "This video shows how to set up an aquarium" is not enough.

Place the text near the video and use aria-describedby to link them — screen readers will announce that a description is available. A clear heading on the text block also helps users find it via heading navigation:

<video controls aria-describedby="aquarium-setup-steps">
  <source src="aquarium-setup.mp4" type="video/mp4">
  <track src="captions_en.vtt" kind="captions" srclang="en" label="English">
</video>

<div id="aquarium-setup-steps">
  <h3>Step-by-step aquarium setup</h3>
  <ol>
    <li>Rinse the gravel under running water and spread it evenly across the tank bottom.</li>
    <li>Place the filter and heater against the back wall, leaving space between them.</li>
    <li>Fill the tank slowly with dechlorinated water to avoid disturbing the gravel.</li>
  </ol>
</div>

For longer descriptions, aria-details is a more semantically precise alternative to aria-describedby — it signals a detailed description rather than a brief summary. Browser support is growing but not yet universal.

Even if the audio isn't meaningful, it's still good practice to provide a captions track with [background music] — so users don't think you forgot captions. See What if my video has only background music?

Add audio descriptions (A, AA)

Ask the question: Does the video have visual information that is needed to understand the content? (WCAG 1.2.3, WCAG 1.2.5)

If your video shows key visuals (e.g., actions, diagrams, on-screen text) that aren't described in the narration or dialogue, you must provide audio description. It describes the visual information needed to understand the content, including text displayed in the video.

At Level A (WCAG 1.2.3), you can choose between audio description or a full text alternative that describes everything in the video. At Level AA (WCAG 1.2.5), audio description is specifically required — a text alternative alone is not enough. If your video has static visuals (e.g., a talking head against an unchanging background), a text alternative may be sufficient even at AA — see Technique G203 (W3C).

What does audio description sound like? During a pause in dialogue, a separate narrator's voice describes the visuals — for example: "The presenter points to a bar chart. The tallest bar is labeled 'Dark mode' at 60%."

The best way to handle description is often not to need it at all — integrate all visual information into the main audio. This is called "integrated description".

For example, instead of a narrator saying "As you can see here..." while showing a chart, the narrator would say "This bar chart shows that 60% of users prefer dark mode." — the visual information is already in the spoken words, so no separate audio description is needed.

How to provide descriptions

Integrate description into the main audio content (recommended)
OR provide a second audio track (kind="descriptions") or a separate video version with narration included
Add a way for users to select or toggle the audio description

<track src="descriptions_en.vtt" kind="descriptions" srclang="en" label="Audio Description">

Note that browsers don't expose this track via controls, so you'll need to build a custom toggle UI or provide a narrated version of the video.

Provide custom controls (A)

Ask the question: Are you building a custom video player on top of the native <video> element? (WCAG 2.1.1)

If you are using a ready-to-use video player library (e.g., Video.js, Plyr, or a platform like YouTube/Vimeo embeds), it likely already handles most of these concerns.

The HTML5 <video> element supports basic accessibility, including keyboard access to controls and support for captions/subtitles.

However, it has limitations:

Inconsistent appearance across different browsers and operating systems
No custom focus styles
No transcript support or toggling of audio descriptions via the interface

Building accessible controls

If you need more control, replace the default controls with your own <button> elements and JavaScript:

Provide keyboard support (Understanding Keyboard Accessible) — see also Test Keyboard Navigation
Make the keyboard focus indicator visible (Understanding Focus Visible)
Provide clear labels (Understanding Labels or Instructions)
Have sufficient contrast between colors for text, controls, and backgrounds (Understanding Contrast)

For recommendations on building custom video players: Media Players (W3C WAI)

Allow stop of auto-playing (A)

Ask the question: Does your video play automatically? (WCAG 2.2.2)

Avoid autoplay whenever possible
If autoplay is required, provide controls to stop or pause the video
If using muted autoplay (e.g., a hero background video), users must still be able to pause it. Also consider prefers-reduced-motion — some users find any motion distracting or disorienting

Provide a transcript (AAA)

Ask the question: Do you want to provide the best possible access to your video content? (WCAG 1.2.8)

Transcripts for audio-only content (e.g., podcasts) are required at Level A under WCAG 1.2.1. This section is about transcripts for synchronized media (video with audio) — that's Level AAA.

Even if you already have captions, a separate transcript adds value:

Captions enable people who are Deaf or hard of hearing to watch the video and read along at the same time
Transcripts provide access to people who are Deaf-blind and use braille, and are also used by people without disabilities

How to add a transcript

Include a full text transcript of the video content. Link to it near the video, display it in a toggleable section, or just include it in the page content below the video.

The simplest approach is the native <details> element — it handles expand/collapse and accessibility without any JavaScript:


**Read transcript**

  <p>[Narrator]: Welcome to the tutorial...</p>
  <p>Today we'll learn how to make video content accessible.</p>

Here's how it works — try clicking:

Read transcript

[Narrator]: Welcome to the tutorial. Today we'll learn how to make video content accessible.

[Narrator]: First, let's add captions to our video using a WebVTT file.

[background music]

FAQ

What if my video has only background music?

Background music alone doesn't require full captions — but you should still let users know, so they don't think you forgot to add them.

You can:

Provide a captions file with only the appropriate indication, such as [background music]
Provide the information in text with the video, such as: "Captions not needed: The only sound in this video is background music"

If the video still conveys information visually (e.g., a tutorial or demonstration), you need a text alternative instead — see Provide alternatives.

Captions vs. Subtitles

These terms are often used interchangeably, but they serve different purposes:

Captions are intended for viewers who cannot hear the audio. They include not just dialogue but also sound effects, music cues, and speaker identification — e.g., [door slams], [upbeat music], [Narrator]:.
Subtitles are intended for viewers who can hear but don't understand the spoken language. They typically only include dialogue.

For accessibility, you need captions, not just subtitles.

Closed captions vs. Open captions

There are two ways captions can be delivered:

Closed captions are a separate text track that users can turn on or off. This is the most common approach on the web — using <track kind="captions"> or a player's built-in caption toggle (the CC button). Closed captions give users control over whether they see the text.
Open captions are burned directly into the video frames. They are always visible and cannot be turned off. This can be useful when you cannot rely on the player supporting text tracks (e.g., social media videos, video you share in .PDF etc.), but it removes user choice and makes the captions impossible to resize or restyle.

For web accessibility, closed captions are preferred because they let users control the display, work with assistive technologies, and can be provided in multiple languages.

What do A, AA, AAA mean?

Each requirement in this article is marked with a WCAG conformance level. Levels are cumulative — to meet Level AA, you must satisfy all A and AA requirements:

Level A — the bare minimum. Without these, some users simply cannot access the content at all.
Level AA — the standard most organizations target. Includes all Level A requirements, plus additional ones. This is what most accessibility laws and policies require (e.g., EU's EN 301 549, US Section 508).
Level AAA — the highest level. Includes all A and AA requirements, plus additional ones. Not always feasible for all content, but provides the best experience.

See also:

Test with Screen Readers & System Settings

Wed, 18 Feb 2026 00:00:00 GMT

This is part 4 of the Accessibility Testing series. It covers how to test your pages with screen readers, zoom, high contrast mode, and reduced motion preferences.

VoiceOver (macOS)

VoiceOver is the native screen reader on macOS — no installation needed.

Starting: Cmd + F5 or use System Settings → Accessibility → VoiceOver toggle
Settings: VoiceOver Utility

Essential VoiceOver keyboard commands
Task	Command
Start (or stop) VoiceOver	`Cmd + F5`
VoiceOver activation keys (VO keys)	`Control + Option`
Start reading	`VO + A`
Pause or resume reading	`Control`
Open Rotor	`VO + U`
Activate link	`Enter` or `VO + Space Bar`
Activate button	`Enter` or `Space Bar` or `VO + Space Bar`
Read next/previous item	`VO + Right` or `Left Arrow`
Repeat last spoken phrase	`VO + Z`
Go to next heading	`VO + Cmd + H`
Go to next table	`VO + Cmd + T`
Go to previous (heading, table, etc.)	`VO + Shift + Cmd + H`, `T`, etc.
Navigate table cells	`VO + Arrow Keys`
Interact with (enter/exit) groups and objects	`VO + Shift + Down/Up Arrow`

VoiceOver uses an "interaction" model — some elements (like toolbars, tables, or groups) require you to "enter" them with VO + Shift + Down Arrow before you can navigate their contents. Use VO + Shift + Up Arrow to exit back out.

For the full reference: VoiceOver Keyboard Shortcuts on a Mac

NVDA (Windows)

NVDA is a free, open-source screen reader for Windows.

Download: nvaccess.org
Starting: Ctrl + Alt + N
Speech viewer: NVDA icon → Tools → Speech viewer (useful for seeing what NVDA announces)

The NVDA modifier key is Insert by default (can be changed to Caps Lock in settings).

Essential NVDA keyboard commands
Task	Command
Start NVDA	`Ctrl + Alt + N`
Stop NVDA	`Insert + Q`
Start reading	`Insert + Down Arrow`
Pause or resume reading	`Control`
Read next/previous item	`Down Arrow` / `Up Arrow`
Activate link or button	`Enter`
Next heading	`H`
Next landmark	`D`
Next table	`T`
Navigate table cells	`Ctrl + Alt + Arrow Keys`
Elements list (like VoiceOver's Rotor)	`Insert + F7`
Toggle browse/focus mode	`Insert + Space`

NVDA has two modes: browse mode (for reading content, single-letter navigation like H for headings) and focus mode (for interacting with form controls). NVDA switches automatically in most cases, but you can toggle manually with Insert + Space.

For the full reference: NVDA Keyboard Shortcuts

What to check

Enable a screen reader and navigate through the page using only the keyboard.
As you move through the page, verify:
- Reading order — Is the content announced in a logical sequence?
- Images — Are meaningful images described? Are decorative images hidden from the screen reader?
- Headings — Do headings reflect the page structure? Are any levels skipped?
- Form fields — Does each input have a label that is announced?
- Interactive states — Are states like "expanded," "pressed," "checked," or "selected" announced when they change?
- Dynamic content — Are updates (toasts, error messages, loading states) announced via live regions?
- Links — Do link texts make sense out of context? (No "click here" or "read more" without context)

Quick structure audit with the Rotor

The VoiceOver Rotor (VO + U) and NVDA Elements List (Insert + F7) give you a quick overview of the page structure:

Check Headings — verify the hierarchy is correct and nothing is skipped
Check Landmarks — verify main regions (banner, navigation, main, contentinfo)
Check Links — confirm all meaningful links have descriptive names

This is a fast way to spot missing headings, broken landmark regions, or links with generic names.

TalkBack (Android) testing will be covered in a separate mobile testing guide (coming soon).

Zoom and screen magnification

Users with low vision often zoom in to 200% or more. WCAG requires that content remains usable at these levels.

WCAG 1.4.4 Resize Text — content must be readable at 200% zoom
WCAG 1.4.10 Reflow — content must reflow into a single column at 400% zoom (no horizontal scrolling)

How to test

Browser zoom to 200% — Cmd + + (macOS) or Ctrl + + (Windows). Check that no text is cut off, no elements overlap, and all functionality is still available.
Reflow at 400% — open DevTools responsive mode and set the viewport to 320px wide (this simulates 400% zoom on a 1280px screen). Verify there is no horizontal scrollbar and all content is reachable by scrolling vertically.

What to look for

Text is not truncated or hidden behind other elements
Interactive elements are still reachable and usable
No horizontal scrolling appears (except for data tables, maps, or diagrams)
Layout adapts without loss of content or functionality

High contrast and forced colors

Some users rely on high contrast modes that override your CSS colors. Content and UI must remain visible and functional.

How to test

Windows — Settings → Accessibility → Contrast themes and select a high contrast theme. Or press Left Alt + Left Shift + Print Screen to toggle quickly.
macOS — System Settings → Accessibility → Display → Increase contrast
DevTools — In Chrome, open DevTools → Rendering panel → "Emulate CSS media feature prefers-contrast" → set to more
Forced colors — In Chrome DevTools → Rendering → "Emulate CSS media feature forced-colors" → set to active

What to look for

Focus indicators are still visible (borders, outlines)
Icons and SVGs are not invisible (they may lose their fill/stroke colors)
Custom-styled buttons and inputs remain distinguishable
Information conveyed by color alone is still accessible (use borders, text labels, or patterns as well)
CSS that uses @media (forced-colors: active) provides fallbacks where needed

Reduced motion

Some users experience discomfort, dizziness, or seizures from animations. WCAG requires that motion can be disabled.

WCAG 2.3.1 Three Flashes or Below Threshold — no content flashes more than 3 times per second
WCAG 2.2.2 Pause, Stop, Hide — auto-playing content can be paused, stopped, or hidden

How to test

macOS — System Settings → Accessibility → Display → Reduce motion
Windows — Settings → Accessibility → Visual effects → Animation effects → Off
DevTools — In Chrome, open DevTools → Rendering panel → "Emulate CSS media feature prefers-reduced-motion" → set to reduce

What to look for

Animations are reduced or removed when prefers-reduced-motion: reduce is active
Carousels and auto-playing content do not auto-advance
Page transitions are instant or very short
No content flashes more than 3 times per second (regardless of motion preference)
Essential motion (like a progress bar filling) is still allowed — only decorative or non-essential animation should be removed

Voice Control quick tip: Label in Name

Voice Control (macOS, iOS, Android) lets users interact by speaking the visible text of buttons and links — e.g., "click Search". This breaks when the accessible name doesn't match what's on screen.

WCAG 2.5.3 Label in Name — the accessible name must contain the visible text label

For example, if a button visually says Search but has aria-label="Find on the website", a Voice Control user saying "click Search" will get no response — the accessible name doesn't include the word "Search."

Rule of thumb: if an element already has a visible text label, either start aria-label with that same text or don't use aria-label at all. Let the visible text be the accessible name.

<!-- Bad: visible label says "Search" but accessible name is different -->
<button aria-label="Find on the website">Search</button>

<!-- Good: no aria-label, visible text is the accessible name -->
<button>Search</button>

<!-- Good: aria-label starts with the visible text -->
<button aria-label="Search products">Search</button>

A full Voice Control testing guide will be covered in a separate post.

See also: Video accessibility requirements

Test Keyboard Navigation

Mon, 16 Feb 2026 00:00:00 GMT

This is part 3 of the Accessibility Testing series. It covers how to test that every interactive element on your page is reachable and usable with a keyboard alone.

macOS users: Keyboard navigation is NOT enabled by default. Your test results will be inaccurate if you don't enable it:

System Settings → Keyboard → turn on Keyboard navigation
Safari only: Safari → Settings → Advanced → turn on Press Tab to highlight each item on a webpage

Key WCAG criteria

2.1.1 Keyboard — all functionality must be operable via keyboard
2.1.2 No Keyboard Trap — users must be able to navigate away from any component
2.4.1 Bypass Blocks — provide a way to skip repeated navigation (skip links)
2.4.3 Focus Order — focus order must be logical and match visual layout
2.4.7 Focus Visible — focused elements must have a visible indicator

Standard keyboard interactions

Keyboard keys and their actions
Key	Action
`Tab`	Move focus to next interactive element
`Shift + Tab`	Move focus to previous interactive element
`Enter`	Activate links and buttons, submit forms
`Space`	Activate buttons, toggle checkboxes
`Arrow Keys`	Navigate within composite widgets (tabs, menus, radio groups)
`Escape`	Close/dismiss modals, dropdowns, tooltips, menus
`Home` / `End`	Jump to first/last item in a list or menu

Although WCAG doesn't explicitly require Enter or Space for activation, it recommends that custom controls mimic native keyboard behavior to meet user expectations — otherwise, you must supply clear instructions.

Tip: Search for "Keyboard interactions" in the MDN ARIA role documentation to find the official keyboard pattern for any role.

How to test

Put your mouse aside and navigate the page using only the keyboard. As you go, check:

Skip link works — press Tab once on a fresh page load. A "Skip to main content" link should appear. Pressing Enter should move focus past the navigation.
All interactive elements are reachable — can you Tab to every link, button, input, and control?
Focus order is logical — does focus move in a sequence that matches the visual layout? No unexpected jumps?
Focus indicator is visible — can you always tell which element has focus? The indicator should be clearly visible, not just a subtle color change.
No keyboard traps — can you navigate in and out of every component? (Modals are an intentional exception — see below.)
Hidden content is not focusable — elements that are visually hidden (display: none, visibility: hidden, hidden attribute, or inside a closed <details>) should not receive focus.
All actions are possible — can you open menus, close dropdowns, submit forms, dismiss notifications, and interact with every feature without a mouse?

`tabindex` pitfalls

A common source of keyboard issues:

tabindex="0" — adds an element to the natural tab order. Use this for custom interactive elements that aren't natively focusable.
tabindex="-1" — removes from tab order but allows programmatic focus (e.g., element.focus()). Useful for elements that should receive focus only via scripts.
tabindex > 0 — avoid this. It overrides the natural DOM order and creates unpredictable navigation for keyboard users.

Common patterns to test

Modals and dialogs

Modals require special attention. When open, focus must be trapped inside — users should not be able to Tab past the modal to the page behind it.

Open the modal with the keyboard
- Focus moves into the modal
Tab through all elements in the modal
- Focus stays trapped inside the modal
Close the modal with Escape or a close button
- Focus returns to the element that opened it

The native HTML <dialog> element with showModal() handles focus trapping automatically and is the recommended approach over custom implementations.

Dropdown menus

Enter or Space opens the menu
Arrow Keys move between menu items
Escape closes the menu and returns focus to the trigger
Tab from the last item closes the menu

Tab panels

Tab moves focus to the active tab
Arrow Keys move between tabs
Tab from a tab moves focus into the tab panel content

Accordions

Enter or Space expands/collapses a section
Content inside a collapsed section is not focusable

See also: Assistive technology testing

Run Automated Accessibility Tools

Sat, 14 Feb 2026 00:00:00 GMT

This is part 2 of the Accessibility Testing series. All tools mentioned here are free — these are the ones I find most useful and use myself. They help catch accessibility issues automatically — in the browser, in your editor, and in CI.

Why use automated tools?

Catch common issues fast — color contrast failures, missing alt text, invalid ARIA roles, broken label associations
Check what's hard to spot manually — contrast ratios, computed accessible names, ARIA attribute validity
Establish a baseline — automated checks ensure basic standards are met before you start manual testing
Prevent regressions — CI integration catches new issues before they reach production

Tools cannot check all accessibility aspects automatically. Human judgement is required. Sometimes evaluation tools can produce false or misleading results. Web accessibility evaluation tools can not determine accessibility, they can only assist in doing so.

— W3C WAI: Selecting Web Accessibility Evaluation Tools

To see just how far automated tools can miss the mark, read Manuel Matuzovic's Building the most inaccessible site possible with a perfect Lighthouse score.

axe DevTools

axe DevTools is one of the most popular accessibility testing browser extensions. It scans the page and reports issues by severity (Critical, Serious, Moderate, Minor).

Install axe DevTools:

How to use: Open DevTools, go to the "axe DevTools" tab, and click "Scan". Review the issues list — each issue links to the affected element and explains how to fix it.

Lighthouse

Lighthouse is built into Chrome DevTools and uses axe-core under the hood for its accessibility audits.

In the browser — DevTools → Lighthouse tab → check "Accessibility" → click "Analyze page load"
CLI — npx lighthouse https://your-site.com --only-categories=accessibility
CI — use Lighthouse CI to run audits on every pull request and fail the build if the score drops

Lighthouse gives you a score out of 100, but remember — a perfect score does not mean your site is accessible. It means the automated checks passed.

WAVE

WAVE is another excellent tool from WebAIM. It provides a visual overlay showing accessibility issues, structural elements, and ARIA information directly on the page.

Install WAVE:

WAVE is particularly useful for its Structure view, which shows heading hierarchy and landmark regions at a glance.

CI integration with axe-core

The real power of automated testing is catching regressions before they ship. axe-core — the engine behind axe DevTools and Lighthouse — can be integrated directly into your test suite:

@axe-core/playwright — run axe checks inside Playwright tests
@axe-core/cli — run axe from the command line against any URL
cypress-axe — run axe checks inside Cypress tests

Some frameworks also offer dev-time axe integration — for example, @nuxt/a11y surfaces violations directly in Nuxt DevTools as you develop, so you can catch issues before they even reach CI.

This lets you fail a build when new automated-detectable issues are introduced. It won't replace manual testing with keyboard and assistive technologies — but it prevents known issues from shipping unnoticed.

For a step-by-step guide to setting up HTML validation and WCAG checks in your CI pipeline, see Automate Accessibility Checks in CI.

Other useful tools

WebAIM Contrast Checker

The WebAIM Contrast Checker is useful when you need to verify color contrast ratios against WCAG requirements:

WCAG AA requires a contrast ratio of at least 4.5:1 for normal text and 3:1 for large text
WCAG AAA requires at least 7:1 for normal text and 4.5:1 for large text

Browser DevTools

Both Chrome and Firefox have built-in accessibility tools — no extensions needed.

Chrome — Elements → Accessibility to inspect the accessibility tree, computed ARIA attributes, and accessible names.

Firefox — F12 → Accessibility tab. Firefox's Accessibility Inspector highlights issues directly on the page and can check for keyboard/text label/contrast issues across the entire page at once.

For testing user preferences (reduced motion, forced colors, contrast, color blindness), see the Assistive Technology Testing post.

See also: Test keyboard navigation

Validate Your HTML

Thu, 12 Feb 2026 00:00:00 GMT

This is part 1 of the Accessibility Testing series. HTML validation comes first because invalid markup can cause automated tools to miss issues or report false positives — and it affects how assistive technologies interpret your page.

Why valid HTML matters

Assistive technologies rely on the browser's DOM to build the accessibility tree. When your HTML is invalid, the browser has to guess how to parse it — and different browsers guess differently. The result: screen readers may skip content, announce elements incorrectly, or miss interactive controls entirely.

Invalid HTML also causes SSR (Server-Side Rendering) bugs and unexpected UX problems. For example:

Nesting a <button> inside an <a> creates two nested interactive elements. Screen readers may only announce the outer one, or create separate tab stops that make no sense to keyboard users.
Nesting a <div> inside a <p> is invalid — browsers silently close the outer <p> and create unexpected DOM structure. In frameworks like React, Vue, or Astro this can also cause hydration mismatches.
Nesting a <p> inside another <p> has the same problem — the browser auto-closes the outer paragraph, splitting your content in ways you won't see visually but screen readers will.

A common e-commerce example: product cards wrapped in a link

Wrapping product cards in a link is tempting, but be aware — it might be ILLEGAL 🚨

A pattern you'll see often in e-commerce: wrapping an entire product card in an <a> tag. This becomes a problem when the card contains other interactive elements — links, buttons, checkboxes, tooltips. Nested links are illegal per the HTML spec, and nesting other interactive elements inside a link leads to invalid HTML and unpredictable browser behavior. If you're using SSR, this can also trigger hydration warnings.

For a deeper look at how browsers handle these situations, see Vadim Makeev's article Jumping HTML Tags.

Not sure if one element can be nested inside another? Use caninclude — a quick tool that tells you whether a specific HTML nesting is valid.

How to validate

Use the W3C Markup Validation Service to check your page or component HTML. You can validate by:

URL — paste the live URL of your page
File upload — upload the HTML file
Text input — paste your HTML snippet directly

The validator will flag both errors (must fix) and warnings (should consider). For example:

Warning: Consider adding a lang attribute to the <html> start tag to declare the language of this document.
Error: The element button must not appear as a descendant of the a element.

Validation in your development workflow

You don't have to leave your editor to validate. There are tools that catch HTML issues as you code:

html-validate — an npm linter for HTML that can run in CI or as a pre-commit hook
eslint-plugin-jsx-a11y — ESLint plugin that catches accessibility and markup issues in JSX/TSX
Browser extensions — the W3C Nu Html Checker also offers a browser bookmarklet for quick checks

Catching issues during development is always cheaper than finding them in production.

What to look for

Focus on fixing:

Invalid nesting — elements inside parents they don't belong in (<button> in <a>, <div> in <p>)
Missing required attributes — alt on images (WCAG 1.1.1), lang on <html> (WCAG 3.1.1)
Duplicate id attributes — these break label associations and anchor links
Unclosed elements — can cause the browser to build a different DOM than you intended

See also: Run automated tools

Practical Accessibility Testing for Developers

Tue, 10 Feb 2026 00:00:00 GMT

This guide covers the basic steps of accessibility testing for software engineers — enough to make sure your feature or page meets WCAG (Web Content Accessibility Guidelines) 2.2 standards (AA Level) in most scenarios. More advanced topics like Voice Control and mobile testing will be covered in a separate guide.

Why accessibility testing matters

If you’ve never heard of accessibility (a11y), the simplest way to think about it is this: it means building a website that works well for everyone — people using keyboards, people on slow connections, people with temporary injuries, and people using assistive technologies every day. Accessibility is not just a compliance checkbox. It’s a sign of a quality website.

WCAG 2.2 AA is the standard most organizations should aim for. It is a legal requirement in many jurisdictions (EAA (European Accessibility Act) in the EU, ADA (Americans with Disabilities Act) in the US, etc.).

How to do basic accessibility testing

Each step builds on the previous one.

Tools cannot check all accessibility aspects automatically. Human judgement is required.

Sometimes evaluation tools can produce false or misleading results. Web accessibility evaluation tools can not determine accessibility, they can only assist in doing so.

— W3C WAI: Selecting Web Accessibility Evaluation Tools

Screen readers used in this guide

macOS — VoiceOver (built-in)
Windows — NVDA (free, JAWS is also widely used but requires a paid license)

See also: Video accessibility requirements

Where accessibility gets complicated — Alexandra Ignatova

Quick Tip: Recap Changes with Claude Custom Commands

Custom /summary command

Bonus: /pr-desc command

Can AI Handle Accessibility for Me?

AI and accessible code

AI coding assistants

AI-powered accessibility overlays

Where does AI help the most?

So, can AI handle accessibility for me?

What we can do with it now:

Automate Accessibility Checks in CI

Install the tools

Configure html-validate

Configure pa11y-ci

Set up the hook to validate HTML on every push

Why only html-validate in the hook?

Create the GitHub Actions workflow

What you now have

FAQ

Can I use axe-core instead of pa11y-ci?

What about Lighthouse CI?

Make Your Videos Accessible

Provide captions (A)

How to add captions

Provide alternatives (A)

Video-only example

Add audio descriptions (A, AA)

How to provide descriptions

Provide custom controls (A)

Building accessible controls

Allow stop of auto-playing (A)

Provide a transcript (AAA)

How to add a transcript

FAQ

What if my video has only background music?

Captions vs. Subtitles

Closed captions vs. Open captions

What do A, AA, AAA mean?

Test with Screen Readers & System Settings

VoiceOver (macOS)

NVDA (Windows)

What to check

Quick structure audit with the Rotor

Zoom and screen magnification

How to test

What to look for

High contrast and forced colors

How to test

What to look for

Reduced motion

How to test

What to look for

Voice Control quick tip: Label in Name

Test Keyboard Navigation

Key WCAG criteria

Standard keyboard interactions

How to test

tabindex pitfalls

Common patterns to test

Modals and dialogs

Dropdown menus

Tab panels

Accordions

Run Automated Accessibility Tools

Why use automated tools?

axe DevTools

Lighthouse

WAVE

CI integration with axe-core

Other useful tools

WebAIM Contrast Checker

Browser DevTools

Validate Your HTML

Why valid HTML matters

A common e-commerce example: product cards wrapped in a link

How to validate

Validation in your development workflow

What to look for

Practical Accessibility Testing for Developers

Custom `/summary` command

Bonus: `/pr-desc` command

`tabindex` pitfalls