@workday/canvas-kit-docs 16.0.10 → 16.0.12

package/dist/mdx/react/form-field/FormField.mdx

@@ -1,20 +1,21 @@
 import {ExampleCodeBlock, Specifications, SymbolDoc} from '@workday/canvas-kit-docs';
+
+import AllFields from './examples/AllFields';
 import Basic from './examples/Basic';
 import Caution from './examples/Caution';
-import Error from './examples/Error';
+import Custom from './examples/Custom';
+import CustomId from './examples/CustomId';
 import Disabled from './examples/Disabled';
+import Error from './examples/Error';
+import GroupedInputs from './examples/GroupedInputs';
+import Grow from './examples/Grow';
 import HiddenLabel from './examples/HiddenLabel';
-import LabelPositionHorizontalStart from './examples/LabelPositionHorizontalStart';
+import Hint from './examples/Hint';
 import LabelPositionHorizontalEnd from './examples/LabelPositionHorizontalEnd';
+import LabelPositionHorizontalStart from './examples/LabelPositionHorizontalStart';
 import RefForwarding from './examples/RefForwarding';
 import Required from './examples/Required';
-import Custom from './examples/Custom';
-import CustomId from './examples/CustomId';
-import AllFields from './examples/AllFields';
-import Hint from './examples/Hint';
-import Grow from './examples/Grow';
 import ThemedError from './examples/ThemedErrors';
-import GroupedInputs from './examples/GroupedInputs';
 
 
 # Canvas Kit Form Field
@@ -134,14 +135,16 @@ for required fields are suffixed by a red asterisk.
 ### Grouped Inputs
 
 Use `FormFieldGroup` when you have a group of inputs that need to be associated to one another, like
-`RadioGroup` or a group of `Checkbox`'s. `FormFieldGroup` renders a `fieldset` element and
-`FormFieldGroup.Label` renders a `legend` element. These elements will allow screen readers to
-automatically announce the legend's context when focusing on the inputs in the group.
+`RadioGroup` or a group of `Checkbox`'s. `FormFieldGroup` renders a `div` with `role="group"` and an
+`aria-labelledby` reference. `FormFieldGroup.Label` renders a `div` with an `id` referenced by the
+`aria-labelledby` of the `FormFieldGroup`. Screen readers announce the group label when focusing
+controls in the group.
 
 `FormFieldGroup` supports the same props of `FormField`:
 
 - `error`: `"caution" | "error"` Defines the error around the whole group of inputs.
-- `orientation`: `"horizontal" | "vertical"` Defines the legend placement.
+- `orientation`: `"vertical" | "horizontalStart" | "horizontalEnd"` Defines the group label
+  placement.
 - `isRequired`: `true` Defines if a group like RadioGroup is required.
 
 <ExampleCodeBlock code={GroupedInputs} />
@@ -149,7 +152,7 @@ automatically announce the legend's context when focusing on the inputs in the g
 > **Accessibility Note**: In addition to radio button and checkbox groups, `FormFieldGroup` can be
 > useful in any situation where the form needs to have multiple sets of identical input fields. For
 > example, a form with identical fields for a Shipping address and a Billing address. The legend
-> provides critical context for screen reader users in these situations.
+> (group label) provides critical context for screen reader users in these situations.
 
 ### Custom
 
@@ -200,21 +203,70 @@ check our
 
 ## Accessibility
 
-`FormField` provides essential accessibility features to ensure form inputs are properly labeled and
-described for all users, including those using assistive technologies. This section covers both the
-technical implementation and best practices for creating accessible forms.
+`FormField` provides essential accessibility features to ensure form inputs have a programmatically
+determinable name, relationships, and instructions. The primary accessibility goal is to ensure
+assistive technology users can identify every field, understand how to complete it, and hear hints,
+errors, and required state when the form input receives focus.
+
+### Minimum Accessible Structure
 
-### Label Association
+```tsx
+import {FormField} from '@workday/canvas-kit-react/form-field';
+import {TextInput} from '@workday/canvas-kit-react/text-input';
 
-The `FormField` adds a `for` attribute to the `FormField.Label` (`<label>` element) element that
-matches the `id` attribute of the `FormField.Input` which is usually a `input` element. This both
-labels the input for screen readers and other assistive technology as well as will focus on the
-input when the user clicks on the label. If your form field input component is more complicated, the
-`FormField` will also add an `id` to the `FormField.Label` and an `aria-labelledby` to the
-`FormField.Input` component. You can then forward the `aria-labelledby` to whatever elements you
-need for the proper accessibility.
+<FormField>
+  <FormField.Label>Email</FormField.Label>
+  <FormField.Field>
+    <FormField.Input as={TextInput} />
+    <FormField.Hint>We'll never share your email.</FormField.Hint>
+  </FormField.Field>
+</FormField>;
+```
+
+Include **`FormField.Hint`** whenever there is hint or error text—the wiring slot for
+`aria-describedby` exists by default (see **Built-in Behaviors**).
+
+### Built-in Behaviors
+
+Canvas Kit applies these automatically when you compose `FormField` with its subcomponents. **Do not
+duplicate them** in consuming code.
+
+**ARIA and DOM** (_applied by subcomponents_):
+
+- `FormField.Label`: `<label>` with `htmlFor` matching the `id` on `FormField.Input` (`input-{id}`).
+  Clicking the label moves focus to the input.
+- `FormField.Input`: `id` (`input-{id}`), `aria-labelledby` (`label-{id}`), `aria-describedby`
+  (`hint-{id}` when an `id` exists), `required` when `isRequired`, and `aria-invalid="true"` when
+  `error="error"`. Caution (`error="caution"`) does **not** set `aria-invalid`.
+- `FormField.Hint`: `id="hint-{id}"` for description association.
+- Generated IDs: `label-{id}`, `input-{id}`, and `hint-{id}` from the `FormField` `id`
+  (auto-generated or custom via the `id` prop).
+- `FormFieldGroup`: `role="group"` with `aria-labelledby` referencing `FormFieldGroup.Label`.
+- Composite controls (for example, `MultiSelect`) forward `aria-labelledby` to related sub-elements
+  (combobox, listbox) so every part shares the same accessible name.
+
+**Implementation note on `aria-describedby`:** `FormField.Input` always sets
+`aria-describedby="hint-{id}"` when an `id` exists, even if `FormField.Hint` is not rendered. Always
+render `FormField.Hint` when there is hint or error text. Omitting `FormField.Hint` leaves a
+dangling `aria-describedby` reference.
+
+**Keyboard** (_standard form control behavior_):
+
+- <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> move focus to and from the input (native tab
+  order)
+- Clicking `FormField.Label` moves focus to the associated input (native `<label>` behavior)
+- Checkbox, radio, and composite controls follow the wrapped input component's own keyboard patterns
 
-For example, the DOM will look something like this:
+**Screen reader expectations** (_when built-in behaviors are used as intended_):
+
+- On focus, assistive technology announces the field label and, when applicable: required state,
+  invalid state (`error="error"`), and hint or error text via `aria-describedby`
+- The Caution state is visual only —`aria-invalid` is **not** set for `error="caution"`
+- In a `FormFieldGroup`, the group label is associated via `aria-labelledby`; focusing a control in
+  the group includes the group name in context
+- Disabled inputs are skipped in the tab order and may be announced as unavailable
+
+For a simple field, the DOM looks like:
 
 ```html
 <div>
@@ -223,38 +275,115 @@ For example, the DOM will look something like this:
 </div>
 ```
 
-Some components, like `MultiSelect`, have an additional `role=listbox` element that also needs to
-link to the `label` element. The resulting DOM will look something like:
+Some composite controls such as `MultiSelect`, have additional sub-elements that also need to be
+linked to the `FormField.Label`. In the example below, the FormField.Label is applied to both the
+`input[role=combobox]` element and the `ul[role=listbox]` element so that screen reader knows that
+the label for both is the "States you've lived in".
 
 ```html
 <div>
   <label id="label-abc" for="input-abc">States you've lived in</label>
-  <input id="input-abc" aria-labelledby="label-abc" role="combobox" ... />
-  <ul role="listbox" aria-labelledby="label-abc">
-    <li>Texas</li>
-    <li>California</li>
+  <input
+    id="input-abc"
+    aria-labelledby="label-abc"
+    role="combobox"
+    aria-expanded="false"
+    aria-autocomplete="list"
+    aria-controls="listbox-abc"
+    type="text"
+  />
+  <ul id="listbox-abc" role="listbox" aria-labelledby="label-abc">
+    <li role="option">Texas</li>
+    <li role="option">California</li>
   </ul>
 </div>
 ```
 
-The `MultiSelect` component gets the `aria-labelledby` from the `FormField.Input` and forwards it to
-both the `input[role=combobox]` element and the `ul[role=listbox]` element so the screen reader
-knows the label for both is "States you've lived in".
+For a field in an error state, the error text is referenced using `aria-describedby`. The rendered
+markup looks like:
 
-### Label Text Best Practices
+```html
+<div>
+  <label id="label-abc" for="input-abc">Password</label>
+  <input
+    id="input-abc"
+    aria-labelledby="label-abc"
+    aria-describedby="hint-abc"
+    required
+    aria-invalid="true"
+  />
+  <p id="hint-abc">Error: Must contain a number and a capital letter</p>
+</div>
+```
 
-- **Be Clear and Concise**: Labels should clearly describe the purpose of the input field.
-- **Use Visible Labels Instead of Only Placeholders**: Always provide a persistent and accessible
-  label with `FormField.Label`. Do not rely solely on placeholder text, as it can disappear while
-  typing and may not be accessible to assistive technologies. Use the `isHidden` prop on
-  `FormField.Label` if a hidden label is required for visual design.
+For grouped checkbox controls, compose a `FormFieldGroup` with `FormFieldGroup.Label` and
+`FormFieldGroup.Input`. The rendered markup looks like:
 
-### Screen Reader Experience
+```html
+<div role="group" aria-labelledby="label-abc">
+  <div id="label-abc">Pizza toppings:</div>
+  <div>
+    <input type="checkbox" id="checkbox-1" />
+    <label for="checkbox-1">Pepperoni</label>
+  </div>
+  <div>
+    <input type="checkbox" id="checkbox-2" />
+    <label for="checkbox-2">Mushrooms</label>
+  </div>
+  <div>
+    <input type="checkbox" id="checkbox-3" />
+    <label for="checkbox-3">Pineapple</label>
+  </div>
+</div>
+```
 
-- The label is announced when the input receives focus.
-- Required, disabled, and invalid statuses are announced automatically.
-- Help text and error messages are announced automatically when focused.
-- For grouped inputs, the group label (`legend`) is announced automatically when focused.
+### Accessibility Requirements
+
+Required in application code for accessible form fields. Rows marked _(conditional)_ apply only when
+the situation matches—otherwise omit.
+
+**If no design spec is provided:** use a visible `FormField.Label`, wrap the input with
+`FormField.Input`, omit `isHidden`, and omit a custom `id` unless testing or composition requires
+it.
+
+| Requirement                        | How to satisfy                                                                                                                                                                               |
+| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Visible label                      | **`FormField.Label`** with concise, meaningful text                                                                                                                                          |
+| Input wiring                       | **`FormField.Input as={...}`** wrapping every Canvas Kit input (`TextInput`, `Select`, `TextArea`, etc.)                                                                                     |
+| Hint or error text _(conditional)_ | **`FormField.Hint`** when there is help or validation copy—required because `aria-describedby` is wired by default (see **Built-in Behaviors**)                                              |
+| Error state _(conditional)_        | `error="error"` on **`FormField`** and **`FormField.Hint`** prefixed with "Error:" so users who cannot perceive color can distinguish errors from hints                                      |
+| Caution state _(conditional)_      | `error="caution"` on **`FormField`** with descriptive **`FormField.Hint`** (no `aria-invalid`)                                                                                               |
+| Required field _(conditional)_     | `isRequired` on **`FormField`**; consider a form-level note that asterisk (\*) marks required fields                                                                                         |
+| Group label _(conditional)_        | **`FormFieldGroup`** + **`FormFieldGroup.Label`** for radio buttons, checkbox groups, or related inputs. Alternatively, **`FormField as="fieldset"`** with **`FormField.Label as="legend"`** |
+| Hidden label _(conditional)_       | **`FormField.Label isHidden`** only when an equally clear alternative exists (for example, a universally recognizable search icon)                                                           |
+| Stable IDs _(conditional)_         | `id` prop on **`FormField`** when multiple fields share a page or predictable `label-`, `input-`, and `hint-` IDs are needed for testing or custom composition                               |
+
+**Summary for code generation:**
+
+- **REQUIRED:** visible label, input wiring
+- **CONDITIONAL:** hint/error text, required state, group label, hidden label, stable `id`
+
+### Anti-Patterns
+
+Do **not** generate code that does the following (see **Accessibility Requirements** above for what
+to supply instead):
+
+- Manually set `id`, `htmlFor`, `aria-labelledby`, `aria-describedby`, `aria-invalid`, or `required`
+  on **`FormField.Input`** or **`FormField.Label`** — Canvas Kit subcomponents wire these
+  automatically
+- **Unlabeled inputs**: Do not use Canvas Kit inputs without `FormField` and `FormField.Label`.
+- **Placeholder-only labels**: Do not rely on `placeholder` instead of `FormField.Label`;
+  placeholders disappear while typing and are poor substitutes for labels.
+- **Color-only errors**: Do not set `error="error"` without descriptive text in `FormField.Hint`.
+- **Caution for invalid values**: Do not use `error="caution"` when a value is invalid; use
+  `error="error"` so `aria-invalid` is exposed.
+- **Broken ID references**: Do not point `aria-labelledby` or `aria-describedby` at missing or empty
+  elements; ensure `FormField.Label` and `FormField.Hint` render meaningful content.
+- **Skipping group labels**: Do not render `RadioGroup` or multiple related checkboxes without
+  `FormFieldGroup` and `FormFieldGroup.Label` (or `FormField` with `as="fieldset"` and
+  `FormField.Label as="legend"`).
+- **Disabled when read-only fits**: Avoid `disabled` on `FormField.Input` when users only need to
+  view data; disabled fields are harder to perceive and are removed from the tab order.
 
 ## Component API
 

package/dist/mdx/react/menu/Menu.mdx

@@ -31,7 +31,7 @@ yarn add @workday/canvas-kit-react
 
 <ExampleCodeBlock code={Basic} />
 
-`Menu` will automatically focus on the cursor item (first item by default). The `Menu` uses a menu
+`Menu` will automatically move focus to the first menu item when it opens. The `Menu` uses a menu
 model which composes a list model and a popup model and sets up accessibility features for you.
 
 > **Note:** When content exceeds `60vh`, the menu content is clipped and the menu becomes scrollable.
@@ -99,9 +99,9 @@ indicate this dual role.
 
 <ExampleCodeBlock code={Nested} />
 
-> **Accessibility Note**: When a menu item has an attached submenu, the `<Menu.Submenu.TargetItem>`
-> includes `aria-haspopup="true"` and `aria-expanded={true | false}` properties. These properties
-> will alert screen reader users to the available submenu systems.
+> **Accessibility Note**: Canvas Kit applies `aria-haspopup` and `aria-expanded` on
+> **`Menu.Submenu.TargetItem`** automatically. Do not set these manually — see
+> [Accessibility](#accessibility).
 
 ### Nested Dynamic Items
 
@@ -115,45 +115,190 @@ submenus.
 
 ## Accessibility
 
-Our Menu component is based on the Menu Button pattern on the ARIA Authoring Practices Guide from
-the W3C and relies on the roving tabindex technique for managing focus within the opened menu. This
-means that the minimum requirements for screen reader support and keyboard navigation are included
-in the component.
-
-[Menu Button Pattern | APG | WAI | W3C](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/)
-
-- The `<Menu.Target>` sub-component uses `aria-haspopup="true"` and `aria-expanded={true | false}`
-  properties. This benefits screen reader users by indicating when a button element has an attached
-  menu.
-- The `<Menu.List>` sub-component uses `role="menu"` and `<Menu.Item>` uses `role="menuitem"` ARIA
-  roles. These roles allow screen readers to pass through arrow key events to the web application.
-- The `<Menu.List>` sub-component includes an `aria-labelledby` ID reference to the `<Menu.Target>`
-  sub-component. This assigns a label to the menu for context.
-
-### Navigation
-
-- **Enter or Space**: When focused on the menu button, opens the menu and moves focus to the first
-  menu item. When focused on a menu item, activates the item and closes the menu
-- **Escape**: Closes the menu and returns focus to the menu button
-- **Up & Down Arrow**: Moves focus up and down the menu items
-- **Home & End**: Moves focus to the first or last menu item
-- **Right & Left Arrow**: When focused on a menu item with a submenu, opens the submenu and moves
-  focus to the first item in the submenu or closes the submenu and returns focus to the parent menu
-  item
-
-### Screen Reader Experience
-
-- The menu button will be announced with its label text followed by the button role, a notification
-  that it has a popup menu, and the current state of the menu (For example: "Actions, button, menu
-  popup, collapsed")
-- **Opening the Menu:** When the menu button is activated, screen readers will announce the menu
-  opening, the number of menu items available, and the currently focused item (For example:
-  "Actions, menu, First Action, menu item, 1 of 4.")
-- **Navigating Menu Items:** As focus moves between menu items, screen readers will announce the
-  item name and its position in the list (For example: "Second Action, menu item, 2 of 4.")
-- **Menu Items with Submenus:** When focused on a menu item that has a submenu, screen readers will
-  announce that it has a submenu and provide the expanded/collapsed state (For example: "More
-  Actions, menu item, has submenu, collapsed, 3 of 4.")
+`Menu` follows the
+[Menu Button Pattern | APG | WAI | W3C](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/), which
+has two parts with different accessibility jobs.
+
+**Menu button** (`Menu.Target`): a focusable control that opens and closes the menu. It exposes
+popup presence and expanded/collapsed state (`aria-haspopup`, `aria-expanded`), and receives focus
+again when the menu is dismissed.
+
+**Menu popup** (`Menu.List` and its items): the floating action list. It uses `role="menu"` /
+`role="menuitem"`, is labeled by the button, and manages focus inside the list with **roving
+tabindex** so users can move between items and activate one.
+
+Use **Menu** for action lists opened from a control. Prefer
+[**Select**](https://workday.github.io/canvas-kit/?path=/docs/components-inputs-select--docs) or
+[**Combobox**](https://workday.github.io/canvas-kit/?path=/docs/features-combobox--docs)
+when choosing a value from options (`Menu.Option` / `listbox` patterns are composed there—do not use
+`Menu.Option` alone for a standard menu button). Prefer
+[**Modal**](https://workday.github.io/canvas-kit/?path=/docs/components-popups-modal--docs) or
+[**Dialog**](https://workday.github.io/canvas-kit/?path=/docs/components-popups-dialog--docs) for
+task dialogs, not menus.
+
+### Minimum Accessible Structure
+
+The following matches the [Basic Example](#basic-example): a keyboard-operable **`Menu.Target`**,
+portaled **`Menu.Popper` → `Menu.Card` → `Menu.List`**, and **`Menu.Item`** children. On open, focus
+moves to the first menu item by default.
+
+```tsx
+import {Menu} from '@workday/canvas-kit-react/menu';
+
+<Menu>
+  <Menu.Target>Open Menu</Menu.Target>
+  <Menu.Popper>
+    <Menu.Card>
+      <Menu.List>
+        <Menu.Item>First Item</Menu.Item>
+        <Menu.Item>Second Item</Menu.Item>
+      </Menu.List>
+    </Menu.Card>
+  </Menu.Popper>
+</Menu>;
+```
+
+Provide a clearly named **`Menu.Target`** (visible text, or an icon-only control with
+**`Tooltip`**, or a translated **`aria-label`** if you are not using **`Tooltip`**). 
+Use **`aria-disabled`** on items that should stay in the keyboard sequence but
+not activate — do not use the native `disabled` attribute for disabled menu items.
+
+### Built-in Behaviors
+
+Canvas Kit applies these automatically via `useMenuModel` (list + popup) and Menu subcomponents.
+**Do not duplicate them** in consuming code.
+
+**Popup behaviors** (_composed on the default model_):
+
+- `useAlwaysCloseOnOutsideClick` — pointer interaction outside closes the menu
+- `useCloseOnEscape` — <kbd>Escape</kbd> closes the menu
+- `useReturnFocus` (_on `Menu.List`_) — returns focus to **`Menu.Target`** (or configured return
+  target) when the menu closes
+- `useFocusRedirect` (_on `Menu.List`_) — <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> from
+  inside the menu closes it and moves focus to the next or previous focusable element on the page
+  (not a focus trap)
+
+**ARIA and DOM** (_applied by hooks/subcomponents_):
+
+- **`Menu.Target`**: shared model `id`, `aria-haspopup="true"`,
+  `aria-expanded={visibility === 'visible'}`; <kbd>ArrowDown</kbd> / <kbd>ArrowUp</kbd> also open
+  the menu
+- **`Menu.List`**: `role="menu"`, `aria-labelledby` referencing the target `id`,
+  `aria-orientation` from the model
+- **`Menu.Item`**: `role="menuitem"`, roving `tabIndex` (`0` on the focused item, `-1` on others);
+  in default `mode="single"`, activating an item selects it and closes the menu (and any open parent
+  menus)
+- **`Menu.Group`**: `role="group"` with `aria-labelledby` referencing **`Menu.Group.Heading`** (or
+  the heading created from the `title` prop)
+- **`Menu.Submenu.TargetItem`**: `role="menuitem"`, `aria-haspopup="true"`, `aria-expanded` for the
+  submenu
+
+**Implementation note on open focus:** Menu does **not** compose `useInitialFocus`. In default
+`mode="single"`, **`useMenuItemFocus`** moves focus to the first menu item when the menu opens. Do
+not generate **`initialFocusRef`** — it is not wired on Menu.
+
+**Implementation note on `mode="multiple"`:** `useMenuModel` supports `mode="multiple"`, which keeps
+the menu open and toggles selection in model state. **`Menu.Item`** uses `role="menuitem"`, which
+does not support **`aria-selected`**, so selected state is not exposed to assistive technology. Do
+not generate **`mode="multiple"`** with **`Menu.Item`** for an accessible multi-select UI—use
+[**Select**](https://workday.github.io/canvas-kit/?path=/docs/components-inputs-select--docs),
+**MultiSelect**, or
+[**Combobox**](https://workday.github.io/canvas-kit/?path=/docs/features-combobox--docs) instead.
+
+**Keyboard** (_trigger is `Menu.Target`, default `SecondaryButton`; list uses vertical orientation by
+default_):
+
+- <kbd>Enter</kbd> / <kbd>Space</kbd> on the trigger opens the menu (button activation)
+- <kbd>ArrowDown</kbd> / <kbd>ArrowUp</kbd> on the trigger also opens the menu
+- On open, focus moves to the first menu item by default
+- <kbd>ArrowDown</kbd> / <kbd>ArrowUp</kbd> moves the roving tabindex between items
+- <kbd>Home</kbd> / <kbd>End</kbd> moves to the first or last item
+- <kbd>Enter</kbd> / <kbd>Space</kbd> on an item activates it and closes the menu (default
+  `mode="single"`)
+- <kbd>Escape</kbd> closes the menu and returns focus per `useReturnFocus`
+- <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> closes the menu via `useFocusRedirect`
+- <kbd>ArrowRight</kbd> / <kbd>Enter</kbd> / <kbd>Space</kbd> on **`Menu.Submenu.TargetItem`** opens
+  the submenu
+- <kbd>ArrowLeft</kbd> on a submenu item closes it (for LTR languages)
+
+**Screen reader expectations** (_when built-in behaviors are used as intended_):
+
+- On the trigger: name, button role, menu popup is available, and expanded/collapsed state
+  (for example: "Open Menu, button, menu popup, collapsed")
+- On open: menu role (labeled by the trigger), focused item name, menuitem role, and often position
+  in set (for example: "Open Menu, menu, First Item, menu item, 1 of 4")
+- While navigating: each focused item’s name and role; group labels when entering a
+  **`Menu.Group`**; submenu items announce has-popup / expanded state (for example: "More Actions, menu item, has submenu, collapsed, 3 of 4.")
+- Disabled items with **`aria-disabled`** remain discoverable but not selectable
+
+### Accessibility Requirements
+
+Required in application code for an accessible Menu. Hoist **`useMenuModel`** when you need return
+focus overrides or dynamic `items`. Rows marked _(conditional)_ apply only when the situation
+matches—otherwise omit.
+
+**If no design spec is provided:** use **`Menu.Target`** + **`Menu.Item`** (not **`Menu.Option`**),
+default `mode="single"`, default open focus on the first menu item, and omit **`returnFocusRef`**,
+**`initialFocusRef`**, and manual ARIA on Target/List/Item.
+
+**Focus management — defaults and developer prompts:** Canvas Kit handles open and close focus for
+the default menu button pattern. **State the default to the developer first.** Only set
+**`returnFocusRef`** after the developer (or an explicit design spec) chooses a non-default return
+target. **Do not generate `returnFocusRef` or `initialFocusRef` by default.**
+
+| 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?_ (Only when return focus should land somewhere other than **`Menu.Target`**.) |
+
+**Custom targets** _(conditional)_: Apply when using a custom **`as`** component on
+**`Menu.Target`**. **`Menu.Target`** adds **`onClick`**, keyboard openers, and **`ref`**. Custom
+targets must forward **`ref`** and props to a **keyboard-focusable** element (prefer a native
+**`<button>`** or **`as={SecondaryButton}`**). Wrap the component in **`React.forwardRef`** when it
+does not forward refs by default.
+
+| Requirement                                              | How to satisfy                                                                                                                                                                                                                                                                 |
+| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Keyboard-operable, named trigger                         | **`Menu.Target`** with visible text, or icon-only with **`Tooltip`** (default `type="label"` sets `aria-label`) or a translated **`aria-label`** without **`Tooltip`**. See **Custom targets** above.                                                |
+| Menu list composition                                    | **`Menu.Popper` → `Menu.Card` → `Menu.List`** with **`Menu.Item`** children (or dynamic `items` + render prop on **`Menu.List`**).                                                                                                                                            |
+| Disabled items _(conditional)_                           | **`aria-disabled`** on **`Menu.Item`** so the item stays in the roving tabindex / screen reader sequence.                                                                                                                                                                      |
+| Stable item ids _(conditional)_                          | **`data-id`** on items when using **`onSelect`**, dynamic lists, or nested menus that need stable selection ids.                                                                                                                                                               |
+| 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`.                                                                                                             |
+| Context menu trigger _(conditional)_                     | **`Menu.TargetContext`** instead of **`Menu.Target`**. OS/browser support for `contextmenu` / Shift+F10 varies—provide an alternate open path for critical actions when required.                                                                                              |
+| Selectable or multi-select options _(conditional)_       | Do **not** use **`Menu.Option`**, `role="listbox"`, or **`mode="multiple"`** with **`Menu.Item`** for a menu button. Compose via [**Select**](https://workday.github.io/canvas-kit/?path=/docs/components-inputs-select--docs), **MultiSelect**, or [**Combobox**](https://workday.github.io/canvas-kit/?path=/docs/features-combobox--docs). |
+
+**Summary for code generation:**
+
+- **REQUIRED:** keyboard-operable named **`Menu.Target`**, **`Menu.Popper` → `Menu.Card` →
+  `Menu.List`**, **`Menu.Item`** (or dynamic list items)
+- **CONDITIONAL:** **`aria-disabled`**, **`data-id`**, **`data-text`**, groups, submenus,
+  **`Menu.TargetContext`**, **`returnFocusRef`**, **`forwardRef`** on custom targets
+
+### Anti-Patterns
+
+Do **not** generate code that does the following (see **Accessibility Requirements** above for what
+to supply instead):
+
+- Manually set `role="menu"`, `role="menuitem"`, `aria-labelledby`, `aria-orientation`,
+  `aria-haspopup`, `aria-expanded`, shared `id`, or roving `tabIndex` on **`Menu.Target`**,
+  **`Menu.List`**, **`Menu.Item`**, or **`Menu.Submenu.TargetItem`** — Canvas Kit hooks wire these
+- Omit **`Menu.Popper`**, or render **`Menu.Card` / `Menu.List`** outside the Menu composition
+- Use **`Menu.Option`**, `role="listbox"`, or **`mode="multiple"`** with **`Menu.Item`** for
+  selectable or multi-select UIs — use **Select**, **MultiSelect**, or **Combobox** instead (see
+  **Implementation note on `mode="multiple"`** in Built-in Behaviors)
+- Set **`initialFocusRef`** — Menu does not compose **`useInitialFocus`**, so this prop has no
+  effect on open focus (see **Built-in Behaviors**)
+- Set **`returnFocusRef`** by default — state the default return-to-target behavior first and ask
+  before overriding
+- 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 that does not forward **`ref`** to a focusable
+  element — use **`React.forwardRef`** or a Canvas Kit button component instead
+- Treat Menu like a **Modal** / **Dialog** (focus trap, `role="dialog"`, inert page) — Menu is a
+  menu button popup with roving tabindex inside **`role="menu"`**
 
 ## Component API