In-page anchor navigation

Problem Context

• The page is long enough that scanning headings alone is inefficient.
• The content is one coherent page rather than a set of separate pages or transaction steps.
• Users may arrive with a specific section in mind and need a quick way to reach it.

Selection Rules

• Choose in-page anchor navigation when one page has several meaningful sections, usually at least two H2-level destinations and enough length to justify jump links.
• Use only headings or major section destinations on the current page; do not mix external pages, account actions, or local hierarchy pages into the list.
• Keep link labels short, descriptive, and aligned with the destination headings so users can predict the target.
• Move focus to the target heading after activation or ensure the destination is programmatically clear.
• Highlight the current section when the navigation is sticky or when users may lose track during scrolling.
• Avoid in-page anchor navigation on short pages where the list would duplicate visible headings without reducing effort.
• Use side navigation for related pages in a section, breadcrumbs for parent hierarchy, and Back links for transaction return.

Required States

• Default state with a labelled same-page navigation list near or beside long content.
• Active section state that matches the heading currently reached or visible.
• Hash-linked or deep-linked state where the correct section is indicated on load.
• Keyboard activation state where focus lands on or near the destination heading.
• Sticky or scrolling state where active section updates as the viewport changes.
• Short-page or insufficient-heading state where the component is omitted.

Interaction Contract

• Activating an anchor link navigates within the current page to the matching section target.
• The destination heading text and anchor link label remain aligned enough for users to confirm they arrived at the expected section.
• Keyboard focus moves to the destination heading or the section receives an equivalent focus target after activation.
• The URL hash, active link, and visible section do not contradict each other.
• Sticky versions update current-section state as users scroll and do not cover the target heading.
• The anchor list remains separate from breadcrumbs, side navigation, global navigation, and page actions.

Implementation Checklist

• Identify the page's major H2 sections and decide whether there is enough content to justify jump links.
• Use a labelled navigation landmark such as 'On this page' or 'Page contents'.
• Generate or maintain anchor hrefs from stable heading IDs and keep labels synchronized with heading text.
• Set scroll-margin or equivalent offset so sticky headers do not hide destination headings.
• Move focus to the destination heading on activation, or make the destination focusable with tabindex when needed.
• Update active state from hash changes and scrolling when the component is sticky.
• Test keyboard, screen-reader, reduced-motion, and narrow-screen behavior.

Common Generated-UI Mistakes

• Using in-page anchors as a substitute for side navigation across different pages.
• Adding a contents list to a short page where all headings are already visible.
• Letting anchor labels drift from destination headings.
• Changing the visible section without moving keyboard focus or active state.
• Mixing same-page anchors with external links, global navigation, or account actions.
• Letting sticky headers cover the target heading after a jump.

Critique Questions

• Is this one long page, or are these actually separate pages that need side navigation or pagination?
• Do anchor labels match the headings users will see after activation?
• What receives focus after a keyboard user activates a jump link?
• Does the component disappear on short pages or when there are too few meaningful headings?
• Can a shared hash URL open the page with the right section and active state?