The Command Center

The Command Center (A11Y.md)

The core A11Y.md file (found in docs/en/ or docs/pt-BR/) is your project's command center. It is a dense, highly structured document designed primarily to be loaded into the persistent memory of an AI agent.

While humans can (and should) read it, its structure is optimized to give AI systems a complete behavioral framework for accessibility before any code is generated.

Here is a breakdown of its 6 core sections:

1. Principle Zero

"Accessibility is a precondition for use."

This establishes the baseline for the AI. The AI is instructed that a feature lacking accessibility is not "incomplete" — it is technically broken. The primary metric it must optimize for is Task Completion, not just passing automated linting.

0.1. Compliance Profiles

A11Y.md doesn't demand impossible perfection from day one. It introduces 3 modular profiles:

• 🛡️ Shield (AAA): Extreme rigor (7:1 contrast, 48px targets). For healthcare and gov.
• ⚖️ Standard (AA): The default (4.5:1 contrast, 44px targets). For production apps.
• 🚀 Launchpad (A): The tactical MVP profile. Relaxes visual rules (3:1 contrast, 24px targets) so startups don't abandon accessibility, but strictly enforces structural rules (keyboard, semantics). Requires an EXCEPTIONS.md log.

Proactive AI Behavior: The AI is instructed to actively ask you which Compliance Profile should be applied when starting a new session, if you haven't specified one in your initial prompt.

Read more: Compliance Profiles

2. Severity and Impact Model

A 4-level taxonomy (CRITICAL, HIGH, MEDIUM, LOW) that the AI uses to weigh trade-offs and prioritize patterns. Unlike standard linters that flag everything equally, this model teaches the AI to distinguish between an operational blocker (Critical) and a perceptual blocker (High). Read more: Severity Model

3. AI Behavioral Contract

This is the core innovation of A11Y.md. It is a set of 8 strict rules that govern how the AI should think. It prevents the AI from making dangerous inferences (like assuming a stylized <div> is accessible) and forces it to act as an architectural partner. Read more: AI Behavioral Contract

4. Technical Standards (POUR)

The AI is fed concrete, deterministic implementation rules based on the WCAG POUR principles (Perceivable, Operable, Understandable, Robust). These aren't generic tips; they are strict mandates (e.g., "never use only color for state"). Read more: Applied POUR Framework

5. Strict UI Criteria

The visual boundaries the AI must respect when generating frontend code:

• Focus Indicators: Minimum 2px thick, 3:1 contrast.
• Typography: Never smaller than 12px (except high-density UIs with AAA contrast).
• Hit Areas: Minimum 44x44px CSS target for interactive elements.

Why Absolute Values? This often causes debate in the community, but there is a specific reason for these absolute numbers: AI models need deterministic boundaries. Without absolute numbers (like 12px or 44px), Large Language Models hallucinate "visually pleasing" solutions that completely fail real-world accessibility. These absolute values do not restrict your design; they act as an unnegotiable "mathematical floor" for the machine to operate safely.

6. Verification Workflow

While A11Y.md is designed to generate accessible code from the start, it provides a 5-step "Definition of Done" that the AI and humans can use to validate the final output, ranging from automated linters to perceptual checks.