Making an AI-built app accessible (WCAG 2.2)

Why it matters

Accessibility is about whether people can use your product at all: people using a keyboard, a screen reader, voice control, a magnifier, or simply a phone in bright sunlight with a shaky hand. If they cannot sign up, they are not your users.

The standard to work to is the W3C's Web Content Accessibility Guidelines, WCAG 2.2. The current version of the W3C Recommendation is dated 12 December 2024. It extends WCAG 2.1, and content that conforms to 2.2 also conforms to 2.0 and 2.1. It added nine success criteria and removed one, 4.1.1 Parsing, which is now marked obsolete. Each criterion has a level: A, AA or AAA. Aim for AA, which means meeting every A and AA criterion.

AI-built apps have a specific pattern. The component layer is often good: shadcn/ui says it is built with Radix UI primitives, and Radix says its primitives follow the WAI-ARIA authoring practices, including keyboard support and focus management. The problems appear in the custom code the AI writes around those components, and in the colour, copy and layout choices made with nobody checking.

What is new in 2.2, and why it hits AI-built apps

If you last looked at accessibility under WCAG 2.1, these are the nine additions. Several land squarely on patterns AI builders like to generate.

The fixes are rarely large. Most are a scroll-padding value, a bigger hit area, a Move to menu or a correct autocomplete attribute. The hard part is knowing to look.

This checklist groups the criteria that AI-built apps most often fail, each with its number and level, so you can look up the exact wording on the W3C site.

The checklist

Structure and meaning

Keyboard and focus

Colour and contrast

Forms and sign-in

Touch, pointer and layout

Dynamic content

Common misses in AI-generated code

These are the patterns to search the codebase for first. Each one is quick to fix once you know it is there.

Clickable divs. div and span elements with an onClick look like buttons but cannot be reached with Tab or triggered with Enter, which fails 2.1.1. Replace them with button for actions and Link for navigation.

Icon buttons with no name. A trash can or a three-dot menu with no text has no accessible name, which fails 1.1.1 and 4.1.2. The shadcn/ui docs' own button example shows the fix:

<Button variant="outline" size="icon" aria-label="Delete project">
  <Trash2 />
</Button>

Note that the default icon size is size-9, 36px, which passes 2.5.8. The newer icon-xs size is size-6, exactly 24px, so check spacing if you use it in a dense row.

Removed focus outlines. Generated styles sometimes add outline-none for a cleaner look. shadcn/ui components replace the outline with a ring on focus-visible, which is fine. Custom elements often have nothing, which fails 2.4.7.

Placeholder labels. A single input with "Email address" as the placeholder and no label is a very common generated pattern. The label disappears as soon as someone types. Add a visible label tied to the input with htmlFor.

Muted text on tinted backgrounds. Grey helper text can pass 4.5:1 on white and fail on a light tinted card or a coloured banner. Check the actual pairs, not the token in isolation.

Errors in colour only. A red border with no message fails 1.4.1 and 3.3.1. Add the message in text next to the field.

Toasts for everything. A toast that disappears after a few seconds is the only feedback for many generated actions. Give it role="status" so it is announced, and for errors that need action, show them inline as well.

Drag-only interfaces. Kanban boards and sortable lists are a favourite of AI builders, and they often work only by dragging. 2.5.7 asks for a single-pointer alternative, such as a Move to menu on each card.

Charts. The shadcn/ui chart component has an accessibilityLayer prop that adds keyboard access and screen reader support. Turn it on, and add a short text summary of what the chart shows.

Motion. Tailwind's motion-reduce: variant makes it easy to respect the user's setting:

<div className="transition-transform duration-300 motion-reduce:transition-none">
  {/* animated panel */}
</div>

Next step

Do these in order. Each takes less than an hour on a small app.

1. Run an automated check on your three busiest screens with axe DevTools or Lighthouse. Fix everything it finds. These are the cheap wins: missing labels, missing names, low contrast.
2. Unplug the mouse. Complete sign-up, the main task and sign-out with only Tab, Shift+Tab, Enter, Space, Escape and the arrow keys. Note every point where focus vanishes, gets stuck or jumps.
3. Zoom to 200 percent and narrow the window to 320px. Note anything cut off, overlapping or scrolling sideways.
4. Turn on a screen reader for one flow: VoiceOver on a Mac, NVDA on Windows. Listen for unnamed buttons and silent status changes.
5. Fix the colour tokens once, in your theme, rather than screen by screen. How to make a shadcn app not look like shadcn shows where they live.

Accessibility work overlaps heavily with general UX fixes. Many items above also appear in UX mistakes AI tools make in every app, and the missing states in empty states, errors and loading states AI forgets are often where 4.1.3 fails.

If you would rather have it designed in from the start, that is how I work: accessible structure, contrast and states are part of the design and the build, not a pass at the end. See FindPopups for a product I designed and built, or the design guide for AI-built apps for where accessibility fits with the rest.