Navigation

---
name: navigation
description: >
  Load this skill whenever the project contains navigation components —
  primary navigation menus, dropdown menus, mega menus, breadcrumbs,
  pagination, mobile hamburger menus, or in-page jump navigation. Under no
  circumstances create navigation without proper landmark roles, keyboard
  support, and accessible labels. Absolutely always wrap navigation in
  <nav> with a unique aria-label.
---

# Navigation Accessibility Skill

> **Canonical source**: `examples/NAVIGATION_ACCESSIBILITY_BEST_PRACTICES.md` in `mgifford/ACCESSIBILITY.md`
> This skill is derived from that file. When in doubt, the example is authoritative.

Apply these rules when creating or reviewing navigation patterns: primary nav,
dropdowns, breadcrumbs, pagination, mobile menus, and in-page navigation.
**Only load this skill if the project contains navigation components.**

---

## Core Mandate

Navigation is how users find content. Screen reader users rely on landmark
structure to orient themselves; keyboard users rely on predictable tab order and
dropdown behaviour; voice control users rely on visible, correctly-labelled
interactive elements; magnification users rely on nav that reflows without
breaking. Get navigation wrong and everything downstream is harder.

---

## Severity Scale (this skill)

| Level | Meaning |
|---|---|
| **Critical** | Navigation completely unreachable or creates a keyboard trap |
| **Serious** | Dropdown only works on hover; `role="menu"` misused; no `aria-current` |
| **Moderate** | Missing `aria-label` on secondary nav; breadcrumb not labelled |
| **Minor** | Nav item count exceeds 7; inconsistent `aria-expanded` update |

---

## Assistive Technology Context

Navigation behaves differently across AT. Test with:

| AT | Browser | Key behaviour |
|---|---|---|
| NVDA | Chrome | `H` key for headings, `R` for regions, list count announced on nav entry |
| JAWS | Chrome | `F6` for frames/regions, `Q` to move to main; announces nav landmark |
| VoiceOver | Safari (macOS) | `VO+U` rotor for landmarks and links; announces nav label |
| VoiceOver | Safari (iOS) | Swipe to navigate; nav landmark accessible via rotor |
| TalkBack | Chrome (Android) | Linear swipe navigation; landmarks via local context menu |
| Voice Control | Any | Users navigate by visible link text; all interactive elements need accurate visible labels. `aria-label` that differs from visible text breaks voice control. |
| Screen magnification | Any | Sticky/fixed navbars shrink the visible viewport. Ensure nav does not obscure content at high zoom (200%, 400%). |
| Reader Mode | Firefox/Edge/Safari | Strips nav from the article view — acceptable. Main content must make sense without it. |
| Edge Read Aloud | Edge | Reads page linearly; nav at top means it is read first — skip link is critical. |

**Voice Control note:** Dragon NaturallySpeaking and iOS Voice Control navigate
by speaking visible link text. If `aria-label` differs from or overrides visible
text, the user cannot activate the link by speaking what they see. **The accessible
name must contain the visible text.** (WCAG 2.5.3 Label in Name.)

---

## Critical: Landmark Structure

Every page must have navigational landmarks. **Missing `<nav>` landmark is Serious**
— screen reader users cannot jump to navigation via the rotor or landmarks list.

```html
<!-- Skip link — always first in <body> -->
<a class="skip-link" href="#main">Skip to main content</a>

<!-- Primary navigation -->
<header role="banner">
  <nav aria-label="Main">
    <ul>
      <li><a href="/" aria-current="page">Home</a></li>
      <li><a href="/about">About</a></li>
      <li><a href="/services">Services</a></li>
    </ul>
  </nav>
</header>

<!-- Main content -->
<main id="main" tabindex="-1">…</main>

<!-- Secondary navigation (if present) -->
<nav aria-label="Footer">…</nav>
```

Rules:
- `<nav>` wraps every navigation region
- When multiple `<nav>` elements are present, **every one** needs a unique
  `aria-label` — without it, screen readers announce "navigation" for each
  with no way to distinguish them
- `aria-label` must be short and descriptive: "Main", "Footer", "Breadcrumb",
  "Pagination" — not "Navigation menu" or "Main navigation menu"

---

## Critical: Skip Link

The skip link must be the **first focusable element** in the document and must
be **visible when focused**. A permanently hidden skip link (via `display:none`)
is a Serious issue — it defeats WCAG 2.4.1.

```css
.skip-link {
  position: absolute;
  top: -100%;
  left: 1rem;
  padding: 0.5rem 1rem;
  background: #000;
  color: #fff;
  font-weight: bold;
  text-decoration: none;
  z-index: 9999;
}
.skip-link:focus { top: 1rem; }
```

The skip link target (`#main`) needs `tabindex="-1"` so focus can be moved
to it programmatically even though it is not natively focusable.

---

## Serious: `aria-current="page"`

The current page link must be identified programmatically.
**Missing `aria-current` is Serious** — screen reader users cannot determine
where they are in the site without it.

```html
<nav aria-label="Main">
  <ul>
    <li><a href="/" aria-current="page">Home</a></li>
    <li><a href="/about">About</a></li>
    <li><a href="/contact">Contact</a></li>
  </ul>
</nav>
```

`aria-current="page"` is the correct value for navigation items linking to
the current page. Use `aria-current="true"` for other current states (current
step in a wizard, current item in a list).

Also provide a **visual** current-page indicator — never rely on `aria-current`
alone (sighted users cannot see ARIA).

---

## Serious: Do Not Use `role="menu"` for Site Navigation

**Using `role="menu"` on site navigation is Serious.** This is one of the most
common navigation ARIA mistakes.

`role="menu"` signals a desktop-application-style menu (like a File menu in a
word processor). It puts screen readers into application-menu interaction mode:
- Arrow keys navigate items (not Tab)
- Tab exits the menu entirely
- Users who expect standard link navigation are confused

Standard site navigation uses native `<a>` elements in `<ul>` lists inside
`<nav>`. No ARIA menu roles needed.

```html
<!-- Wrong — creates wrong AT interaction model -->
<nav>
  <ul role="menu">
    <li role="menuitem"><a href="/about">About</a></li>
  </ul>
</nav>

<!-- Right — native semantics, no ARIA menu roles -->
<nav aria-label="Main">
  <ul>
    <li><a href="/about">About</a></li>
  </ul>
</nav>
```

The **only** appropriate use of `role="menu"` / `role="menuitem"` in web
navigation is for application toolbar menus that genuinely replicate desktop
app behaviour with full arrow-key navigation. See the
[WAI-ARIA APG menubar pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/)
for that distinct use case.

---

## Serious: Dropdown / Disclosure Navigation

The recommended pattern for dropdown submenus is the **Disclosure pattern**
(not the APG Menubar pattern). Disclosure is simpler, has broader AT support,
and is what most users — including AT users — expect from web navigation.

### Disclosure dropdown (recommended)

```html
<nav aria-label="Main">
  <ul>
    <li>
      <!-- Option A: Top-level item is a link; separate button opens dropdown -->
      <a href="/services">Services</a>
      <button type="button"
              aria-expanded="false"
              aria-controls="services-submenu"
              aria-label="Services submenu">
        <svg aria-hidden="true" focusable="false"><!-- chevron icon --></svg>
      </button>
      <ul id="services-submenu" hidden>
        <li><a href="/services/web">Web</a></li>
        <li><a href="/services/mobile">Mobile</a></li>
      </ul>
    </li>

    <li>
      <!-- Option B: Top-level item is a button that opens dropdown only -->
      <button type="button"
              aria-expanded="false"
              aria-controls="about-submenu">
        About
        <svg aria-hidden="true" focusable="false"><!-- chevron --></svg>
      </button>
      <ul id="about-submenu" hidden>
        <li><a href="/about/team">Team</a></li>
        <li><a href="/about/history">History</a></li>
      </ul>
    </li>
  </ul>
</nav>
```

**Do not mix link and dropdown trigger on a single element.** If "Services"
is both a link to `/services` and the trigger for a dropdown, keyboard users
cannot reach the dropdown without navigating away from the page. Use Option A
(separate button) or Option B (button only, link in dropdown).

### JavaScript for disclosure dropdown

```js
document.querySelectorAll('[aria-controls][aria-expanded]').forEach(trigger => {
  const target = document.getElementById(trigger.getAttribute('aria-controls'));

  trigger.addEventListener('click', () => {
    const expanded = trigger.getAttribute('aria-expanded') === 'true';
    trigger.setAttribute('aria-expanded', String(!expanded));
    target.hidden = expanded;
  });

  // Escape closes the dropdown and returns focus to trigger
  target.addEventListener('keydown', e => {
    if (e.key === 'Escape') {
      trigger.setAttribute('aria-expanded', 'false');
      target.hidden = true;
      trigger.focus();
    }
  });
});

// Close on outside click
document.addEventListener('click', e => {
  document.querySelectorAll('[aria-controls][aria-expanded="true"]').forEach(trigger => {
    if (!trigger.contains(e.target)) {
      const target = document.getElementById(trigger.getAttribute('aria-controls'));
      trigger.setAttribute('aria-expanded', 'false');
      target.hidden = true;
    }
  });
});
```

### Hover behaviour

If hover also opens dropdowns, the dropdown **must not disappear immediately**
when the pointer moves away — users with motor impairments need time to move
the pointer into the submenu. Add a short CSS delay:

```css
.submenu { transition-delay: 0.2s; }
```

Also apply the dropdown open state on focus, not just hover — keyboard users
focus the trigger, not hover it.

---

## Moderate: Breadcrumbs

```html
<nav aria-label="Breadcrumb">
  <ol>
    <li><a href="/">Home</a></li>
    <li><a href="/services">Services</a></li>
    <li><a href="/services/web" aria-current="page">Web Design</a></li>
  </ol>
</nav>
```

- Use `<ol>` (ordered list) — breadcrumbs have a meaningful sequence
- `aria-label="Breadcrumb"` distinguishes it from other nav landmarks
- `aria-current="page"` on the current page item
- The current item may be a link or plain text — both are acceptable

---

## Moderate: Pagination

```html
<nav aria-label="Pagination">
  <ul>
    <li>
      <a href="/articles?page=1" aria-label="Previous page">
        <span aria-hidden="true">←</span>
      </a>
    </li>
    <li><a href="/articles?page=1">1</a></li>
    <li><a href="/articles?page=2" aria-current="page" aria-label="Page 2, current">2</a></li>
    <li><a href="/articles?page=3">3</a></li>
    <li>
      <a href="/articles?page=3" aria-label="Next page">
        <span aria-hidden="true">→</span>
      </a>
    </li>
  </ul>
</nav>
```

- `aria-label="Pagination"` on the `<nav>`
- `aria-current="page"` on the current page link
- Previous/Next arrows need descriptive `aria-label` — arrows alone are not
  meaningful to screen reader users
- Page numbers: `aria-label="Page 2, current"` avoids ambiguity

---

## Moderate: Mobile Navigation (Hamburger)

```html
<button type="button"
        id="mobile-menu-toggle"
        aria-expanded="false"
        aria-controls="mobile-nav"
        aria-label="Open main menu">
  <svg aria-hidden="true" focusable="false"><!-- hamburger icon --></svg>
</button>

<nav id="mobile-nav" aria-label="Main" hidden>
  <ul>
    <li><a href="/">Home</a></li>
    <li><a href="/about">About</a></li>
  </ul>
</nav>
```

```js
const toggle = document.getElementById('mobile-menu-toggle');
const nav    = document.getElementById('mobile-nav');

toggle.addEventListener('click', () => {
  const expanded = toggle.getAttribute('aria-expanded') === 'true';
  toggle.setAttribute('aria-expanded', String(!expanded));
  // Update label to reflect current state — action-based label
  toggle.setAttribute('aria-label', expanded ? 'Open main menu' : 'Close main menu');
  nav.hidden = expanded;
  if (!expanded) {
    // Move focus to first link in nav when opening
    nav.querySelector('a')?.focus();
  }
});
```

When the nav closes, return focus to the toggle button.
Apply `inert` to background content while the mobile nav is open (see
`keyboard/SKILL.md` for the `inert` pattern).

---

## Moderate: `aria-current` for Active Navigation States

Beyond `aria-current="page"`, use `aria-current` for other active states:

```html
<!-- Step indicator -->
<ol aria-label="Order process">
  <li><a href="/cart">Cart</a></li>
  <li><a href="/delivery" aria-current="step">Delivery</a></li>
  <li>Payment</li>
</ol>

<!-- Tab list (use APG Tabs pattern instead for interactive tabs) -->
<!-- For navigation-style tabs that are links: -->
<nav aria-label="Account sections">
  <ul>
    <li><a href="/account/profile" aria-current="page">Profile</a></li>
    <li><a href="/account/security">Security</a></li>
  </ul>
</nav>
```

---

## Minor: Navigation Design Principles

- **5–7 top-level items** is the cognitive limit for most users; more creates
  findability problems before accessibility ones
- Navigation items must have **consistent placement** across all pages —
  moving the nav between pages disoriented users with cognitive disabilities
- Navigation icons must have **visible text labels** — icon-only nav is a
  persistent accessibility and usability failure
- **Do not open new windows or tabs** from navigation links without warning

---

## CMS and Framework Notes

**Drupal:** Drupal's Menu module generates `<nav>` landmark markup. The active
trail uses the `.is-active` class — ensure `aria-current="page"` is also set
programmatically. The [Drupal Accessibility Coding Standards](https://www.drupal.org/docs/getting-started/accessibility/accessibility-coding-standards)
require correct landmark structure in contributed modules.

**WordPress:** Block themes use `<nav>` landmarks. Check that `wp_nav_menu()`
output includes `aria-label` when multiple menus are present — it does not by
default. Use the `nav_menu_args` filter to add it.

**React/SPA frameworks:** Single-page apps must announce page changes after
navigation. When a route changes, move focus to the new page's `<h1>` or a
designated skip target, and announce the page title via a live region. Without
this, screen reader users hear nothing after navigation.

---

## Definition of Done Checklist

* [ ] `<nav>` landmark wraps every navigation region
* [ ] Every `<nav>` has a unique, descriptive `aria-label`
* [ ] Skip link: first in DOM, visible on focus, target has `tabindex="-1"`
* [ ] `aria-current="page"` on current page link in every nav
* [ ] `role="menu"` / `role="menuitem"` not used on site navigation
* [ ] Dropdowns use Disclosure pattern: `aria-expanded`, `aria-controls`, `hidden`
* [ ] Top-level link and dropdown trigger are separate elements (not one `<a>`)
* [ ] `Escape` closes dropdown and returns focus to trigger
* [ ] Hover dropdowns: delay prevents immediate close on pointer leave
* [ ] Breadcrumb: `<ol>`, `aria-label="Breadcrumb"`, `aria-current="page"` on last item
* [ ] Pagination: `aria-label` on nav, `aria-label` on prev/next arrows, `aria-current` on current page
* [ ] Mobile nav: `aria-expanded` on toggle, focus moves into nav on open, returns on close
* [ ] `inert` applied to background while mobile nav is open
* [ ] Voice Control tested: all links activatable by speaking visible text
* [ ] Screen magnification tested at 200%: nav not covering content at high zoom
* [ ] SPA/framework: focus moved and page title announced after route change
* [ ] Tested: NVDA+Chrome, JAWS+Chrome, VoiceOver+Safari

---

## Key WCAG Criteria

* 2.4.1 Bypass Blocks (A) — **Serious if skip link absent or broken**
* 2.4.3 Focus Order (A)
* 2.4.5 Multiple Ways (AA) — navigation + search or sitemap
* 2.4.7 Focus Visible (AA)
* 2.4.11 Focus Appearance (AA, WCAG 2.2)
* 2.5.3 Label in Name (A) — **Serious for voice control if violated**
* 4.1.2 Name, Role, Value (A) — **Serious if `aria-expanded` not updated**

---

## References

* [Full best practices guide](https://github.com/mgifford/ACCESSIBILITY.md/blob/main/examples/NAVIGATION_ACCESSIBILITY_BEST_PRACTICES.md)
* [Curated resources — navigation](../resources/by-topic/navigation.md)
* [WAI Menus Tutorial](https://www.w3.org/WAI/tutorials/menus/) — structure, fly-out, application menus
* [WAI-ARIA APG — Disclosure Navigation](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/examples/disclosure-navigation/) — recommended dropdown pattern
* [WAI-ARIA APG — Menubar](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/) — for application toolbar menus only
* [Pope Tech — Accessible navigations and sub-menus](https://blog.pope.tech/2024/01/30/how-to-create-accessible-navigations-and-sub-menus/)
* [Adrian Roselli — Be careful using menu](https://adrianroselli.com/2023/05/be-careful-using-menu.html) — `role="menu"` misuse — do not scrape; link to it
* [Drupal Accessibility Coding Standards](https://www.drupal.org/docs/getting-started/accessibility/accessibility-coding-standards)
* [WCAG 2.2 Understanding 2.4.1 Bypass Blocks](https://www.w3.org/WAI/WCAG22/Understanding/bypass-blocks.html)
* [WCAG 2.2 Understanding 2.5.3 Label in Name](https://www.w3.org/WAI/WCAG22/Understanding/label-in-name.html)

> **Standards horizon:** These rules target WCAG 2.2 AA. No breaking changes
> to navigation requirements are anticipated in WCAG 3.0.
> Monitor: <https://www.w3.org/TR/wcag-3.0/>