anchor-links

Name: anchor-links
Author: mgifford

39installs2forks

How to install anchor-links?

mgifford/accessibility-skills/anchor-links

$npx -y skills add mgifford/accessibility-skills --skill anchor-links

Installs into the current project.

Summary

Load this skill whenever the project contains in-page anchor links, skip links, fragment identifiers, or heading links. Under no circumstances omit accessible anchor-link requirements when such links exist. Ensure every anchor link has meaningful text, a reachable target, and a v

Files · 1

View on GitHub

SKILL.md

1	# Anchor Links Accessibility Skill
2
3	> Canonical source: `examples/ANCHOR_LINKS_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 in-page anchor links, skip links, or heading links.
7	Only load this skill if the project contains in-page navigation or skip links.
8
9	---
10
11	## Core Mandate
12
13	Every anchor link must have meaningful text, a reachable target with a visible
14	focus indicator, and must not cause motion-related harm. Use a real `<a>`
15	element with an `href` for navigation; use a button only for actions that
16	don't navigate. Prefer native fragment navigation before adding JavaScript.
17
18	---
19
20	## Severity Scale (this skill)
21
22	\| Level \| Meaning \|
23	\|---\|---\|
24	\| Critical \| Anchor navigation blocks access or causes a trap \|
25	\| Serious \| Skip link broken or permanently hidden; smooth scroll triggers vestibular harm \|
26	\| Moderate \| Focus indicator obscured by sticky header; link text ambiguous in context \|
27	\| Minor \| Non-slug IDs; missing `aria-current` in table of contents \|
28
29	---
30
31	## Use Links for Navigation, Not Actions
32
33	Use an anchor when activation changes the URL or navigates to a location; use
34	a button when activation performs an action without navigation.
35
36	```html
37	<!-- Navigation to a page fragment -->
38	<a href="#installation">Installation instructions</a>
39
40	<!-- An action -->
41	<button type="button" id="copy-installation-link">Copy link to Installation</button>
42	```
43
44	Do not use dummy links for actions:
45
46	```html
47	<!-- Do not use these for actions -->
48	<a href="#">Open settings</a>
49	<a href="javascript:void(0)">Open settings</a>
50	```
51
52	An empty fragment navigates to the top of the document; a JavaScript URL loses
53	ordinary link semantics (history, copying, opening in a new tab, no-script
54	fallback). Do not add `role="link"` to a native anchor with `href` — the role
55	is already provided.
56
57	---
58
59	## Serious: Meaningful Link Text
60
61	WCAG 2.4.4 requires a link's purpose be determinable from its text alone or
62	text plus programmatically determined context — understanding every link
63	without any context is the stronger Level AAA criterion (2.4.9), still a
64	useful goal.
65
66	```html
67	<!-- Prefer -->
68	<a href="#installation">Installation instructions</a>
69	<a href="#wcag-criteria">Relevant WCAG success criteria</a>
70
71	<!-- Avoid when clearer wording is available -->
72	<a href="#section">Click here</a>
73	<a href="#section">Read more</a>
74	```
75
76	"Read more" is not automatically a Level A failure when programmatically
77	determined context supplies the purpose, but clearer text is easier to scan,
78	translate, and operate by speech. If a design must retain repeated visible
79	text, add hidden context inside the link rather than replacing it:
80
81	```html
82	<a href="#keyboard-testing">
83	Read more<span class="visually-hidden"> about keyboard testing</span>
84	</a>
85	```
86
87	Do not use `aria-label` to replace useful visible text with a different name
88	— the accessible name should contain the visible words (supports speech input
89	and WCAG 2.5.3 Label in Name). For icon-only links, "Link to" is redundant —
90	screen readers already announce the role:
91
92	```html
93	<a href="#installation" aria-label="Installation section">
94	<svg aria-hidden="true" focusable="false"><!-- anchor icon --></svg>
95	</a>
96	```
97
98	Links with the same purpose/destination should use consistent names; links
99	with the same text but different destinations need enough context to
100	distinguish them.
101
102	---
103
104	## Serious: Fragment Targets Must Be Unique, Visible, and Stable
105
106	The fragment after `#` must resolve to a unique `id` within the document; IDs
107	must not contain ASCII whitespace.
108
109	```html
110	<nav aria-label="On this page"><a href="#installation">Installation</a></nav>
111	<h2 id="installation">Installation</h2>
112	```
113
114	Do not target: an element with `hidden`/`display:none`/`visibility:hidden`;
115	content inside a closed disclosure; an inactive tab panel; an empty marker far
116	from the visible heading; or an element removed during hydration. If a deep
117	link points into collapsed or tabbed content, reveal the container before
118	scrolling or moving focus.
119
120	Keep published IDs stable: preserve an existing ID when the destination is
121	conceptually the same; provide an alias/redirect strategy when an ID must
122	change; don't regenerate every ID just because heading text/capitalization
123	changed. Generated slug systems must resolve duplicate headings deterministically
124	and produce the same ID during server rendering and client hydration.
125
126	---
127
128	## Serious: Skip Link
129
130	Must be the first focus

People who liked this also viewed

6 picks

Type

anchor-links

39installs2forks

View on GitHub

How to install anchor-links?

mgifford/accessibility-skills/anchor-links

$npx -y skills add mgifford/accessibility-skills --skill anchor-links

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Anchor Links Accessibility Skill
2
3	> Canonical source: `examples/ANCHOR_LINKS_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 in-page anchor links, skip links, or heading links.
7	Only load this skill if the project contains in-page navigation or skip links.
8
9	---
10
11	## Core Mandate
12
13	Every anchor link must have meaningful text, a reachable target with a visible
14	focus indicator, and must not cause motion-related harm. Use a real `<a>`
15	element with an `href` for navigation; use a button only for actions that
16	don't navigate. Prefer native fragment navigation before adding JavaScript.
17
18	---
19
20	## Severity Scale (this skill)
21
22	\| Level \| Meaning \|
23	\|---\|---\|
24	\| Critical \| Anchor navigation blocks access or causes a trap \|
25	\| Serious \| Skip link broken or permanently hidden; smooth scroll triggers vestibular harm \|
26	\| Moderate \| Focus indicator obscured by sticky header; link text ambiguous in context \|
27	\| Minor \| Non-slug IDs; missing `aria-current` in table of contents \|
28
29	---
30
31	## Use Links for Navigation, Not Actions
32
33	Use an anchor when activation changes the URL or navigates to a location; use
34	a button when activation performs an action without navigation.
35
36	```html
37	<!-- Navigation to a page fragment -->
38	<a href="#installation">Installation instructions</a>
39
40	<!-- An action -->
41	<button type="button" id="copy-installation-link">Copy link to Installation</button>
42	```
43
44	Do not use dummy links for actions:
45
46	```html
47	<!-- Do not use these for actions -->
48	<a href="#">Open settings</a>
49	<a href="javascript:void(0)">Open settings</a>
50	```
51
52	An empty fragment navigates to the top of the document; a JavaScript URL loses
53	ordinary link semantics (history, copying, opening in a new tab, no-script
54	fallback). Do not add `role="link"` to a native anchor with `href` — the role
55	is already provided.
56
57	---
58
59	## Serious: Meaningful Link Text
60
61	WCAG 2.4.4 requires a link's purpose be determinable from its text alone or
62	text plus programmatically determined context — understanding every link
63	without any context is the stronger Level AAA criterion (2.4.9), still a
64	useful goal.
65
66	```html
67	<!-- Prefer -->
68	<a href="#installation">Installation instructions</a>
69	<a href="#wcag-criteria">Relevant WCAG success criteria</a>
70
71	<!-- Avoid when clearer wording is available -->
72	<a href="#section">Click here</a>
73	<a href="#section">Read more</a>
74	```
75
76	"Read more" is not automatically a Level A failure when programmatically
77	determined context supplies the purpose, but clearer text is easier to scan,
78	translate, and operate by speech. If a design must retain repeated visible
79	text, add hidden context inside the link rather than replacing it:
80
81	```html
82	<a href="#keyboard-testing">
83	Read more<span class="visually-hidden"> about keyboard testing</span>
84	</a>
85	```
86
87	Do not use `aria-label` to replace useful visible text with a different name
88	— the accessible name should contain the visible words (supports speech input
89	and WCAG 2.5.3 Label in Name). For icon-only links, "Link to" is redundant —
90	screen readers already announce the role:
91
92	```html
93	<a href="#installation" aria-label="Installation section">
94	<svg aria-hidden="true" focusable="false"><!-- anchor icon --></svg>
95	</a>
96	```
97
98	Links with the same purpose/destination should use consistent names; links
99	with the same text but different destinations need enough context to
100	distinguish them.
101
102	---
103
104	## Serious: Fragment Targets Must Be Unique, Visible, and Stable
105
106	The fragment after `#` must resolve to a unique `id` within the document; IDs
107	must not contain ASCII whitespace.
108
109	```html
110	<nav aria-label="On this page"><a href="#installation">Installation</a></nav>
111	<h2 id="installation">Installation</h2>
112	```
113
114	Do not target: an element with `hidden`/`display:none`/`visibility:hidden`;
115	content inside a closed disclosure; an inactive tab panel; an empty marker far
116	from the visible heading; or an element removed during hydration. If a deep
117	link points into collapsed or tabbed content, reveal the container before
118	scrolling or moving focus.
119
120	Keep published IDs stable: preserve an existing ID when the destination is
121	conceptually the same; provide an alias/redirect strategy when an ID must
122	change; don't regenerate every ID just because heading text/capitalization
123	changed. Generated slug systems must resolve duplicate headings deterministically
124	and produce the same ID during server rendering and client hydration.
125
126	---
127
128	## Serious: Skip Link
129
130	Must be the first focus

People who liked this also viewed

6 picks

Type