A11y: Fix MDX heading anchors not keyboard accessible

[TheSeydiCharyyev]

Description

Makes MDX heading anchors keyboard accessible by replacing the inaccessible styled anchor with a Button component.

Related Issue

Fixes #33240

Changes Made

• Replaced styled.a (OcticonAnchor) with Button asChild wrapping an <a> element for consistent styling and built-in accessibility
• Removed aria-hidden="true" and tabIndex={-1} so the anchor is reachable by keyboard and screen readers
• Added ariaLabel="Copy heading URL to address bar" which also provides an automatic tooltip on hover/focus
• Added &:focus-within svg style to show the link icon on keyboard focus (alongside existing :hover)
• Anchor remains an <a> with href so tocbot Table of Contents continues to work

How it works

• Button asChild uses Radix Slot to render an <a> element with button styles — visually a button, semantically a link
• ariaLabel on Button automatically creates a tooltip via InteractiveTooltipWrapper
• :focus-within on the heading container makes the SVG icon visible when the anchor inside receives keyboard focus

Manual testing

1. Open any MDX docs page with headings
2. Press Tab — anchor icons should become visible on focus
3. Tooltip "Copy heading URL to address bar" should appear on focus/hover
4. Enter navigates to the heading anchor
5. Hover still works as before

Checklist

• Linter passes (0 errors)
• Tested manually in sandbox

Summary by CodeRabbit

• New Features

  • Header icons now appear on both hover and keyboard focus, improving discoverability and keyboard navigation.

• Bug Fixes

  • Copy-heading control updated for more reliable activation and target validation; accessibility labels and visual behavior improved for keyboard and assistive‑tech users.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: f7087380-9cd0-4150-82c8-c770052925a9

📥 Commits

Reviewing files that changed from the base of the PR and between 837b786 and 97cb78f.

📒 Files selected for processing (1)

• code/addons/docs/src/blocks/blocks/mdx.tsx

---

📝 Walkthrough

Walkthrough

Refactors the MDX heading copy-link to a Button-wrapped anchor, makes the octicon visible on both :hover and :focus-within, and updates the click handler to call preventDefault(), verify the target element exists, then invoke navigate(context, hash).

Changes

MDX Heading Anchor

Layer / File(s)	Summary
Import, styling, wrapper, and click behavior code/addons/docs/src/blocks/blocks/mdx.tsx	Adds Button import; makes octicon SVG visible on :hover and :focus-within; introduces OcticonAnchorWrapper to adjust float/spacing and force nested a to color: inherit and no text-decoration; replaces the previous styled anchor with a Button (asChild) wrapping an a whose onClick preventDefault()s, checks document.getElementById(id), and calls navigate(context, hash) if found.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• UI: Fix trivial RefBlocks ARIA violations #33026 — Modifies anchor elements to function as button-like controls by changing semantics and click handling behavior, similar to the Button/anchor restructuring in this PR.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[TheSeydiCharyyev]

Synced the branch with the latest next — no conflicts, mdx.tsx wasn't touched upstream.

[Sidnioulz]

LGTM overall. Waiting for the Chromatic UI Test to finish before I approve :)

[TheSeydiCharyyev]

Pulled the commit and ran yarn task compile -s compile — compiles clean, no issues.

[Sidnioulz]

@TheSeydiCharyyev if you look at the UI Tests, you'll see there's a layout shift for titles. They have all moved to the right.

Could you please find a way to make sure there is no visual change for titles? Thanks.

You can ignore the failed Linux test, it's a flake. It should go away the next time CI runs.

[TheSeydiCharyyev]

Fixed — the anchor was floated, and the Button's padding widened it, which pushed the heading text to the right. It's now positioned absolutely in the left gutter, so the Button's dimensions no longer affect heading layout. Verified locally on an MDX page with headings — titles are flush-left with body text again.