AI-Friendly Web Design (AI Accessibility)

Original: @karminski-牙医 · Compiled by: @ianho7

Core principle: Treat AI agents the same way you'd treat a screen reader for a visually impaired user.

Getting AI Accessibility right is a win on three fronts simultaneously: future-proofing for agent traffic, improving human accessibility, and boosting SEO.

---

Prime Directive

Minimize modals and popups. They're bad for humans and bad for AI. When you must alert the user, use a banner instead.

---

Core Checklist

DOM Structure & Semantics

• Use semantic HTML tags: <main>, <article>, <nav>, <button>, etc. Add aria-label to icon-only buttons
• Hide decorative elements: Mark long SVGs, background layers, and visual noise with aria-hidden="true" or data-ai-hidden="true" to reduce irrelevant token consumption
• Provide stable locators: Add data-testid="submit-order" or data-ai-action="submit-order" to key interactive nodes — never rely on volatile Tailwind-generated class names

Forms & Interactions

• Use native form controls: Prefer <select>, <input type="checkbox"> over div-based custom components — native controls have standard APIs that tools like Playwright can drive directly
• Don't hide actions behind hover: Agents won't probe hover states; content that's only visible on hover may never be discovered
• Listen to input/change events: Programmatic input doesn't fire keydown/keyup — relying solely on keyboard events will break validation
• Error messages must be plain text: Use aria-describedby to surface readable error text; don't rely on color changes alone

State & Navigation

• Make loading states explicit: Disable buttons during loading and show text like "Saving..." or "Loading..."
• Prefer pagination over infinite scroll: Pagination controls give agents a clear navigation target; infinite scroll has no definable end condition
• Sync state to the URL: Write search terms, filters, categories, and page numbers into the URL to support deep linking and reproducibility

Context & Isolation

• Use iframes and Shadow DOM sparingly: If unavoidable, keep enough context, status hints, and key summaries in the top-level DOM — many lightweight extraction tools can't pierce these boundaries
• Complete critical flows in-page: Keep login, payment, and authorization in the current context; avoid opening new tabs or popup windows, which cause agents to lose focus

Advanced: Dual Entry Points

• Expose an AI-consumable API manifest at .well-known/ai.json or a prominent location
• Don't default to ReCAPTCHA — it's an impenetrable wall for AI agents; prefer rate limiting, honeypot fields, or behavioral analysis instead

---

Code Review Checklist

When reviewing frontend code, check in order:

1. Do interactive elements have semantic tags or aria-label?
2. Are decorative elements marked with aria-hidden?
3. Do key buttons and forms have stable data-testid or data-ai-action attributes?
4. Are any actions only reachable via hover?
5. Are forms using native controls or div-based simulations?
6. Are error messages in readable text form, not just color changes?
7. Do loading states include disabled + text feedback?
8. Do critical flows open new tabs or popup windows?

For full rationale and code examples, see references/guidelines.md