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