docs: Expand Modal, Popup, and Dialog accessibility for AI codegen

[williamjstanton]

Summary

Expands and aligns Accessibility documentation for Modal, Popup, and Dialog to the AI-codegen template (minimum structure, built-in behaviors, requirements, anti-patterns), so agents and consumers get consistent, accurate guidance across the popup family.

• Modal — Full accessibility section for the blocking dialog pattern (focus trap, assistive sibling hiding, overflow/scroll, accept-only dismiss).
• Popup — Full accessibility section for compose-your-own hooks (usePopupModel + behavior hooks), including reading-order/aria-owns DIY and when to prefer Dialog or Modal.
• Dialog — Aligns shared guidance with Modal/Popup (min structure, Custom Target, open-focus patterns, ARIA/DOM depth) while keeping non-modal-only rules (aria-owns, useFocusRedirect, conditional aria-expanded).

Cross-component polish after review:

• Shared Custom Target / focus-default / open-focus-below wording and cross-links
• Modal treats aria-expanded / aria-haspopup as an anti-pattern (non-modal only)
• Input labeling left to FormField / input docs (not duplicated as a popup-family requirement)
• APG modal dialog pattern cited for Modal; Dialog/Popup point to Modal for that pattern

Release Category

Documentation

---

Checklist

• MDX documentation adheres to Canvas Kit's Documentation Guidelines
• Label ready for review has been added to PR

For the Reviewer

• PR title is short and descriptive
• PR summary describes the change (Fixes/Resolves linked correctly)
• PR Release Notes describes additional information useful to call out in a release message or removed if not applicable
• Breaking Changes provides useful information to upgrade to this code or removed if not applicable

Where Should the Reviewer Start?

1. modules/react/modal/stories/Modal.mdx — ## Accessibility (canonical modal / blocking pattern)
2. modules/react/popup/stories/Popup.mdx — ## Accessibility (compose hooks; prefer Dialog/Modal first)
3. modules/react/dialog/stories/Dialog.mdx — ## Accessibility (non-modal; confirm shared vs modal-only deltas)

Areas for Feedback? (optional)

• Code
• Documentation
• Testing
• Codemods

Focus on:

• Accuracy of built-in behaviors vs hooks/subcomponents (especially Modal aria-modal="false" and Popup “hooks not auto-applied”)
• Whether Dialog/Popup aria-expanded guidance and Modal’s anti-pattern are clear enough for codegen
• Cross-links between the three pages and Inline Popups / Return Focus / Initial Focus

Testing Manually

1. Run Storybook (yarn start) and open:
   • Components > Popups > Modal → Accessibility
   • Components > Popups > Popup → Accessibility
   • Components > Popups > Dialog → Accessibility
2. Confirm headings, tables, code samples, and internal/external links render.
3. Spot-check that min-structure snippets match each component’s Basic Example composition (Overlay/Popper/ButtonGroup, hook composition on Popup).

Screenshots or GIFs (if applicable)

N/A — documentation only.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

🗂️ Base branches to auto review (3)

• support
• prerelease/minor
• prerelease/major

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: ca27caad-886e-449c-b6b7-3920faf51e8f

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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.}