Getting Accessibility Right with Claude Code
Claude adds ARIA attributes automatically, but it often adds the wrong ones. Here's what to verify and how to prompt for real accessibility.
Claude Code includes accessibility attributes in its UI output by default. This looks good — aria-label, role, tabIndex all show up. The problem is that accessibility requires semantic correctness, not just attribute presence, and Claude sometimes adds attributes that look right but don't do what they should.
The most common mistakes
ARIA labels on elements that already have visible text. An aria-label on a button that says "Submit" is redundant. The visible text is the accessible name. Claude sometimes adds labels that duplicate the content, which can confuse screen readers.
role="button" on non-interactive elements. Adding a button role without keyboard event handlers means keyboard users can't activate the element. If it has onClick, it also needs onKeyDown for Enter/Space.
Missing focus management in modals. Claude will create modal components but sometimes omit focus trapping — when a modal opens, focus should move into it, and Tab should cycle within it, not behind it.
Color contrast in generated CSS. Claude picks colors that look reasonable but doesn't always check contrast ratios. This is the one I catch most often in review.
What to add to every UI prompt
"Ensure keyboard navigation works without a mouse. Check color contrast meets WCAG AA. Use semantic HTML elements where possible rather than div with role attributes."
This doesn't eliminate all issues but significantly improves the baseline output.
The semantic HTML preference
Ask Claude to prefer semantic HTML over ARIA where possible. A <button> is more accessible than a <div role="button"> because it handles keyboard events, focus, and browser defaults automatically. Claude knows this but sometimes reaches for div+role, especially when styling constraints are mentioned.
Verify with a screen reader or axe
The axe browser extension catches a large percentage of mechanical accessibility errors in seconds. Run it on any Claude-generated UI before shipping. It won't catch all issues (color contrast in dynamic states, focus management edge cases) but it's fast and catches the common mistakes.