anchor-links

# Anchor Links Accessibility Skill > **Canonical source**: `examples/ANCHOR_LINKS_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 in-page anchor links, skip links, or heading links. **Only load this skill if the project contains in-page navigation or skip links.** --- ## Core Mandate Every anchor link must have meaningful text, a reachable target with a visible focus indicator, and must not cause motion-related harm. Use a real `<a>` element with an `href` for navigation; use a button only for actions that don't navigate. Prefer native fragment navigation before adding JavaScript. --- ## Severity Scale (this skill) | Level | Meaning | |---|---| | **Critical** | Anchor navigation blocks access or causes a trap | | **Serious** | Skip link broken or permanently hidden; smooth scroll triggers vestibular harm | | **Moderate** | Focus indicator obscured by sticky header; link text ambiguous in context | | **Minor** | Non-slug IDs; missing `aria-current` in table of contents | --- ## Use Links for Navigation, Not Actions Use an anchor when activation changes the URL or navigates to a location; use a button when activation performs an action without navigation. ```html <!-- Navigation to a page fragment --> <a href="#installation">Installation instructions</a> <!-- An action --> <button type="button" id="copy-installation-link"...