Ai-accessibility-skill ai-accessibility-skill

AI Accessibility Skill

install

source · Clone the upstream repo

git clone https://github.com/Napsterwanp/ai-accessibility-skill

Claude Code · Install into ~/.claude/skills/

git clone --depth=1 https://github.com/Napsterwanp/ai-accessibility-skill ~/.claude/skills/napsterwanp-ai-accessibility-skill-ai-accessibility-skill-b785dd

manifest: SKILL.md

source content

AI Accessibility Skill

Analyze and optimize websites for AI accessibility (AI-friendly web design). Based on 14 best practices from @karminski-牙医 for making websites readable and actionable by AI agents, screen readers, and automated tools.

Quick Start

/ai-a11y https://example.com           # Analyze a website
/ai-a11y https://example.com --fix     # Analyze and suggest fixes
/ai-a11y ./local-file.html             # Analyze local HTML file

Why AI Accessibility Matters

As AI agents and skills become more prevalent, the way users interact with websites is shifting from direct human browsing to AI-mediated access. However, modern websites optimized for visual appeal are often unfriendly to AI access.

The Core Principle: Design your website as if it's for visually impaired users with screen readers. All content and interactive elements should have text descriptions. An AI-friendly website is essentially one that is extremely friendly to screen readers and highly structured for machine crawlers.

By implementing AI Accessibility (AI-A11Y), you not only embrace future Agent traffic but also improve human accessibility and SEO.

The 14 Principles

Category 1: DOM & Semantics

1. Use Semantic Tags and A11Y Attributes

DO: Use semantic tags like

<main>

<article>

<button>

and add aria-label for icon-only buttons.

<main>
  <article aria-labelledby="post-title">
    <h1 id="post-title">AI Friendly Checkout</h1>
    <button aria-label="Search">🔍</button>
  </article>
</main>

Why: Many agents understand pages similarly to screen readers, relying on DOM structure and accessibility information. Clear semantics lead to accurate positioning and lower misoperation rates.

2. Hide Redundant Elements to Save Tokens

DO: Add

aria-hidden

data-ai-hidden

to decorative nodes, long SVGs, and background noise layers.

<svg aria-hidden="true" class="hero-noise">
  <!-- Decorative SVG -->
</svg>

<div class="bg-grid" data-ai-hidden="true"></div>

Why: Agents count decorative elements in context. Redundant DOM distracts, increases token consumption, and slows extraction of important information.

3. Provide Stable Data Attribute Locators

DO: Add

data-testid

data-ai-action

to key interactive elements for stable identification.

<button
  data-testid="submit-order"
  data-ai-action="submit-order"
>
  Submit order
</button>

Why: If locators depend on Tailwind or CSS Modules classes, scripts may break on redesign. Stable data attributes significantly improve Playwright and agent operation reliability.

Category 2: Interaction

4. Prefer Native Form Components

DO: Use native browser components for dropdowns, checkboxes, and radio buttons instead of div-based pseudo-components.

<label for="plan">Plan</label>
<select id="plan" name="plan">
  <option value="free">Free</option>
  <option value="pro">Pro</option>
</select>

<input id="agree" type="checkbox" />

Why: Native controls have clear states and standard APIs. Playwright can interact directly. Pseudo-components often require extra clicks, scrolling, and have higher error rates.

5. Don't Hide Critical Actions in Hover

DO: Make key functions visible buttons or expandable via click, not hidden behind hover states.

<button
  type="button"
  aria-expanded="false"
  data-testid="account-menu"
>
  Account
</button>

Why: Humans instinctively explore with mouse movements, but agents are task-driven and won't probe hover states. Critical buttons invisible by default may never be discovered by AI.

6. Prefer Pagination Over Infinite Scroll

DO: Keep explicit "Previous/Next" pagination controls on list pages.

<nav aria-label="Pagination">
  <a href="?page=1">Prev</a>
  <a href="?page=3" rel="next">Next page</a>
</nav>

Why: Infinite scroll lacks clear termination conditions. Agents struggle to know when to stop. Pagination provides identifiable navigation targets for more stable crawling and execution.

7. Provide Clear Loading States

DO: Disable buttons during requests and use clear text to indicate state.

<button type="submit" disabled>
  Saving...
</button>

Why: Agents act quickly. Without standard loading states, they may trigger next steps before previous ones complete. Disabled states work naturally with automation wait mechanisms.

Category 3: Routing & Architecture

8. Use Iframes and Shadow DOM Sparingly

DO: If business requires iframe or Shadow DOM, keep sufficient context, status hints, and key summaries in the top-level DOM.

<section data-testid="payment-status">
  <h2>Payment status</h2>
  <p>Processing payment...</p>
</section>

Why: Many lightweight DOM extraction tools have incomplete iframe and Shadow DOM support. Critical content hidden in impenetrable areas may be invisible to agents.

9. Sync Page State to URL

DO: Write search terms, categories, pagination, and filters into the URL.

/products?category=shoes&page=2&sort=price-desc

Why: Agents often modify URLs or reopen links directly. If state only exists in frontend memory, they must click through from scratch. Deep links make navigation, debugging, reproduction, and sharing more direct.

Category 4: Error Recovery

10. Error Messages Must Be Clear Plain Text

DO: Write error reasons as readable text and associate with input fields.

<label for="password">Password</label>
<input id="password" aria-describedby="password-error" />
<p id="password-error">Password must include uppercase letters.</p>

Why: Agents without visual ability can't see "it turned red" but can read text error hints. As long as errors are in the DOM, agents have a chance to understand and auto-correct.

Category 5: Extra Ideas

11. Support Programmatic Input

DO: Listen to

input

and

change

events for controlled components, not just

keydown

keyup

input.addEventListener("input", handleChange);
input.addEventListener("change", handleChange);

Why: Programmatic inputs like Playwright's

fill()

trigger standard input events. If logic only binds to keyboard events, the agent may appear to "fill content" but business validation never executes.

12. Stick to Single-Page Context Principle

DO: Complete login, payment, and authorization flows within current context. Avoid unnecessary new tabs, popups, or extra windows.

<a href="/oauth/start" target="_self" rel="noopener">
  Continue with OAuth
</a>

Why: Multiple windows increase context-switching cost and can cause agents to lose focus. Keeping flows within one page chain significantly reduces automation and agent execution complexity.

13. Provide Dual Entry: UI and API

DO: Offer AI-consumable API listings and machine-readable capability indexes at obvious locations or conventional paths.

<link rel="alternate" type="application/json" href="/.well-known/ai.json" />

GET

/.well-known/ai.json

Why: This goes beyond "making webpages readable." Structured APIs are often more stable, cheaper, and efficient for AI than UI parsing—closer to future native Agent integration.

14. Consider Rate Limiting for Login, But Don't Start with reCAPTCHA

DO: Use rate limiting for login protection, but avoid reCAPTCHA unless you completely don't want AI login.

Why: reCAPTCHA is unreadable by AI. It's a barrier if you want AI agents to interact with your service.

Usage Examples

Basic Analysis

/ai-a11y https://mywebsite.com

Analysis with Fix Suggestions

/ai-a11y https://mywebsite.com --fix

Check Multiple Pages

/ai-a11y https://mywebsite.com/page1 https://mywebsite.com/page2

Output as JSON

/ai-a11y https://mywebsite.com --json

Checklist

Use this checklist to manually verify AI accessibility:

Semantic HTML tags used throughout (
```
<main>
```
,
```
<article>
```
,
```
<nav>
```
, etc.)
All images have descriptive alt text
Icon-only buttons have aria-label
Decorative elements use aria-hidden
Key elements have data-testid or data-ai-action
Native form components preferred over custom div-based ones
No critical actions hidden behind hover-only
Pagination used instead of infinite scroll (or both provided)
Loading states clearly indicated with text
iframe/Shadow DOM content mirrored in parent DOM
URL reflects page state (filters, pagination, search)
Error messages are text-based and linked to inputs
Input validation triggers on input/change events
Authentication flows stay in same tab
API endpoint available for programmatic access
No reCAPTCHA blocking AI access (or alternatives provided)

Additional Resources

Credits

Based on the excellent work by @karminski-牙医 shared on Weibo. Original post titled "14 tips to make your website better indexed by AI."

License

MIT License - See LICENSE file for details.