Accessibility
You don’t need to become an accessibility expert. You need to know the five things that go wrong most often and how to tell Claude to fix them.
These five issues cover the vast majority of accessibility failures in web apps. Get these right and you’re ahead of most shipping products.
1. Color Contrast
Your text needs enough contrast against its background. WCAG AA requires a 4.5:1 ratio for body text and 3:1 for large text (18px bold or 24px regular).
The most common mistake: light gray text on a white background. It looks clean, but it’s unreadable for anyone with low vision — and uncomfortable for everyone else. Dark mode has its own version of this problem — dim text on dark backgrounds that technically “looks fine” on your retina display but fails the math.
Try it. Paste this into Claude:
Check all text in my app for WCAG AA contrast compliance and fix any failures.Claude will scan your styles, find the failures, and fix them. If you’re working with a dark mode theme, check the Theming guide for more on keeping contrast consistent across modes.
2. Missing Alt Text
Every image needs a decision: does it convey information, or is it decorative?
Informational images (photos, diagrams, screenshots) need descriptive alt text. Decorative images (background patterns, aesthetic icons) should be explicitly marked as decorative with an empty alt="" attribute. The common designer mistake is treating every image the same — either skipping alt text entirely or writing generic labels like “image” that tell screen readers nothing.
Try it.
Audit all images and add appropriate alt text. Mark decorative images with empty alt attributes.3. Keyboard Navigation
Everything clickable must be reachable with Tab and activatable with Enter or Space. This is where custom-styled elements break things. If you asked Claude to make a clickable card or a styled div that acts like a button, it might not be keyboard accessible by default.
Native HTML buttons and links get keyboard support for free. Custom elements need it added manually. Claude can do this — you just have to ask.
Try it.
Make sure every interactive element in my app is keyboard accessible. I should be able to tab through the entire interface.4. Focus Indicators
When someone tabs through your interface, they need to see where they are. The browser provides a default focus outline — that blue or black ring around the active element. Designers remove it constantly because it doesn’t match their aesthetic. That’s fine, as long as you replace it with something visible.
Without focus indicators, keyboard users are navigating blind. They’re pressing Tab and hoping.
Try it.
Add visible focus indicators to all interactive elements. Match the app's design language.Claude will add focus rings that fit your design system — not the default browser outline, but something intentional that still serves the purpose.
5. Semantic HTML
Using the right HTML elements — <button> for buttons, <nav> for navigation, <h1> through <h6> for headings — gives screen readers the structure they need to make sense of your page. A screen reader user can jump between headings, skip to the nav, or find the main content area, but only if you used the right elements.
Claude is generally good at this. But when you’ve been iterating fast and prompting for visual changes, structure can drift. Worth a check.
Try it.
Audit the HTML structure. Make sure we're using semantic elements — buttons, nav, headings, landmarks.Test It Yourself with VoiceOver
You can hear what your app sounds like to a screen reader right now. If you’re on a Mac:
- Open System Settings → Accessibility → VoiceOver and turn it on (or press Cmd+F5)
- Press Tab to move through the page
- Listen to what VoiceOver announces at each stop
- If something doesn’t make sense when spoken aloud — a button with no label, a heading that’s out of order, an image announced as “image” — it needs fixing
- Press Cmd+F5 again to turn it off
This takes two minutes and will immediately show you what’s broken. If you hear something wrong, describe it to Claude and ask for a fix.
Make It Stick
Prompting for accessibility every time works, but you’ll forget. The better move is to make Claude check automatically.
The Accessibility skill file drops into your project and tells Claude to build accessibly by default — semantic HTML, proper ARIA, focus management, contrast ratios — without you asking each time.
For dark mode considerations, see the Theming guide.