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 11 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. Platform Awareness

The reference guides are web-first. Fed to an AI working on a native app, they produce dangerous hybrids — aria-live in SwiftUI, CSS pixels in Flutter — that compile to nothing or silently break assistive tech. The Constraint: The AI must identify the target platform before loading any reference. The normative layer of A11Y.md (Principle Zero, POUR, profiles, severity, governance) is platform-agnostic, but on native platforms (iOS, Android, React Native, Flutter) the web references must be read as semantic intent to translate — never implementation to copy. No ARIA attributes or CSS pixels outside the web. The guide-platform-native.md reference provides the translation table. Read more: Reference Library

9. Component Reuse

AI agents love a blank canvas. Ask for a confirmation dialog and they will happily generate a brand-new modal — even if the project already ships a battle-tested, accessible one. The Constraint: Before generating any interactive component, the AI must check for an existing implementation in the project or its design system and extend it. Generating a parallel implementation of an existing pattern is a violation.

10. Decision Memory

Two implementations can both pass A11Y.md and axe and still diverge (different role, focus pattern, announcement wording) — twenty compliant modals, zero coherence. The Constraint: Choices between equally conformant alternatives (e.g., alertdialog vs dialog for a destructive confirmation) must be recorded in A11Y-DECISIONS.md — indexed by pattern, never by screen — and reused in later turns, so the project converges on one way of doing each pattern.

11. 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).