1. What does 508 compliance mean for a vibe-coded app?

Section 508 requires US federal agencies to buy accessible software, measured against WCAG 2.0 Level AA. Many state, education and enterprise buyers now ask for WCAG 2.1 or 2.2 AA.

Buyers don't care how the code was written. They judge what the product does, and they ask for a VPAT to prove it: a report that lists each WCAG rule and whether your product meets it.

AI output looks finished, and that's the trap. The gaps are invisible if you use a mouse and see the screen well.

Ask yourself:

• Will we sell to government, education or large enterprise?

• Has a buyer asked for a VPAT yet?

• Has anyone on the team used the app with only a keyboard?

Looking finished and being usable are two different tests.

What fails most often, and where to fix it

The same six errors make up 96% of what automated scans find on the web. That's your priority list.

2. Priority 1: Fix contrast once, in your color tokens

Low contrast text is the most common failure on the web. In one 2025 study, it was about 80% of the violations in AI-generated code.

AI tools reach for faint gray text, gray placeholders and pale borders because that's what most modern SaaS UI looks like. The fix lives in your color tokens. In a shadcn and Tailwind app, that's a handful of CSS variables. Change them once and every screen updates.

WCAG AA asks for 4.5:1 contrast for body text, and 3:1 for large text and UI parts like input borders, icons and focus rings.

One token change can clear a big chunk of an audit. Better still, decide contrast at the design stage and bake it into the brand, so it never becomes an afterthought.

The most common version I see: a brand's primary color that doesn't work in the UI. A very light green looks great in a logo. As a button with white text, or a link on white, it fails contrast. Add a darker shade of the same green to the brand palette for text and buttons, and the brand still looks like itself.

Check:

• Muted and secondary text

• Placeholder text

• Input borders and icons

• Dark mode, token by token

A lot of "clean" AI UI is clean because it's faint.

3. Priority 2: Give every button, link and field a name

Screen readers announce each control by its name. An icon-only button, an empty link or an input with only a placeholder has no name, so the user hears "button" and nothing after it.

Use real HTML elements before ARIA. A <button> comes with a role, keyboard support and focus for free. A clickable <div> comes with none of that.

Alt text counts too, and it has to say something. alt="image" passes every automated check and tells the user nothing.

Look for:

• Close, menu, copy and "more" icon buttons with no label

• Clickable <div> and <span> elements

• Inputs with a placeholder but no <label>

• Links that only wrap an icon or say "here"

• Alt text like "image", "icon" or a file name

4. Priority 3: Make your core flows work with a keyboard

Every task in your app has to work with Tab, Enter, Space, Escape and the arrow keys, with a visible focus ring the whole way. Start with the flows that make you money: signup, the main workflow, settings and billing.

AI-generated Tailwind often removes the focus ring with outline-none and puts nothing back. Custom dropdowns, date pickers and command menus written from scratch tend to break first. Swap them for tested primitives like Radix, which sits under shadcn, or React Aria.

Test:

• Put the mouse away and finish signup

• Check that you can always see where focus is

• Press Escape in every modal and check where focus lands

If you can't sign up without a mouse, a 508 reviewer can't either.

5. Priority 4: Announce what changes on screen

Toasts, inline errors, loading states and live data change on screen, but a screen reader won't announce them unless you tell it to.

Charts need a text version too. A line going up means nothing to someone who can't see it.

Dashboards are where this piles up: charts, filters and live numbers on one screen.

Add:

• A status region (role="status") for toasts and "saved" messages

• Error text linked to its field with aria-describedby

• A one-line summary or table under every chart

• Real header cells in every data table

6. How do you prompt AI tools to build accessible code?

Give the AI specific rules and real checker output, not a one-line "make it accessible."

In a 2025 study, adding a general accessibility instruction to the prompt made model output slightly worse than no instruction at all. Feeding automated test results back to the model gave the best results.

So give it rules, then give it errors. Put 5 to 10 specific rules in a rules file (CLAUDE.md, Cursor rules or Lovable's project knowledge), run a checker, paste the results back and fix. Better yet, turn them into a reusable Claude Code skill so every new screen starts from the same rules.

Use:

• Rules like: real elements first, label every input, visible focus on every control, 4.5:1 text tokens, never color alone

• axe DevTools, or axe-core in your Playwright tests, on every page

• One VoiceOver or NVDA pass per core flow before each release

Then write your VPAT honestly. A clear "partially supports" with a fix date reads better to a buyer than claims your product can't back up.

The AI writes the code. Someone still has to check it.

Final thoughts

AI made it fast to ship. It also made it fast to ship the same mistake on every screen.

That's the good news. Because vibe-coded apps repeat their mistakes, fixing a handful of components clears most of the report. The same rules apply to your marketing site, which is often the first thing a reviewer opens.

Get this right and you get:

• Government, education and enterprise deals that clear procurement

• A VPAT you can sign without stretching the truth

• Fewer support tickets from keyboard and low-vision users

• Lower exposure to ADA demand letters and EU accessibility rules