docs(menu): expand accessibility guidance for AI codegen by purvas12 · Pull Request #4072 · Workday/canvas-kit

purvas12 · 2026-07-17T16:37:32Z

Summary

Restructure Menu accessibility docs to match the Dialog/FormField pattern with minimum structure, built-in behaviors, requirements, and anti-patterns for codegen.

Release Category

Components

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?

/modules/react/menu/stories/Menu.mdx

Areas for Feedback? (optional)

Code
Documentation
Testing
Codemods

Updated the accessibility section for the Menu component. PLease review the content for accuracy and clarity for AI code generation.

Testing Manually

Review the storybook page for Menu and ensure that the accessibility section renders correctly.

Restructure Menu accessibility docs to match the Dialog/FormField pattern with minimum structure, built-in behaviors, requirements, and anti-patterns for codegen. Co-authored-by: Cursor <cursoragent@cursor.com>

coderabbitai · 2026-07-17T16:37:44Z

Important

Review skipped

Draft detected.

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: aaf24bd4-a855-411e-bd6c-6a9847907791

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

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

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

cypress · 2026-07-17T16:46:17Z

Workday/canvas-kit Run #11271

Run Properties: Passed #11271 • 95781b7d42 ℹ️: Merge 299fc6436fb583e381983a2c28b30922887d2a11 into e97ce23f43709a2b63ae9c506c93...

Project	`Workday/canvas-kit`
Branch Review	`purva-a11y-doc-update-menu`
Run status	`Passed #11271`
Run duration	`02m 31s`
Commit	`95781b7d42 ℹ️: Merge 299fc6436fb583e381983a2c28b30922887d2a11 into e97ce23f43709a2b63ae9c506c93...`
Committer	`purvas12`
View all properties for this run ↗︎

Test results
Failures	`0`
Flaky	`0`
Pending	`17`
Skipped	`0`
Passing	`809`
View all changes introduced in this branch ↗︎

UI Coverage `19.52%`
Untested elements	`1540`
Tested elements	`371`

Accessibility `99.44%`
Failed rules	`5 critical` `5 serious` `0 moderate` `2 minor`
Failed elements	`68`

williamjstanton · 2026-07-17T21:06:07Z

+**`as={SecondaryButton}`**). Use **`React.forwardRef`** when the menu may open programmatically
+before the user activates the target.
+
+**Programmatic open without `Menu.Target`:**


I'm not sure I follow why we need this example. There's a bunch of things that fall off here if we don't use <Menu.Target> that normally supplies:

an id for <Menu.List> to reference aria-labelledby

aria-haspopup

aria-expanded

Down arrow key events to open the menu

The return focus target when menu is dismissed

I think we should remove this example. People can just use the as prop to customize the target to suit their needs. (E.g. as={PrimaryButton})

williamjstanton · 2026-07-17T21:13:35Z

+      <Menu.List>
+        <Menu.Item>First Item</Menu.Item>
+        <Menu.Item>Second Item</Menu.Item>
+        <Menu.Item aria-disabled>Unavailable Item</Menu.Item>


Let's take out aria-disabled from the minimum structure.

williamjstanton · 2026-07-17T21:23:55Z

+- Use native **`disabled`** (or deprecated **`isDisabled`**) instead of **`aria-disabled`** when
+  the item should remain discoverable
+- Skip **`data-text`** on static items whose accessible/filter text is not plain string children
+- Use a custom **`Menu.Target`** **`as`** component **without** **`forwardRef`** when the menu can


Either remove or consider revising in some way.

williamjstanton · 2026-07-17T21:28:46Z

+| When           | Default behavior                                                                                                                                     | Ask the developer before overriding                                                                                                                                                                      |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Menu **opens** | Focus moves to the **first menu item** by default via item focus hooks—not `useInitialFocus`. Omit **`initialFocusRef`**.                            | _Which item should receive focus when the menu opens?_ Prefer item order / `data-id` registration; do not assume **`initialFocusRef`** works on Menu.                                                     |
+| Menu **closes** | **`useReturnFocus`** moves focus to **`Menu.Target`**. Omit **`returnFocusRef`**.                                                                  | _Which element should receive focus when the menu closes?_ (When there is no **`Menu.Target`**, set **`returnFocusRef`** on **`useMenuModel({returnFocusRef})`**, or when return focus should land elsewhere.) |


Consider removing "When there is no Menu.Target ..."

williamjstanton · 2026-07-17T21:36:06Z

+| Complex item content / icons _(conditional)_             | For static API when children are not plain text, set **`data-text`** on **`Menu.Item`** so typeahead/filtering can resolve the item text. Decorative icons alongside **`Menu.Item.Text`** usually need no extra accessible name.                                             |
+| Groups _(conditional)_                                   | **`Menu.Group`** with **`title`** or **`Menu.Group.Heading`** so `role="group"` is labeled. Group headers are not keyboard-selectable.                                                                                                                                          |
+| Nested menus _(conditional)_                             | **`Menu.Submenu`** with **`Menu.Submenu.TargetItem`** plus **`Popper` / `Card` / `List` / `Item`**. Do not manually set submenu `aria-haspopup` / `aria-expanded`.                                                                                                             |
+| Multi-select menu _(conditional)_                        | `mode="multiple"` on the model when items should toggle selection without closing. Ask before changing from default `single`.                                                                                                                                                  |


Hang on, we can select multiple options in a menu? How do we toggle a selection state on a menu? The menu item role doesn't support aria-selected ...

This feels like it also contradicts the instructions 2 lines below: Use Select or Combobox for selectable options.

docs(menu): expand accessibility guidance for AI codegen

299fc64

Restructure Menu accessibility docs to match the Dialog/FormField pattern with minimum structure, built-in behaviors, requirements, and anti-patterns for codegen. Co-authored-by: Cursor <cursoragent@cursor.com>

purvas12 requested a review from williamjstanton July 17, 2026 16:37

williamjstanton requested changes Jul 17, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(menu): expand accessibility guidance for AI codegen#4072

docs(menu): expand accessibility guidance for AI codegen#4072
purvas12 wants to merge 1 commit into
Workday:a11yfrom
purvas12:purva-a11y-doc-update-menu

purvas12 commented Jul 17, 2026

Uh oh!

coderabbitai Bot commented Jul 17, 2026

Review skipped

Uh oh!

cypress Bot commented Jul 17, 2026

Uh oh!

williamjstanton Jul 17, 2026

Uh oh!

williamjstanton Jul 17, 2026

Uh oh!

williamjstanton Jul 17, 2026

Uh oh!

williamjstanton Jul 17, 2026

Uh oh!

williamjstanton Jul 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

purvas12 commented Jul 17, 2026

Summary

Release Category

Checklist

For the Reviewer

Where Should the Reviewer Start?

Areas for Feedback? (optional)

Testing Manually

Uh oh!

coderabbitai Bot commented Jul 17, 2026

Review skipped

Uh oh!

cypress Bot commented Jul 17, 2026

Workday/canvas-kit Run #11271

Uh oh!

williamjstanton Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

williamjstanton Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

williamjstanton Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

williamjstanton Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

williamjstanton Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants