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 8 core sections:

0. 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 text contrast per SC 1.4.6, 44px normative targets per SC 2.5.5 — 48px† advised). For healthcare and gov.
• ⚖️ Standard (AA): The default (4.5:1 contrast per SC 1.4.3; 24px WCAG floor per SC 2.5.8, with a 44px† House Rule design target). For production apps.
• 🚀 Launchpad (A): The tactical MVP profile. Relaxes visual rules (3:1† contrast floor, 24px† targets — House Rules, since Level A defines no such criteria) 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

1. 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

2. AI Behavioral Contract

This is the core innovation of A11Y.md. It is a set of 11 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. Version 1.1.0 added three rules: Platform Awareness (identify the target platform before loading references — on native platforms, web references are semantic intent to translate, never implementation to copy), Component Reuse (extend the project's existing components instead of generating parallel ones), and Decision Memory (record choices between equally conformant alternatives in A11Y-DECISIONS.md, indexed by pattern). Read more: AI Behavioral Contract

3. 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

4. Visual Directives (Strict UI Criteria)

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

• Focus Indicators: Minimum 2px thick, 3:1 contrast (a House Rule† adopting the SC 2.4.13 AAA values — AA only requires focus to be visible).
• Typography: Never smaller than 12px under the default Standard profile (a House Rule† — WCAG defines no minimum font size at any level), except high-density UIs with 7:1 contrast as mitigation.
• Hit Areas: 24x24px CSS is the WCAG 2.2 AA floor (SC 2.5.8); the AI designs to the 44x44px House Rule† target (Apple HIG / Material — normative under Shield via SC 2.5.5).

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. Since 1.1.0, every value is labeled by provenance — WCAG Success Criterion (cited by SC number) or House Rule† — so you always know what is law and what is this standard's policy.

Read more: Visual Perception & Color

5. Complex Component Protocol

When the AI faces an unmapped or highly complex component (charts, dynamic grids), it must follow a strict 4-step protocol — Identify (WAI-ARIA APG), Validate (request human screen reader validation — the AI must never claim it ran this test), Document, and Scale (record the resolved pattern in A11Y-DECISIONS.md). Read more: Anti-patterns & Protocol

6. Anti-patterns

An explicit blocklist of the most dangerous patterns in AI-generated code: clickable divs, leaked focus traps, placeholder-only labels, and reinventing complex components from scratch. Read more: Anti-patterns & Protocol

7. 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. Read more: Governance & Compliance and Operational Templates

The Reference Hub

Beyond its 8 numbered sections, A11Y.md acts as a dispatcher for 21 deep engineering guides that are loaded on-demand by the AI. Read more: Reference Library