Practical Examples

Practical Examples: AI Anti-Patterns

When AI generates code without the A11Y.md context, it makes predictable, systemic mistakes. These are not theoretical examples. The anti-patterns below were extracted from real-world testing in state-of-the-art code generation systems like Figma Make and Antigravity (Gemini 1.5 Pro). They showcase the exact systemic errors these tools make "in the wild" when they lack an accessibility conscience.

Below are real-world examples of how A11Y.md forces the AI to course-correct.

1. The "Beautiful" Action Element

Without A11Y.md (The AI optimizes for visual speed):

// 🔴 CRITICAL VIOLATION: Invisible to keyboards and screen readers
<div 
  className="bg-blue-600 text-white p-4 rounded cursor-pointer" 
  onClick={() => submitOrder()}
>
  Checkout
</div>

With A11Y.md (Intercepted by Rule 6: UI Interrogation):

// ✅ CORRECT: Semantic, keyboard-operable, focusable
<button 
  type="button"
  className="bg-blue-600 text-white p-4 rounded focus:ring-4 focus:ring-blue-300"
  onClick={() => submitOrder()}
>
  Checkout
</button>

---

2. The Floating Form

Without A11Y.md (The AI optimizes for minimalism):

// 🟠 HIGH VIOLATION: Placeholder disappears, no semantic binding
<div>
  <input type="email" placeholder="Enter your email address" className="border p-2" />
</div>

With A11Y.md (Enforced Understandability):

// ✅ CORRECT: Explicit binding, persistent instruction
<div className="flex flex-col gap-2">
  <label htmlFor="user-email" className="text-sm font-medium">
    Email address
  </label>
  <input 
    id="user-email"
    type="email" 
    className="border p-2 focus:ring-2 focus:ring-black" 
  />
</div>

---

3. The Silent State Change

Without A11Y.md (The AI assumes visual change is enough):

// 🟠 HIGH VIOLATION: Blind users don't know the file was saved
const handleSave = async () => {
  await saveToDb();
  setShowSuccessToast(true); // Renders a visual green box in the corner
}

With A11Y.md (Enforced Dynamic Feedback):

// ✅ CORRECT: Screen reader announces the toast
<div 
  role="status" 
  aria-live="polite" 
  className="fixed bottom-4 right-4"
>
  {showSuccessToast && (
    <div className="bg-green-100 border-green-500 text-green-800 p-4 rounded">
      Document saved successfully.
    </div>
  )}
</div>

These examples demonstrate the core philosophy: A11Y.md does not wait for a human to find these bugs in a PR review. It conditions the AI to write the second snippet from the very first prompt.