ensure-accessibility

name	ensure-accessibility
source	botcore
description	Provides comprehensive accessibility review, guidance, and implementation patterns for WCAG 2.1+ AA compliance. Covers keyboard navigation, ARIA roles and states, screen reader support, assistive technology analysis, compliance frameworks (Section 508, ADA, EN 301 549, EAA, ACA, CVAA), UX component patterns, and accessible content authoring. Use when building interactive components, auditing UI for accessibility, implementing focus management, reviewing designs or specs against WCAG, mapping issues to compliance frameworks, or creating accessibility checklists. Triggers: accessibility, a11y, WCAG, ARIA, keyboard navigation, screen reader, assistive technology, focus management, inclusive design, compliance, Section 508, ADA.
version	1.0.0
triggers	["accessibility","a11y","WCAG","ARIA","keyboard navigation","screen reader","assistive technology","focus management","inclusive design","compliance","Section 508","ADA"]
portable	true

Ensuring Accessibility

Comprehensive accessibility review, guidance, and implementation patterns for WCAG 2.1+ AA compliance across designs, specs, and implementations.

Capabilities

1. Accessibility reviews -- Structured reviews of designs, specs, and implementations against WCAG 2.1+ AA criteria.
2. Keyboard and focus management -- Tab order, focus trapping, keyboard shortcuts, roving tabindex, and visible focus indicators.
3. ARIA patterns and semantic markup -- Roles, states, properties, labeling, and live regions for custom interactive components.
4. Screen reader analysis -- Evaluate how screen reader users perceive, navigate, and operate an experience.
5. Assistive technology coverage -- Guidance for keyboard-only, speech recognition, magnification, braille display, eye tracking, and switch access users.
6. Standards and compliance mapping -- Informational mapping to WCAG 2.x, Section 508, ADA Title II/III, EN 301 549, EAA, ACA, and CVAA.
7. UX component patterns -- Accessible patterns for buttons, forms, dialogs, tooltips, loading states, headings, accordions, and breadcrumbs.
8. Accessible content authoring -- Plain language, alt text, link text, heading structure, multimedia, and form content.
9. Targeted Q&A and troubleshooting -- Focused answers to specific accessibility questions, tradeoffs, and implementation decisions.

Routing Logic

Use the reference files to provide deep guidance on specific topics.

Intent Routing

Start by identifying the user's primary intent, then choose the appropriate entry point:

Intent	Cues	Primary reference
Full accessibility review	"Review this dialog/page/flow", "create a checklist", designs/specs/code	references/accessibility-review.md
Targeted Q&A / troubleshooting	"How do I fix this?", "Should I use this pattern?", "Why is this an issue?"	references/accessibility-qna.md
Learning / education	"Explain screen readers", "Teach me about WCAG", "What should I know about keyboard a11y?"	references/accessibility-qna.md + specialist references below
Standards and compliance	Jurisdiction, ADA, 508, EN 301 549, EAA, ACA, CVAA	references/standards-requirements/ files by jurisdiction

Assistive Technology References

Topic	Reference
Screen reader UX	references/assistive-tech/screen-reader.md
Keyboard-only interaction and focus	references/assistive-tech/keyboard.md
Speech / voice control	references/assistive-tech/speech-recognition.md
High zoom / magnification	references/assistive-tech/screen-magnification.md
Braille display	references/assistive-tech/braille-display.md
Eye tracking / gaze input	references/assistive-tech/eye-tracking.md
Switch access / scanning	references/assistive-tech/switch-devices.md

Standards and Compliance References

Topic	Reference
WCAG 2.x criteria and remediation	references/standards-requirements/wcag.md
Section 508 (U.S. federal)	references/standards-requirements/section-508.md
ADA Title II/III (U.S. state/local, public)	references/standards-requirements/ada-title-ii-iii.md
EN 301 549 (EU ICT standard)	references/standards-requirements/en-301-549.md
European Accessibility Act (EAA)	references/standards-requirements/european-accessibility-act-EAA.md
Accessible Canada Act (ACA)	references/standards-requirements/accessible-canada-act.md
CVAA (communications / video)	references/standards-requirements/cvaa.md

Use selectively based on jurisdiction and sector:

• ADA Title II/III for U.S. state/local governments and public accommodations.
• Section 508 for U.S. federal agencies and federal procurement.
• EN 301 549 / EAA for EU public sector and EU consumer products/services.
• Accessible Canada Act for Canadian federal and federally regulated entities.
• CVAA when the product is primarily a communications or video service.
• WCAG when mapping issues to criteria without a specific legal framework.

Implementation References

Topic	Reference
ARIA roles, states, and properties	references/aria-patterns.md
Keyboard navigation patterns	references/keyboard-nav.md
WCAG 2.1 AA quick reference	references/wcag-guidelines.md
Accessible content authoring	references/accessible-content.md

UX Component Pattern References

Topic	Reference
Buttons, toggles, calls to action	references/ux-component-pattern/buttons.md
Form fields, validation, errors	references/ux-component-pattern/form-fields.md
Error states and recovery flows	references/ux-component-pattern/error-states.md
Modal dialogs	references/ux-component-pattern/modal-dialogs.md
Tooltips and help affordances	references/ux-component-pattern/tooltips.md
Loading and busy states	references/ux-component-pattern/loading-states.md
Headings and structure	references/ux-component-pattern/headings.md
Accordions and disclosure	references/ux-component-pattern/accordions.md
Breadcrumb navigation	references/ux-component-pattern/breadcrumbs.md

Spec Review References

Topic	Reference
Accessibility annotations	references/spec-review/accessibility-annotations.md
Keyboard / tab order spec	references/spec-review/keyboard-tab-order-spec-review.md
Reflow / responsive spec	references/spec-review/reflow-responsive-spec-review.md
Screen reader annotations	references/spec-review/screen-reader-annotations-spec-review.md

Core Principles

1. WCAG 2.1+ AA as baseline -- Use WCAG 2.1 AA (or higher, such as 2.2 AA) as the primary reference, while acknowledging that guidance is informational and not legal advice.
2. Semantic HTML first -- Prefer native elements (<button>, <nav>, <dialog>) before reaching for ARIA. No ARIA is better than bad ARIA.
3. Broad assistive technology coverage -- Consider screen readers, keyboard-only, speech input, magnification, braille, eye tracking, and switch access. Avoid assumptions about a single "typical" user.
4. Actionable over abstract -- Prioritize concrete recommendations with specific markup, interaction patterns, or content examples over abstract theory.
5. Severity classification -- Clearly distinguish between must-fix conformance failures, should-fix usability risks, and nice-to-have enhancements.
6. Human review required -- Encourage usability testing with people with disabilities and consultation with accessibility experts for high-risk or ambiguous cases.

Workflow

Full Accessibility Review

1. Identify the artifact and scope -- Determine whether you are reviewing a design, specification, or implementation, and which user flows or pages are in scope.
2. Select assistive technologies and standards -- Based on the scenario, choose the appropriate assistive-tech and standards references from the routing tables.
3. Analyze -- Inspect structure, interaction patterns, content, and markup for accessibility issues using the relevant references.
4. Document issues and recommendations -- For each issue, capture impact, location, affected users/AT, relevant WCAG criteria, and concrete remediation guidance.
5. Prioritize and summarize -- Group findings by severity and impact, provide a concise summary, and outline clear next steps.

Targeted Q&A

1. Clarify the question and context -- What component, flow, or platform is involved? What is the user trying to achieve?
2. Identify relevant specialists -- Map the question to relevant assistive-tech, UX pattern, or standards references.
3. Provide targeted guidance -- Explain the issue in clear terms with specific markup, interaction, or content recommendations.
4. Suggest next steps -- If the question suggests broader risks, recommend a full accessibility review.

Review Output Format

Structure review outputs as:

1. Quick summary of overall accessibility health and main risks.
2. Key strengths so teams understand what to preserve.
3. Issues and risks, grouped logically with: what the issue is, why it matters (user impact), where it appears, how to fix it, and likely WCAG criteria (informational).
4. Prioritized next steps and/or a concise checklist for remediation tracking.

Quick Reference

WCAG 2.1 AA -- Four Principles

Principle	Key Requirements
Perceivable	Text alternatives for images; captions for video; color contrast 4.5:1 (text), 3:1 (large text/UI); don't use color alone
Operable	All functionality via keyboard; no keyboard traps; focus visible and not obscured; target size 24x24px minimum
Understandable	Consistent navigation; clear error messages; labels for all inputs; page language set
Robust	Valid HTML; unique IDs; custom controls expose name, role, value

Standard Keyboard Keys

Key	Action
Tab / Shift+Tab	Move between focusable elements
Enter	Activate button or link
Space	Activate button, toggle checkbox
Escape	Close modal, menu, or popup
Arrow keys	Navigate within a composite widget
Home / End	Jump to first/last item in a list

Common ARIA Patterns

Component	Role	Key Attributes
Button	button	aria-pressed, aria-expanded
Modal	dialog	aria-modal, aria-labelledby
Tab	tab / tablist	aria-selected, aria-controls
Menu	menu / menuitem	aria-activedescendant
Accordion	button + panel	aria-expanded, aria-controls
Alert	alert	Used for important announcements
Live region	--	aria-live="polite" or "assertive"

Checklist

Implementation Checklist

• All functionality is keyboard accessible (Tab, Enter, Space, Escape, Arrows)
• Focus is visible, has 3:1 contrast, and is not obscured
• Target size is at least 24x24px
• Semantic HTML is used before ARIA
• ARIA roles, states, and labels are correct and non-redundant
• Color contrast meets 4.5:1 (text) and 3:1 (large text/UI components)
• Images have appropriate alt text (or alt="" for decorative)
• Form inputs have associated labels and programmatic error messages
• Page language is set (lang attribute)
• Focus order matches visual order
• Modal dialogs trap focus and restore it on close
• Dynamic content changes are announced via live regions

Testing Checklist

• Navigate entire flow with keyboard only (no mouse)
• Test with at least one screen reader (NVDA, JAWS, or VoiceOver)
• Verify at 200% and 400% zoom (reflow, no horizontal scroll at 320px)
• Check with increased text spacing (WCAG 1.4.12)
• Run automated scan (axe, Lighthouse, or equivalent)
• Confirm color is not the sole indicator of meaning
• Verify skip links and landmark regions work correctly

Content Checklist

• Link text is descriptive and self-contained (no "click here")
• Headings follow a logical hierarchy (no skipped levels)
• Plain language is used; technical terms are explained
• Error messages are specific, polite, and actionable
• Video has captions; audio has transcripts
• Alt text is concise and describes purpose, not just appearance

When to Escalate

Escalate to human accessibility experts, legal counsel, or governance teams when:

• Requests involve formal conformance claims, policy interpretation, or legal risk decisions.
• The experience is safety-critical (healthcare, financial authorization, emergency services) where accessibility failures could have severe consequences.
• There are conflicting requirements between standards, organizational policies, or product constraints that require judgment calls.
• User feedback from people with disabilities conflicts with heuristic guidance and needs deeper investigation.
• The question requires legal interpretation of ADA, Section 508, EN 301 549, EAA, ACA, CVAA, or other regulations -- guidance here is informational only, not legal advice.