Reference Library

The Reference Library

The core A11Y.md file is the command center, but it cannot contain the specific ARIA logic for every single component in existence. That is why the project includes a massive Reference Library.

Currently containing 21 engineering guides (guide-*.md), this library is an actionable, code-ready database of accessibility protocols.

The Taxonomy of the 21 Guides

To manage complexity, the library is divided into four logical domains:

Domain 1: Interactive Components & APG

Focused on expected behavior (keyboard, ARIA roles, focus management) based on the W3C standards.

• guide-buttons.md — Buttons, CTAs, actions.
• guide-forms.md — Inputs, validations, explicit label binding.
• guide-modals.md — Native dialogs, focus trapping.
• guide-tabs-accordion.md — Hidden panels, aria-expanded, arrow key navigation.
• guide-carousels-sliders.md — Pause controls, navigation buttons, aria-roledescription.
• guide-autocomplete.md — Comboboxes, aria-activedescendant, aria-controls.
• guide-tooltips-popovers.md — Popover API, hover timeout, aria-describedby.
• guide-tables.md — Complex data grids, associated headers (scope).

Domain 2: Interface Patterns & Experience

Lidando com a macro-escala de como o usuário navega e percebe o conteúdo.

• guide-navigation.md — Landmarks (<nav>, <main>), skip links.
• guide-content-interaction.md — Microcopy, timeouts, media alternatives.
• guide-visual-perception.md — Colors, contrasts (APCA/WCAG), color blindness rules.
• guide-images.md — Alt text heuristics (decorative vs informative vs complex).
• guide-responsive-mobile.md — Text resize up to 200% (SC 1.4.4), reflow at 320 CSS px ≈ 400% zoom (SC 1.4.10), touch targets.

Domain 3: Dynamic & Modern Patterns

Focused on Single Page Applications (SPAs) and rich interactions that typically break screen readers.

• guide-toasts-notifications.md — aria-live polite vs assertive.
• guide-drag-drop.md — Keyboard operability for drag & drop (reordering shortcuts).
• guide-infinite-scroll.md — Using "Load More" buttons instead of auto-fetching for keyboard users.
• guide-loading-skeleton.md — Announcing "busy" states during skeleton screen rendering.

Domain 4: Governance, Architecture & Compliance

Guides geared towards software architecture, accessibility DevOps, and auditing.

• guide-governance.md — Audit prep (EN 301 549, ADA), legal documentation.
• guide-compliance-profiles.md — How to apply and transition between Shield, Standard, and Launchpad.
• guide-framework-mapping.md — How to transpose semantic patterns across React, Vue, Svelte, and Angular.
• guide-platform-native.md — The web→native translation layer: how to map semantic intent (never web idioms) to iOS, Android, React Native, and Flutter.

---

Lazy Context Loading in Action

If you ask your AI to "Build a DataGrid with drag & drop and infinite pagination", you do not want it to load all 21 guides into its memory. Doing so would bloat the prompt, waste tokens, and confuse the AI.

Because of Rule 2 of the AI Behavioral Contract (Lazy Context Loading), the AI is programmed to manage its own context. It will surgically search your repository and load only:

1. A11Y.md (The core rules)
2. guide-tables.md
3. guide-drag-drop.md
4. guide-infinite-scroll.md

The reference library is not a book to read front-to-back; it is a queryable database for your AI agent.