a11y-expert

name	a11y-expert
description	Load when implementing or reviewing frontend files, user-facing UI, or accessibility-sensitive interaction behavior and a specialist accessibility pass is useful.
version	1.1.0
required	false
category	review
tools	["claude","copilot","codex","cursor"]
routing	{"triggers":["frontend","accessibility-audit","a11y-review","jsx","tsx","vue","svelte","angular-template"],"paths":["full-path","review-path"]}
assets	["references/guide-autocomplete.md","references/guide-buttons.md","references/guide-carousels-sliders.md","references/guide-compliance-profiles.md","references/guide-content-interaction.md","references/guide-drag-drop.md","references/guide-forms.md","references/guide-framework-mapping.md","references/guide-governance.md","references/guide-images.md","references/guide-infinite-scroll.md","references/guide-loading-skeleton.md","references/guide-modals.md","references/guide-navigation.md","references/guide-platform-native.md","references/guide-responsive-mobile.md","references/guide-tables.md","references/guide-tabs-accordion.md","references/guide-toasts-notifications.md","references/guide-tooltips-popovers.md","references/guide-visual-perception.md","templates/A11Y-DECISIONS.md","templates/EXCEPTIONS.md","templates/REPORT.md"]

A11y Expert: Accessibility as a Baseline

Target standard: WCAG 2.2 AA Last updated: 2026-07-20

This document establishes the persistent context required so that the software can be certified under the WCAG 2.2 AA, ISO 9241-171, ADA, and EAA standards, depending on rigorous implementation and mandatory human validation.

0. Principle Zero: Accessibility as Pre-condition

• Accessibility is not a feature or an incremental improvement; it is a pre-condition for use.
• If a user cannot complete a task due to an accessibility barrier, the feature is considered technically broken.
• Task Completion success is our primary quality metric.

0.1. Compliance Profile

Reference: Compliance Profiles Detail

This document defaults to Standard (AA) compliance. When generating or reviewing interface code, the AI should ask the user which compliance profile to apply if not already specified:

Profile	Target	Contrast (text / UI)	Min Font†	Min Target	Use Case
🛡️ Shield (AAA)	WCAG AAA	7:1 / 3:1 (SC 1.4.6, 1.4.11)	14px†	44×44px (SC 2.5.5) · 48×48px† advised	Regulated industries, healthcare, gov
⚖️ Standard (AA)	WCAG AA	4.5:1 / 3:1 (SC 1.4.3, 1.4.11)	12px†	24×24px (SC 2.5.8) · 44×44px† advised	Default. Production apps, public web
🚀 Launchpad (A)	WCAG A	3:1† (house floor)	10px†	24×24px†	MVPs, internal tools, prototypes

† = House Rule, non-normative: this standard's ergonomic policy where WCAG requires less — or nothing — at that level. WCAG defines no minimum font size at any level; Level A defines no contrast or target-size criteria; 44–48px targets come from Apple HIG / Material Design. Skipping a WCAG SC at your target level MUST be logged in EXCEPTIONS.md; relaxing a House Rule is a product decision — record it in A11Y-DECISIONS.md.

Launchpad additionally requires explicit EXCEPTIONS.md documentation for each criterion relaxed below AA.

⚠️ The Launchpad (A) profile does NOT relax CRITICAL rules (Section 1). Keyboard operability, focus management, and semantic HTML remain mandatory at ALL levels — these are Level A requirements.

1. Severity & Impact Model

Evaluate the impact of any design or implementation decision following these levels:

• 🔴 CRITICAL: Operation failures. Blocks Task Completion or renders the function unusable (e.g., Broken keyboard navigation, Click on Div/Span, Modal without focus management). MUST FIX.
• 🟠 HIGH: Perception and Readability failures. Significantly increases Error or Abandonment Rate (e.g., Insufficient contrast, Fonts < 12px in critical text, Lack of Dynamic Feedback). MUST FIX.
• 🟡 MEDIUM: Reduces Efficiency and Satisfaction (e.g., Lack of optional keyboard shortcuts, lack of redundant labels). SHOULD FIX.
• 🔵 LOW: Cosmetic or Polish impact (e.g., Micro-interactions without aria-labels, improvements to Focus Indicators that are already visible). MAY FIX.

2. AI Behavior Contract

To ensure technical integrity, any AI interacting with this repository MUST:

• No Inference: Never infer accessibility without direct evidence in the code or specification.
• Lazy Context Loading: Reference files (references/) MUST NOT be preloaded. They MUST be consulted only when the task explicitly involves that component type. The A11Y.md alone is sufficient for most code generation tasks. If the references/ and templates/ folders are not available locally (e.g., only this file was copied into the project), resolve the relative links against the upstream repository: https://github.com/fecarrico/A11Y.md/tree/main/docs/en/.
• Reference APG: Prioritize patterns from the WAI-ARIA Authoring Practices Guide (APG).
• Protocol for Ambiguity: Follow the Complex Component Protocol in case of uncertainty.
• Explain Trade-offs: Explain impacts on Accessibility vs UX vs Business when suggesting changes.
• UI Component Interrogation: Before adding onClick to non-semantic elements, the AI MUST propose replacing them with native elements or full ARIA patterns.
• Framework Adaptation: Examples in this document use React/TSX syntax. On web frameworks, the AI MUST transpose patterns to the active project's framework while preserving semantic equivalence. Reference: Framework Mapping
• Platform Awareness: The AI MUST identify the target platform before loading any reference. The normative layer of this document (Principle Zero, POUR, profiles, severity, governance) is platform-agnostic; the technical references are web-first. On native platforms (iOS, Android, React Native, Flutter), web references MUST be read as semantic intent to translate — never implementation to copy: no ARIA attributes or CSS pixels outside the web. Reference: Platform-Native Mapping
• Component Reuse: Before generating any interactive component, the AI MUST check for an existing implementation in the project or its design system and extend it. Generating a parallel implementation of an existing pattern is a violation.
• Decision Memory: Choices between equally conformant alternatives (e.g., alertdialog vs dialog for a destructive confirmation) MUST be recorded in A11Y-DECISIONS.md — indexed by pattern, never by screen — and reused in later turns. Reference: Decisions Log
• Mode Awareness: When generating new code, apply all rules proactively. When reviewing existing code, identify violations, classify by severity (Section 1), and suggest targeted fixes — do not propose full rewrites unless the structural damage is CRITICAL. If an EXCEPTIONS.md exists, consult it: an entry there is a legitimate dispensation, but an entry past its expiry date MUST be flagged as 🟠 HIGH technical debt.

3. Technical Standards (POUR Framework)

Perceivable

References: Images | Content & Timing | Visual Perception & Color | Responsive & Zoom

• Contrast (SC 1.4.3, 1.4.11): Text MUST have 4.5:1; UI components and meaningful graphics MUST have 3:1. Prioritize real luminance difference (light vs dark) beyond hue.
• Alt Text (SC 1.1.1): Informative images MUST have a functional description in alt.
• Semantic Redundancy: MUST NOT convey state using color alone. The use of Icon + Text + Color (e.g., 🔴 Error) is the mandatory standard.
• Visual Patterns: Charts and dashboards MUST use textures or distinct line styles to ensure differentiation without color.

Operable

References: Buttons | Modals | Navigation | Tabs & Accordions | Carousels & Sliders | Drag & Drop | Autocomplete | Infinite Scroll

• Keyboard (SC 2.1.1): 100% of functionalities MUST be operable without a mouse. Avoid purely pointer-based listeners without keyboard event equivalents (onKeyDown).
• Focus (SC 2.4.7, 2.4.11): Focus MUST be visible, never entirely obscured by author content (e.g., sticky headers/footers), persistent, and never suppressed via CSS (outline: none without fallback is forbidden).
• SPA Routing (Single Page Applications): After client-side routing changes, focus MUST be managed and properly reset (e.g., sending focus to the top or an H1). Avoid lost focus on the screen.
• Targets (SC 2.5.8): Interactive elements MUST have a minimum size of 24x24 CSS pixels — the WCAG 2.2 AA floor — except when an equivalent larger target exists, sufficient spacing prevents accidental activation, or the target sits inline in text. House Rule†: design to 44x44px (48×48 under Shield), the ergonomic floor shared by Apple HIG and Material Design. Under Shield, 44×44 is normative (SC 2.5.5 AAA).
• Motion (SC 2.3.3 AAA — enforced as House Rule† at every profile): MUST respect the CSS media query @media (prefers-reduced-motion). Avoid heavy state animations during crucial transitions if the preference is active.

Understandable

References: Forms & Errors | Content & Microcopy | Tables | Toasts & Notifications | Loading & Skeletons | Tooltips & Popovers

• Labels (SC 1.3.1, 3.3.2): Forms MUST have explicit labels connected via id and for, or via tag wrapping. Avoid reinventions that break native browser events.
• Predictability: Navigation behavior MUST be consistent and interactions must not cause unannounced sudden structural changes.
• Dynamic Feedback (SC 4.1.3): Dynamic events based on component state (such as Toasts, loading, and AJAX/fetch form successes) MUST be actively read or informed through aria-live regions or modern equivalents (role="status", role="alert").

Robust

References: Governance & Compliance | Framework Mapping | Platform-Native Mapping

• Semantic HTML: MUST prefer native (HTML5) elements over custom ones.
• Interoperability: The code MUST be compatible with current assistive technologies (ISO 9241-171).

4. Visual Directives (Strict UI Criteria)

To ensure certification, these visual guidelines are non-negotiable:

• Focus Indicator (House Rule† — inspired by SC 2.4.13 AAA, whose normative metric is an indicator area ≥ a 2 CSS px perimeter with 3:1 contrast between the focused/unfocused states): The focus ring MUST have a minimum thickness of 2px and a contrast of at least 3:1 against the background. (The AA floor: focus visible — SC 2.4.7 — and not entirely obscured by author content — SC 2.4.11.)
• Typography (House Rule† — WCAG defines no minimum font size at any level): Text MUST NOT be smaller than the minimum font size of the active Compliance Profile (Section 0.1); 12px under the default Standard (AA).
  • Density Exception: In complex dashboards or secondary metadata (badges), min 10px is allowed, provided the contrast is raised to 7:1 as mitigation — a trade-off defined by this standard's policy, not by WCAG, which has no size-for-contrast compensation mechanism — and the relaxation is documented in EXCEPTIONS.md, the same logging rule that applies to profile-level relaxations (Section 0.1).
• Target Spacing & Hit Area: See Section 3 — Targets for the minimum size rule and exceptions. In dense UIs (e.g., tables), if the visual size is smaller than 44px, the hit area (invisible clickable area) MUST be expanded via CSS/padding. Adjacent targets SHOULD have 8px of spacing.

5. Complex Component Protocol

When identifying an unmapped or highly complex component (e.g., Charts, Dynamic Grids):

1. Identify: Look for a similar pattern in the WAI-ARIA APG.
2. Validate: Request human validation with a screen reader — the AI MUST NOT claim this test was performed, nor fabricate its results.
3. Document: Document expected behavior (keyboard and announcements).
4. Scale: Record the resolved pattern in A11Y-DECISIONS.md so future components reuse it instead of re-deriving it.

6. Anti-patterns (Do NOT do this)

• Clickable Divs: MUST NOT use div or span for click actions. Prefer native buttons. If forced to use them, manually replicate the behavior of a <button> (role, tabindex="0", Enter and Space event listeners).

• Leaked Focus Traps: MUST NOT create modals without managing focus.

  When a modal is open:

  • Focus MUST move into the modal
  • Focus MUST be trapped within the modal
  • Focus MUST return to the triggering element when closed
  • Background content MUST NOT be interactive or reachable via keyboard

• Placeholder Labels: MUST NOT use placeholder as the sole form of label. Crucial instructions (like date formats) MUST be visible outside the field to prevent disappearance during filling.

• ARIA Soup: MUST NOT add ARIA where native HTML already provides the semantics — no ARIA is better than bad ARIA. Forbidden by default: redundant roles (role="button" on a <button>), aria-label duplicating visible text (harmless today, but it drifts into an SC 2.5.3 failure when the text changes), and static ARIA states that are never updated (hardcoded aria-expanded — an SC 4.1.2 failure). ARIA is the fallback for gaps in native semantics (First Rule of ARIA Use), not a seasoning. (Field data: WebAIM Million 2026 — pages average 133+ ARIA attributes, 6× the 2019 figure, and more ARIA correlates with more detected errors.)

• Reinventing the Complex Wheel: If you need complex components (Autocomplete Selects, TreeViews, Datepickers), it is strongly recommended to use robust and accessible libraries (Headless UI) rather than building proprietary logic from scratch.

7. Verification Workflow (Definition of Done)

Compliance must be verified through these steps (Refer to the Report Template for final QA details and the Governance Guide for audit readiness):

• Technical Check: Clean code, testable via integrated linter (eslint-plugin-jsx-a11y or similar), and passing without critical violations through engines like Axe.
• Tab Order: Tab key path manually validated (Ensures absence of frontend dead-ends).
• User Flow: Dynamic interactions (SPAs) tested for feedback via aria-live in error and success scenarios without mouse use.
• Zoom & Reflow: Text resizes up to 200% without loss of content or function (SC 1.4.4); content reflows at 320 CSS px width — equivalent to 400% zoom on a 1280px viewport — without two-dimensional scrolling (SC 1.4.10). Preserve flexibility using relative density (Rem/Em).
• Color & Perception: No functional loss when losing the exclusive use of colors (vision deficiency simulators).
• Exceptions Audit: EXCEPTIONS.md reviewed — every active entry has a risk owner, approver, tracking issue and expiry; no expired entries left unaddressed.

---

📚 Reference & Templates Library

Technical Guides: Images | Forms | Buttons | Modals | Navigation | Content | Visual Perception | Tables | Tabs & Accordions | Tooltips & Popovers | Toasts & Notifications | Autocomplete | Carousels & Sliders | Drag & Drop | Infinite Scroll | Loading & Skeletons | Responsive & Zoom | Framework Mapping | Platform-Native Mapping | Compliance Profiles | Governance

External Standards: WAI-ARIA APG | eBay MIND Patterns | Deque Axe Core

Optional Templates: Accessibility Report | Exceptions Log | Decisions Log