navigation

Name: navigation
Author: mgifford

27stars2forks

How to install navigation?

mgifford/accessibility-skills/navigation

$npx -y skills add mgifford/accessibility-skills --skill navigation

Installs into the current project.

Summary

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, keyboar

Files · 1

View on GitHub

SKILL.md

1	# Navigation Accessibility Skill
2
3	> Canonical source: `examples/NAVIGATION_ACCESSIBILITY_BEST_PRACTICES.md` in `mgifford/ACCESSIBILITY.md`
4	> This skill is derived from that file. When in doubt, the example is authoritative.
5
6	Apply these rules when creating or reviewing navigation patterns: primary nav,
7	dropdowns, breadcrumbs, pagination, mobile menus, and in-page navigation.
8	Only load this skill if the project contains navigation components.
9
10	---
11
12	## Core Mandate
13
14	Navigation must remain understandable and operable with keyboards, touch,
15	speech input, screen readers, screen magnification, text resizing, and
16	browser zoom. Screen reader users rely on landmark structure to orient
17	themselves; keyboard users rely on predictable tab order and dropdown
18	behaviour; voice control users rely on visible, correctly-labelled
19	interactive elements; magnification users rely on nav that reflows without
20	breaking. Get navigation wrong and everything downstream is harder.
21
22	---
23
24	## Severity Scale (this skill)
25
26	\| Level \| Meaning \|
27	\|---\|---\|
28	\| Critical \| Navigation completely unreachable or creates a keyboard trap \|
29	\| Serious \| Dropdown only works on hover; `role="menu"` misused; no `aria-current` \|
30	\| Moderate \| Missing `aria-label` on secondary nav; breadcrumb not labelled \|
31	\| Minor \| Nav item count exceeds 7; inconsistent `aria-expanded` update \|
32
33	Do not assign severity from the pattern alone — determine the actual effect
34	on navigation and task completion. Consider whether users can reach main
35	content, whether a menu can be opened/operated/closed/left, whether focus
36	becomes trapped or lost, and whether the defect affects every page through a
37	shared component (a shared nav trap can block an entire site).
38
39	---
40
41	## Assistive Technology Context
42
43	Navigation behaves differently across AT. Test with:
44
45	\| AT \| Browser \| Key behaviour \|
46	\|---\|---\|---\|
47	\| NVDA \| Chrome \| `H` key for headings, `R` for regions, list count announced on nav entry \|
48	\| JAWS \| Chrome \| `F6` for frames/regions, `Q` to move to main; announces nav landmark \|
49	\| VoiceOver \| Safari (macOS) \| `VO+U` rotor for landmarks and links; announces nav label \|
50	\| VoiceOver \| Safari (iOS) \| Swipe to navigate; nav landmark accessible via rotor \|
51	\| TalkBack \| Chrome (Android) \| Linear swipe navigation; landmarks via local context menu \|
52	\| 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 \|
53	\| Screen magnification \| Any \| Sticky/fixed navbars shrink the visible viewport at high zoom (200%, 400%) \|
54	\| Reader Mode \| Firefox/Edge/Safari \| Strips nav from the article view — acceptable; main content must make sense without it \|
55
56	Voice Control note: Dragon and iOS Voice Control navigate by speaking
57	visible link text. If `aria-label` differs from visible text, users cannot
58	activate the link by speaking what they see — **the accessible name must
59	contain the visible text** (WCAG 2.5.3 Label in Name).
60
61	---
62
63	## Critical: Landmark Structure
64
65	```html
66	<a class="skip-link" href="#main-content">Skip to main content</a>
67
68	<header>
69	<a href="/">Service name</a>
70	<nav aria-label="Primary">
71	<ul>
72	<li><a href="/services">Services</a></li>
73	<li><a href="/guidance">Guidance</a></li>
74	</ul>
75	</nav>
76	</header>
77
78	<main id="main-content" tabindex="-1">
79	<h1>Page title</h1>
80	</main>
81
82	<footer>
83	<nav aria-label="Footer">…</nav>
84	</footer>
85	```
86
87	* `<nav>` wraps every major group of links that help users navigate the site,
88	page, or process — don't wrap every incidental link list in a nav landmark;
89	excess landmarks make region navigation harder
90	* When multiple `<nav>` elements are present, every one needs an
91	understandable name so users can distinguish them: `aria-label="Primary"`,
92	`"Footer"`, `"On this page"` — do not include the role word ("Primary
93	navigation landmark" is redundant since the role is already exposed)
94	* Use `aria-labelledby` when a visible heading already names the region
95	* Use the same name for repeated navigation landmarks containing the same
96	links; use different names when landmarks serve different purposes
97	* Do not add redundant `role="navigation"` to `<nav>`
98
99	Missing `<nav>` landmark is Serious — screen reader users cannot jump to
100	navigation via the rotor or landmarks list.
101
102	---
103
104	## Critical: Skip Link
105
106	Must be at or near the beginning of the body, before the content it bypasses,
107	and must be one of the first useful keyboard stops (not necessarily the
108	literal first DOM node).

People who liked this also viewed

6 picks

Type

navigation

27stars2forks

View on GitHub

How to install navigation?

mgifford/accessibility-skills/navigation

$npx -y skills add mgifford/accessibility-skills --skill navigation

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Navigation Accessibility Skill
2
3	> Canonical source: `examples/NAVIGATION_ACCESSIBILITY_BEST_PRACTICES.md` in `mgifford/ACCESSIBILITY.md`
4	> This skill is derived from that file. When in doubt, the example is authoritative.
5
6	Apply these rules when creating or reviewing navigation patterns: primary nav,
7	dropdowns, breadcrumbs, pagination, mobile menus, and in-page navigation.
8	Only load this skill if the project contains navigation components.
9
10	---
11
12	## Core Mandate
13
14	Navigation must remain understandable and operable with keyboards, touch,
15	speech input, screen readers, screen magnification, text resizing, and
16	browser zoom. Screen reader users rely on landmark structure to orient
17	themselves; keyboard users rely on predictable tab order and dropdown
18	behaviour; voice control users rely on visible, correctly-labelled
19	interactive elements; magnification users rely on nav that reflows without
20	breaking. Get navigation wrong and everything downstream is harder.
21
22	---
23
24	## Severity Scale (this skill)
25
26	\| Level \| Meaning \|
27	\|---\|---\|
28	\| Critical \| Navigation completely unreachable or creates a keyboard trap \|
29	\| Serious \| Dropdown only works on hover; `role="menu"` misused; no `aria-current` \|
30	\| Moderate \| Missing `aria-label` on secondary nav; breadcrumb not labelled \|
31	\| Minor \| Nav item count exceeds 7; inconsistent `aria-expanded` update \|
32
33	Do not assign severity from the pattern alone — determine the actual effect
34	on navigation and task completion. Consider whether users can reach main
35	content, whether a menu can be opened/operated/closed/left, whether focus
36	becomes trapped or lost, and whether the defect affects every page through a
37	shared component (a shared nav trap can block an entire site).
38
39	---
40
41	## Assistive Technology Context
42
43	Navigation behaves differently across AT. Test with:
44
45	\| AT \| Browser \| Key behaviour \|
46	\|---\|---\|---\|
47	\| NVDA \| Chrome \| `H` key for headings, `R` for regions, list count announced on nav entry \|
48	\| JAWS \| Chrome \| `F6` for frames/regions, `Q` to move to main; announces nav landmark \|
49	\| VoiceOver \| Safari (macOS) \| `VO+U` rotor for landmarks and links; announces nav label \|
50	\| VoiceOver \| Safari (iOS) \| Swipe to navigate; nav landmark accessible via rotor \|
51	\| TalkBack \| Chrome (Android) \| Linear swipe navigation; landmarks via local context menu \|
52	\| 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 \|
53	\| Screen magnification \| Any \| Sticky/fixed navbars shrink the visible viewport at high zoom (200%, 400%) \|
54	\| Reader Mode \| Firefox/Edge/Safari \| Strips nav from the article view — acceptable; main content must make sense without it \|
55
56	Voice Control note: Dragon and iOS Voice Control navigate by speaking
57	visible link text. If `aria-label` differs from visible text, users cannot
58	activate the link by speaking what they see — **the accessible name must
59	contain the visible text** (WCAG 2.5.3 Label in Name).
60
61	---
62
63	## Critical: Landmark Structure
64
65	```html
66	<a class="skip-link" href="#main-content">Skip to main content</a>
67
68	<header>
69	<a href="/">Service name</a>
70	<nav aria-label="Primary">
71	<ul>
72	<li><a href="/services">Services</a></li>
73	<li><a href="/guidance">Guidance</a></li>
74	</ul>
75	</nav>
76	</header>
77
78	<main id="main-content" tabindex="-1">
79	<h1>Page title</h1>
80	</main>
81
82	<footer>
83	<nav aria-label="Footer">…</nav>
84	</footer>
85	```
86
87	* `<nav>` wraps every major group of links that help users navigate the site,
88	page, or process — don't wrap every incidental link list in a nav landmark;
89	excess landmarks make region navigation harder
90	* When multiple `<nav>` elements are present, every one needs an
91	understandable name so users can distinguish them: `aria-label="Primary"`,
92	`"Footer"`, `"On this page"` — do not include the role word ("Primary
93	navigation landmark" is redundant since the role is already exposed)
94	* Use `aria-labelledby` when a visible heading already names the region
95	* Use the same name for repeated navigation landmarks containing the same
96	links; use different names when landmarks serve different purposes
97	* Do not add redundant `role="navigation"` to `<nav>`
98
99	Missing `<nav>` landmark is Serious — screen reader users cannot jump to
100	navigation via the rotor or landmarks list.
101
102	---
103
104	## Critical: Skip Link
105
106	Must be at or near the beginning of the body, before the content it bypasses,
107	and must be one of the first useful keyboard stops (not necessarily the
108	literal first DOM node).

People who liked this also viewed

6 picks

Type