Building accessible UIs with AI is not optional philanthropy — it is shipping quality software. Vibe-coded interfaces look polished in screenshots and fail keyboard users, screen readers, and contrast checkers in production. AI defaults to div soup, missing labels, and color-only state indicators because training data optimizes for visual similarity, not WCAG compliance. This guide gives you practical WCAG checklists and copy-paste prompts that fix the failures AI repeats on every project. Updated October 2026.
UI generation context: AI prompts for UI generation and Figma Make to production. Broader build flow: how to vibe code a web app and Vibe Coding Roadmap. Review generated markup with how to review AI-generated code.
Table of contents
- Why accessibility matters for vibe coders
- WCAG 2.1 AA practical checklist
- Copy-paste accessibility prompts
- Component-by-component fixes
- Testing accessibility
- A11y workflow per feature
- FAQ
Why accessibility matters for vibe coders
Three reasons beyond ethics:
- Legal exposure — ADA lawsuits hit SaaS and e-commerce; indie is lower risk but not zero
- SEO overlap — semantic HTML helps crawlers; see SEO for vibe-coded apps
- Product quality — keyboard navigation benefits power users; clear labels reduce support tickets
Building accessible UIs with AI means treating a11y as a required prompt pass, like TypeScript strict mode. AI will not volunteer it unless instructed.
| AI default | WCAG expectation |
|---|---|
| <div onClick> buttons | <button> or role=”button” + keyboard |
| Placeholder as label | <label for> or aria-label |
| Color-only errors | Text + icon + aria-describedby |
| Missing focus styles | Visible :focus-visible ring |
| Modal without trap | Focus trap, Escape close, aria-modal |
WCAG 2.1 AA practical checklist
Use this after every UI prompt. Check manually + automated axe/Lighthouse.
Perceivable
- All images have meaningful alt text; decorative images use alt=””
- Color contrast ≥ 4.5:1 for normal text, 3:1 for large text (18px+ bold or 24px+)
- Information not conveyed by color alone (errors, status, required fields)
- Text resizable to 200% without loss of content or functionality
- Captions or transcripts for video/audio content
Operable
- All functionality available via keyboard — Tab, Enter, Space, Escape, arrows where appropriate
- Visible focus indicator on all interactive elements
- No keyboard traps except intentional modals with documented Escape exit
- Skip link to main content on marketing pages
- Touch targets minimum 44×44 CSS pixels on mobile
- No content flashing more than 3 times per second
Understandable
- Page language set: <html lang=”en”>
- Form inputs have associated labels; errors linked via aria-describedby
- Consistent navigation across pages
- Error messages identify field and suggest fix
- Autocomplete attributes on common fields (email, name, address)
Robust
- Valid HTML — no duplicate IDs
- ARIA roles used correctly; prefer native elements first
- Name, role, value exposed to assistive tech for custom widgets
- Status updates use aria-live regions (toasts, form submission feedback)
Copy-paste accessibility prompts
Add to every UI generation prompt or run as dedicated audit pass:
Build this component WCAG 2.1 AA compliant: semantic HTML, button not div, labels on all inputs, focus-visible styles matching design tokens, aria-label on icon-only buttons, color contrast 4.5:1 minimum, keyboard operable, no positive tabindex.
Audit pass prompt:
Audit components/ui/ for WCAG 2.1 AA violations: replace div buttons with button, add missing labels, fix heading hierarchy (one h1 per page), add focus rings, fix contrast failures, add aria-expanded on toggles, trap focus in Dialog. Minimal diff; list changes made.
Modal prompt:
Implement Dialog using Radix/shadcn pattern: aria-modal, role dialog, aria-labelledby, focus trap, Escape closes, return focus to trigger on close, overlay click closes optional per prop.
Form prompt:
Signup form: label every input, aria-invalid and aria-describedby on errors, announce errors in aria-live=”polite” region, required fields marked with text not color only, autocomplete email and name.
Navigation prompt:
Main nav: nav landmark, ul/li structure, current page aria-current=”page”, mobile menu button aria-expanded and aria-controls, keyboard arrow navigation optional, skip link as first focusable element.
Data table prompt:
Table: th scope col/row, caption or aria-label, sortable columns announce sort direction in aria-sort, responsive card fallback on mobile maintains equivalent info.
Component-by-component fixes AI misses
| Component | Common AI failure | Fix prompt snippet |
|---|---|---|
| Dropdown | Mouse-only open | “Arrow keys navigate items; Enter selects; Escape closes” |
| Tabs | Div tabs | “Use role tablist, tab, tabpanel; roving tabindex” |
| Toast | Silent notification | “aria-live polite region; role status or alert by severity” |
| Carousel | Auto-rotate no pause | “Pause on hover/focus; prev/next buttons labeled” |
| Icon button | No accessible name | “aria-label=’Close dialog’ on X button” |
| Loading spinner | No context | “role status aria-label Loading; sr-only text” |
Design-to-code pipelines break a11y first — read Figma Make to production recovery section. Use prompt chains: layout pass, then dedicated a11y pass.
Testing accessibility
- Automated — axe DevTools extension, Lighthouse accessibility audit, eslint-plugin-jsx-a11y in CI
- Keyboard only — unplug mouse; Tab through entire flow; activate with Enter/Space
- Screen reader spot check — VoiceOver (Mac) or NVDA (Windows) on signup and checkout
- Zoom — 200% browser zoom; no horizontal scroll on critical paths
- Contrast — WebAIM contrast checker on text/background pairs AI chose
Prompt: “Add eslint-plugin-jsx-a11y to eslint config; fix all errors in components/ without disabling rules.”
Debug stubborn issues with debugging prompts — paste axe violation output into agent.
A11y workflow per feature
Integrate into vibe coding rhythm, not launch-week panic:
- Generate UI with a11y constraints in initial prompt
- Run axe on preview deploy — fix Critical/Serious
- Keyboard test happy path
- Commit with note “a11y pass” in PR description
- Re-audit after any “make it prettier” prompt — visual tweaks break contrast
Add to system prompt templates: “All UI must meet WCAG 2.1 AA. Never use div as button. Always include focus-visible styles.”
Accessible design tokens
Define focus ring color, error color with sufficient contrast on all backgrounds, and minimum touch target spacing in your token file. Prompt: “Add –focus-ring and –error-text tokens; ensure 4.5:1 contrast on –background and –card.”
Marketing vs app accessibility
Marketing pages need skip links and semantic landmarks. App dashboards need table semantics and live regions for async updates. Scope prompts per surface — do not run marketing checklist on admin DataGrid.
Ship accessible apps via Vercel deploy. Compare UI tools in v0 vs Lovable — both need post-export a11y pass.
When to reach beyond AA
AA covers most legal and user needs. Consider AAA contrast (7:1) for body text in health/finance apps. Consider extended audio descriptions for education products. Government RFPs may mandate WCAG 2.2 — check contract before bidding.
shadcn/ui accessibility audit prompts
shadcn components wrap Radix — good primitives, custom themes break contrast:
- “Audit Button variants: destructive, outline, ghost — all pass 4.5:1 on background”
- “Audit Input focus ring visible in dark mode”
- “Combobox: screen reader announces selected value and filter results count”
Legal landscape for indie founders
ADA Title III lawsuits target e-commerce and SaaS with public signup. Risk scales with revenue and US customer concentration. Accessibility is cheaper than counsel. Document your audit trail: axe reports, fix commits, checklist completion date.
Mobile accessibility specifics
VoiceOver on iOS and TalkBack on Android behave differently from desktop screen readers. Test mobile web signup flow with screen reader enabled. Common AI mobile failures: tiny touch targets, modals that do not scroll when keyboard open, fixed headers covering focused inputs.
Prompt: “Mobile audit: all interactive elements min 44px touch target; modals scrollable; inputs not hidden behind fixed nav on focus.”
Automated a11y in CI
Prompt: “Add @axe-core/playwright to e2e signup test; fail CI on violations with impact critical or serious. Allowlist documented exceptions in tests/a11y-allowlist.json with justification comment.”
Runs on preview deploy — catches regressions when you prompt “make the design pop” and contrast dies.
Landmarks and page structure
Every page needs semantic landmarks AI skips:
- One
mainelement per page headerfor site nav,footerfor linksnavwith aria-label when multiple nav regions existasidefor supplementary content, not primary flow
Prompt: “Audit app/(marketing)/layout.tsx: add header, main, footer landmarks; skip link as first focusable element targeting #main-content.”
Dark mode accessibility
Vibe-coded dark themes often fail contrast on muted text and border colors. Test both modes with axe — toggle class="dark" on html in DevTools. Prompt: “Audit all text-* and border-* utilities in dark mode; ensure 4.5:1 against dark background tokens; fix muted-foreground token if needed.”
Advanced form accessibility
Multi-step forms need:
- aria-current=”step” on progress indicator
- Focus move to first field on step change
- Summary of errors at top with links to fields — not only inline
- Do not disable Submit while loading — use aria-busy on form
Password fields: toggle show/hide must not remove label association; button needs aria-label “Show password”.
Inclusive language in AI-generated copy
AI UI copy defaults to “Hey guys” and ableist metaphors. Accessibility includes language. Prompt: “Review all user-facing strings in components/ for inclusive language; gender-neutral greetings; no ‘click here’ link text; link text describes destination.”
Accessible media and motion
Auto-playing video backgrounds trend in AI-generated marketing pages — they harm users with vestibular disorders and eat bandwidth. Prompt: “Remove autoplay from hero video; add controls; respect prefers-reduced-motion: reduce — disable parallax and large transitions.” For essential animation, keep duration under 500ms and provide pause controls on carousels.
Charts and data visualizations need text alternatives: table summary or aria-label describing trend. AI-generated Recharts often lack accessible names — prompt: “Add aria-label to chart container summarizing data trend in one sentence.”
Accessibility in design-to-code handoff
When importing from Figma Make or v0, run accessibility audit before backend wiring. Fixing div-buttons after Supabase integration means retesting every authenticated flow. Order: semantic HTML pass → contrast pass → keyboard pass → then data. See Figma Make to production for parallel design fixes.
Screen reader users are not edge case — they are paying customers, employees at enterprise accounts evaluating your SaaS, and users in jurisdictions where accessibility lawsuits create real liability. Budget one hour per major release for manual keyboard and VoiceOver pass. Automated axe catches roughly sixty percent of issues; human testing catches the context failures automation misses.
Publish a simple accessibility statement at /accessibility — contact email for accommodation requests, conformance target WCAG 2.1 AA, last audit date. Takes one prompt and signals good faith to enterprise buyers reviewing your vibe-coded product.
FAQ
Is WCAG AA enough?
Yes for most indie SaaS. AAA for specific contracts or government; AA is industry standard.
Do shadcn components pass a11y?
Radix primitives are solid; custom styling can break contrast. Still audit composed pages.
Can AI fix all a11y issues?
80% automated fixes; screen reader flow and alt text meaning need human judgment.
Accessibility vs vibe coding speed?
+10–15 min per component with prompts above — cheaper than retrofitting or lawsuits.
Building accessible UIs with AI requires explicit prompts, the WCAG checklist above, and automated testing in every deploy preview. Audit after generation, keyboard test before merge, encode rules in agent system prompts. Pair with UI generation prompts and review with code review guide.
