Setup and Integration

A11Y.md is fundamentally a context injection tool.

Rather than embedding accessibility rules into every conversation, it teaches AI coding agents when accessibility knowledge should be loaded.

Its purpose is to make accessibility part of your project's development process before the first line of code is written, while keeping the agent's permanent context lean.

If you're interested in the architectural rationale behind this approach, see Performance & Context Loading.

---

Choosing an Integration Method

Choose the setup that best matches your AI development environment.

Method 1 — Persistent Project Instructions (Recommended)

If your coding agent supports persistent project instructions (such as CLAUDE.md, .cursorrules, AGENTS.md, or similar files), this is the recommended integration method.

Step 1 — Add the standard

Copy docs/en/A11Y.md into your project's repository.

It can be placed in the project root, inside a docs/ directory, or anywhere else that your coding agent can access.

Optionally, copy the references/ and templates/ directories alongside it to make the complete documentation available offline.

If you choose not to copy these directories, A11Y.md automatically falls back to the official reference guides hosted in this repository whenever additional guidance is required.

This allows teams to keep only the core standard inside their repository while still benefiting from the complete A11Y.md ecosystem.

Step 2 — Inject the command

Add the following directive to your project's persistent instruction file:

When developing the frontend, strictly follow the development rules defined in the A11Y.md file.

This instruction intentionally remains very small.

Rather than embedding accessibility rules into the agent's permanent context, it simply tells the agent when to load A11Y.md, allowing accessibility guidance to be introduced only for frontend-related tasks.

For environment-specific installation examples, see docs/en/SETUP.md.

---

Method 2 — Global Custom Instructions

Some AI tools provide global custom instructions instead of repository-level configuration (for example, GitHub Copilot or Gemini).

Whenever possible, add a lightweight instruction that points to A11Y.md instead of embedding the entire document into the system prompt.

Embedding the full document should only be considered when external files cannot be referenced.

For environment-specific installation examples, see docs/en/SETUP.md.

---

Method 3 — Zero-shot Prompt

If you're starting a temporary conversation without any persistent project context, you can manually inject the context at the beginning of your prompt by pointing your AI assistant to a local A11Y.md file or to the official GitHub repository.

Example:

When developing the frontend, strictly follow the development rules defined in local/path/to/A11Y.md.

or

When developing the frontend, strictly follow the development rules defined in https://github.com/fecarrico/A11Y.md/blob/main/docs/en/A11Y.md.

Because this context isn't persisted, you'll need to repeat the instruction whenever you start a new conversation.

For environment-specific installation examples, see docs/en/SETUP.md.

---

Repository Layout

The minimum setup consists of a single file:

project/
├── A11Y.md
└── ...

The repository also includes additional resources such as reference guides, templates, and supporting documentation.

These resources are optional and are designed to be loaded only when deeper guidance is required for a specific implementation.

To explore the available documentation, see Reference Library.

---

What Happens After Injection?

Once the instruction has been injected, the coding agent knows when accessibility guidance becomes relevant.

Conceptually, the workflow looks like this:

Conversation starts
        │
        ▼
Persistent instruction
        │
        ▼
"When developing the frontend..."
        │
        ├── Backend task
        │        │
        │        └── A11Y.md is never loaded
        │
        └── UI / Frontend task
                 │
                 ▼
            Load A11Y.md
                 │
                 ├── Apply accessibility rules
                 ├── Validate implementation
                 └── Load additional references if needed

This keeps backend, infrastructure, and unrelated tasks free from unnecessary accessibility context while ensuring accessibility expertise is introduced automatically whenever frontend work becomes relevant.

---

Lazy Context Loading

A11Y.md is intentionally designed around Lazy Context Loading.

The main document acts as an orchestration layer.

When a task requires more specialized guidance—such as forms, buttons, modals, navigation, typography, or other UI patterns—the agent loads only the documentation relevant to that implementation.

Instead of loading an entire accessibility knowledge base into the model's context window, information is retrieved progressively as the implementation evolves.

Learn more about the reasoning behind this architecture in Performance & Context Loading.

---

Choosing a Compliance Profile

A11Y.md supports multiple compliance profiles so teams can adopt the level that best matches their product requirements.

For most projects, Standard (WCAG 2.2 AA) is the recommended profile.

If you're unsure which profile to choose, start with Standard (AA) and adjust as your project's accessibility requirements evolve.

See Compliance Profiles for the complete profile descriptions.

---

Best Practices

• Keep the injected instruction as small as possible.
• Store accessibility knowledge inside A11Y.md, not inside your persistent prompt.
• Version-control A11Y.md alongside your project.
• Copy only the resources your team needs locally; additional reference material can be resolved from the official repository when required.
• Allow additional reference documents to load only when they are needed.
• Keep A11Y.md updated as your accessibility standards evolve.

---

Next Steps

After completing the setup, continue with:

1. Compliance Profiles — choose the accessibility profile that best fits your project.
2. AI Behavioral Contract — understand how A11Y.md guides AI coding agents during implementation.
3. Performance & Context Loading — learn why the project uses Lazy Context Loading.
4. Reference Library — explore implementation guides, templates, and component-specific references.