[islamhany528]

Problem:
The Notebook page only has one heading, the H1 "Notebook". The page-name groups (the ToggleDetails toggles) aren't marked up as headings. That means screen reader users can't jump between groups by heading. They have to go through every note card to find the notes for a page.

WCAG: 1.3.1 Info and Relationships (Level A)

Test Plan

Manual (docs app: pnpm run dev, ToggleDetails page, "Heading" example)

1. Heading markup: inspect the "Heading" example. The toggle button should sit inside an <h2>. Other examples should have no <h2>.
2. Variants: set asHeading on each combination and confirm the toggle is wrapped in an h2:
   • variant="default"
   • variant="filled"
   • href set
   • iconPosition="start" and iconPosition="end"
   • size small, medium and large
   • fluidWidth

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[Copilot]

🟡 Changes recommended

The added required heading style key is missing from generateStyle, causing a TypeScript error, and the unstyled h2 introduces spacing and typography regressions.

2 open issues

• Missing required heading style in generateStyle return value · New
• Reset heading wrapper margins and inherited typography · New

What changed in this PR

Adds an optional asHeading prop to ToggleDetails v2 so screen reader users can navigate toggle groups by heading.

Changes:

• Wraps default, filled, and link toggles in an h2 when enabled.
• Documents the prop with an interactive example.
• Adds tests for heading markup and unchanged default behavior.

File	Description
packages/​ui-toggle-details/​src/​ToggleDetails/​v2/​README.md	Documents asHeading with a heading example.
packages/​ui-toggle-details/​src/​ToggleDetails/​v2/​props.ts	Declares the prop and heading style key.
packages/​ui-toggle-details/​src/​ToggleDetails/​v2/​index.tsx	Conditionally wraps the toggle in an h2.
packages/​ui-toggle-details/​src/​ToggleDetails/​__tests__/​ToggleDetails.test.tsx	Tests default behavior and heading wrappers across variants.

_{Review effort: Balanced}

[github-actions]

PR Preview Action v1.8.2
🚀 View preview at https://instructure.design/pr-preview/pr-2771/
Built to branch gh-pages at 2026-10-30 08:19 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[matyasf]

I think this generally this change is OK (e.g. W3C recommends this pattern too -- https://www.w3.org/WAI/ARIA/apg/patterns/accordion/examples/accordion/ )

but since this is a library, we should make it customizable the heading level, for example the new prop should have a type 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' (and when the value is not set, it should not wrap stuff in a heading)

[matyasf]

Why just h2? This is a reusable component, others might need different heading value

[islamhany528]

Sure I will add more options to include not just h2