AI Behavioral Contract

AI Behavioral Contract

Most accessibility initiatives focus on what the code should do. The AI Behavioral Contract in A11Y.md focuses on how the AI should think when generating code.

It is a set of 8 deterministic constraints. Once A11Y.md is injected into the AI's context, this contract prevents the AI from falling into its natural tendency to optimize for speed and visual aesthetics at the expense of semantics and inclusion.

1. No Inference

AI agents tend to be overly optimistic. If they see a <div> styled beautifully as a button, they might infer it is a button. The Constraint: The AI must never infer accessibility. If there is no explicit semantic HTML or ARIA attribute, the AI must treat the component as inaccessible. It is programmed to be pessimistic by default.

2. Lazy Context Loading

LLMs have finite context windows. Feeding an AI every accessibility reference at once dilutes its focus and wastes tokens. The Architectural Strategy: The A11Y.md project was designed with a "Lazy Context Loading" prompt strategy. The AI is explicitly instructed to rely on the core A11Y.md file globally, but to only load specific reference files (like guide-modals.md) when the user's prompt actually requires building that specific component. The user doesn't have to manage this; the AI manages its own context.

3. Prioritize WAI-ARIA APG

When asked to build complex interactive components, AI often hallucinates proprietary logic that breaks screen readers. The Constraint: The AI must prioritize patterns from the official WAI-ARIA Authoring Practices Guide (APG). It must not reinvent the wheel for established patterns like Comboboxes or Tabs.

4. Protocol for Ambiguity

What happens when the AI is asked to build an exotic UI pattern not covered by standard guides? The Constraint: The AI must not improvise a "reasonable" guess (which usually introduces severe accessibility bugs). Instead, it must follow a strict protocol: Identify, Validate, Document the uncertainty, and Escalate to the human.

5. Explain Trade-offs

Sometimes, accessibility constraints clash with requested visual designs (e.g., adding a thick focus ring to a minimalist interface). The Constraint: The AI cannot silently sacrifice accessibility, nor can it silently break the design without explanation. It must make the trade-offs explicit so the human developer can make an informed product decision.

6. UI Component Interrogation

The "clickable div" is the most prevalent anti-pattern in AI-generated code. The Constraint: Before the AI ever adds an onClick event to a non-semantic element like <div> or <span>, it must stop, interrogate the structure, and propose replacing it with a native <button> or <a>. This acts as an internal circuit breaker for bad code. Read more: Anti-patterns & Protocol

7. Framework Adaptation

The A11Y.md reference guides use React/TSX as a baseline, but the AI must act as a semantic translator. The Constraint: The AI must transpose accessible patterns to the active project's framework (Vue, Angular, Svelte, vanilla JS) while preserving strict semantic equivalence. It cannot inject React code into an Angular project just because the documentation used React. Read more: Framework Adaptation

8. Mode Awareness

AI agents often attempt to rewrite entire files to fix a single missing aria-label, destroying the developer's work. The Constraint: The AI must be mode-aware. When generating new code, it must apply all rules proactively as an architect. When reviewing existing code, it must act as a precise surgeon, suggesting targeted fixes without proposing total rewrites (unless the structural damage is classified as CRITICAL).