Performance & Context Loading

One of the first questions raised about A11Y.md is whether adding another context file increases the model's token consumption enough to become impractical.

The short answer is no — because A11Y.md was designed around scoped loading, not permanent residency.

---

Context is a limited resource

Modern coding agents already dedicate a significant portion of their context window to information that exists before a conversation even begins.

A real production session using Cursor with Claude (1M-token context window) produced the following breakdown:

Category	Tokens	Share
Conversation	64.7K	29.5%
Rules (persistent context)	60.8K	27.7%
Skills	33.4K	15.2%
Tool definitions	25.6K	11.7%
MCP & dynamic tools	19.3K	8.8%
Subagents	8.8K	4.0%
System prompt	6.6K	3.0%

At the time of the snapshot:

• Context window: 1,000,000 tokens
• Context in use: ~219K tokens (22%)
• Persistent context before the conversation even started: ~154K tokens

This demonstrates an important architectural reality:

The largest consumers of context are typically the agent's persistent rules, skills, and tooling—not the application conversation itself.

---

Where does A11Y.md fit?

During the evaluation session, A11Y.md was not installed as a persistent rule.

Instead, the document was read once when an accessibility-related task required it.

The observed impact was approximately:

Operation	Approximate Cost
Not loaded	0 tokens
Scoped rule reference (estimated)	~80 tokens
Reading A11Y.md	~2.7K tokens

The ~2.7K figure reflects the document being loaded during that specific evaluation session. It should be considered an observed measurement, not a fixed property of the project. As the document evolves, this number will naturally change.

---

Why lazy loading matters

A11Y.md intentionally follows a progressive loading strategy.

Instead of permanently occupying the model's working memory, accessibility guidance is introduced only when the current task involves frontend or user interface work.

Conceptually:

Task
 │
 ├── Backend?
 │      └── A11Y.md is never loaded.
 │
 └── UI / Frontend?
        │
        ▼
    Load A11Y.md
        │
        ├── Accessibility principles
        ├── Interaction guidance
        ├── WCAG references
        └── Additional documentation only if needed

This approach minimizes permanent context usage while ensuring accessibility expertise is available exactly when it is relevant.

---

Why this architecture was chosen

The goal of A11Y.md is not to become another large permanent system prompt.

Instead, it is designed as a specialized knowledge source that can be loaded on demand.

This provides several advantages:

• Keeps backend and infrastructure tasks free from unnecessary accessibility context.
• Reduces permanent context occupation.
• Scales naturally as additional accessibility documentation is added.
• Aligns with how modern coding agents progressively load specialized knowledge.

---

Engineering principle

The philosophy behind A11Y.md can be summarized in one sentence:

Accessibility expertise should be available when needed—not occupy context when it isn't.

As coding agents evolve, efficient context management becomes just as important as the quality of the guidance itself.

A11Y.md therefore treats context loading as an architectural concern, not simply a token optimization strategy.

---

Notes

• The measurements presented here come from a real production Cursor + Claude session using a 1M-token context window.
• Values are approximate and intended to illustrate architectural behavior rather than provide fixed benchmarks.
• Actual token consumption depends on the version of A11Y.md, the model, the coding agent, and how the document is loaded.