AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

a11y-audit

Use for any accessibility audit or a11y fix (WCAG 2.2 A/AA, color contrast, compliance report, CI check) in React, Next.js, Vue, Angular, Svelte or HTML. Scans with a11y_scanner.py and checks contrast with contrast_checker.py, then fixes and re-verifies.

Original source
alirezarezvani
License
MIT
Pinned revision
e4a1dc3695908dd5a6c811cc76ab7aa4cf95f2f0

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read alirezarezvani--a11y-audit at revision e4a1dc3695908dd5a6c811cc76ab7aa4cf95f2f0, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 12

references/aria-patterns.md

ARIA Patterns & Keyboard Interaction Reference

Landmark Roles

Every page should have these landmarks:

<header role="banner">         <!-- Site header — once per page -->
<nav role="navigation">         <!-- Navigation — can have multiple with aria-label -->
<main role="main">              <!-- Main content — once per page -->
<aside role="complementary">    <!-- Sidebar — related but not essential -->
<footer role="contentinfo">     <!-- Site footer — once per page -->
<form role="search">            <!-- Search form -->

Semantic HTML equivalents: <header>, <nav>, <main>, <aside>, <footer> provide implicit roles — no need to double up with explicit role attributes.

Live Regions

When to Use

| Pattern | Attribute | Use Case | |---------|-----------|----------| | Polite | aria-live="polite" | Toast notifications, status updates, search result counts | | Assertive | aria-live="assertive" | Error messages, urgent alerts, form validation errors | | Status | role="status" | Loading indicators, progress updates | | Alert | role="alert" | Error dialogs, time-sensitive warnings | | Log | role="log" | Chat messages, activity feeds | | Timer | role="timer" | Countdown timers |

Implementation

<!-- Toast notifications -->
<div aria-live="polite" aria-atomic="true">
  <!-- Inject toast content here dynamically -->
</div>

<!-- Form validation errors -->
<div aria-live="assertive" role="alert">
  <p>Please enter a valid email address.</p>
</div>

<!-- Loading state -->
<div role="status" aria-live="polite">
  Loading results...
</div>

Key rule: The live region container must exist in the DOM before content is injected. Adding aria-live to a newly created element won't announce it.

Focus Management

Focus Trap (Modals)

// Trap focus inside modal
const modal = document.querySelector('[role="dialog"]');
const focusable = modal.querySelectorAll(
  'a[href], button, textarea, input, select, [tabindex]:not([tabindex="-1"])'
);
const first = focusable[0];
const last = focusable[focusable.length - 1];

modal.addEventListener('keydown', (e) => {
  if (e.key === 'Tab') {
    if (e.shiftKey && document.activeElement === first) {
      e.preventDefault();
      last.focus();
    } else if (!e.shiftKey && document.activeElement === last) {
      e.preventDefault();
      first.focus();
    }
  }
  if (e.key === 'Escape') closeModal();
});

Focus Restoration

// Save focus before opening modal
const trigger = document.activeElement;
openModal();

// Restore focus on close
function closeModal() {
  modal.hidden = true;
  trigger.focus();
}

Skip Link

<a href="#main-content" class="skip-link">Skip to main content</a>
<!-- ... navigation ... -->
<main id="main-content" tabindex="-1">
.skip-link {
  position: absolute;
  left: -9999px;
  z-index: 999;
}
.skip-link:focus {
  left: 10px;
  top: 10px;
  background: #000;
  color: #fff;
  padding: 8px 16px;
}

Keyboard Interaction Patterns

Tabs

Tab          → Move to tab list, then to tab panel
Arrow Left/Right → Switch between tabs
Home         → First tab
End          → Last tab
<div role="tablist" aria-label="Settings">
  <button role="tab" aria-selected="true" aria-controls="panel-1" id="tab-1">General</button>
  <button role="tab" aria-selected="false" aria-controls="panel-2" id="tab-2" tabindex="-1">Security</button>
</div>
<div role="tabpanel" id="panel-1" aria-labelledby="tab-1">...</div>
<div role="tabpanel" id="panel-2" aria-labelledby="tab-2" hidden>...</div>

Combobox / Autocomplete

Arrow Down   → Open list / next option
Arrow Up     → Previous option
Enter        → Select option
Escape       → Close list
Type         → Filter options

Menu

Enter/Space  → Activate item
Arrow Down   → Next item
Arrow Up     → Previous item
Arrow Right  → Open submenu
Arrow Left   → Close submenu
Escape       → Close menu

Accordion

Enter/Space  → Toggle section
Arrow Down   → Next header
Arrow Up     → Previous header
Home         → First header
End          → Last header

Framework-Specific ARIA

React

// Announce route changes (SPA)
<div aria-live="polite" className="sr-only">
  {`Navigated to ${pageTitle}`}
</div>

// Error boundary with accessible error
<div role="alert">
  <h2>Something went wrong</h2>
  <p>{error.message}</p>
</div>

Vue

<!-- Announce dynamic content -->
<div aria-live="polite">
  <p v-if="results.length">{{ results.length }} results found</p>
</div>

<!-- Accessible toggle -->
<button
  :aria-expanded="isOpen"
  :aria-controls="panelId"
  @click="toggle"
>
  {{ isOpen ? 'Collapse' : 'Expand' }}
</button>

Angular

<!-- cdkTrapFocus for modals -->
<div cdkTrapFocus cdkTrapFocusAutoCapture role="dialog" aria-labelledby="dialog-title">
  <h2 id="dialog-title">Confirm Action</h2>
</div>

<!-- LiveAnnouncer service -->
<!-- In component: this.liveAnnouncer.announce('Item added to cart'); -->

Common ARIA Mistakes

| Mistake | Why It's Wrong | Fix | |---------|---------------|-----| | <div role="button"> without keyboard | Div doesn't get keyboard events | Use <button> or add tabindex="0" + onkeydown | | aria-hidden="true" on focusable element | Screen reader skips it but keyboard reaches it | Remove from tab order too: tabindex="-1" | | aria-label overriding visible text | Confusing for sighted screen reader users | Use aria-labelledby pointing to visible text | | Redundant ARIA on semantic HTML | <nav role="navigation"> is redundant | Drop the role — <nav> implies it | | aria-live on container that already has content | Initial content gets announced on load | Add aria-live to empty container, inject content after | | Missing aria-expanded on toggles | Screen reader can't tell if section is open | Add aria-expanded="true/false" |