From 3e48585737f526ee99e68e7b2758a30ca373771a Mon Sep 17 00:00:00 2001
From: Purva Sane <purva.sane@workday.com>
Date: Mon, 28 Sep 2026 10:53:41 -0400
Subject: [PATCH 1/2] docs(button): Rewrite accessibility section for AI
 codegen

Align Button docs with the Canvas Kit accessibility template: structure,
built-in behaviors, requirements table, and anti-patterns scoped to variant
buttons with correct Segmented Control and icon-only naming guidance.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../react/button/stories/button/Button.mdx    | 178 ++++++++++++++----
 1 file changed, 138 insertions(+), 40 deletions(-)

diff --git a/modules/react/button/stories/button/Button.mdx b/modules/react/button/stories/button/Button.mdx
index 0170fad023..9d1a9b82da 100644
--- a/modules/react/button/stories/button/Button.mdx
+++ b/modules/react/button/stories/button/Button.mdx
@@ -118,47 +118,145 @@ tokens with the fallback being `brand.primary.**`.
 
 ## Accessibility
 
-Our button components render semantic HTML `<button>` elements to the browser DOM. This means that
-ARIA roles won't be necessary in most cases, and `onClick` listeners will automatically support the
-Enter and Space keys for keyboard interactions.
-
-[Button Pattern | APG | WAI | W3C](https://www.w3.org/WAI/ARIA/apg/patterns/button/)
-
-- An `aria-label` is only necessary for icon-only buttons in most cases. Using
-  [Canvas Kit's tooltip component](/components/popups/tooltip/) will handle this for you, and all
-  users will be able to see the label for the button.
-- When button designs have 2 toggle states, an `aria-pressed={true | false}` property is required
-  for screen reader support. For example, see Canvas Kit's
-  [Segmented Control component](/components/buttons/segmented-control/).
-- When buttons have an attached menu, an `aria-haspopup="true"` property is required. Using
-  [Canvas Kit's Menu component](/components/popups/menu/) will handle this for you.
-- The icons used in text buttons are decorative in most cases and include ARIA `role="presentation"`
-  and `focusable="false"`. In some special cases where an icon does add meaning, you may be required
-  to change the `role` and add an `aria-label` to the icon for equivalent screen reader support.
-
-### Disabled Buttons
-
-- Disabled buttons use the `disabled` attribute, removing them from the tab order.
-- Disabled styling is exempt from WCAG contrast requirements.
-
-### Screen Reader Experience
-
-- Button text content is announced along with the button role (e.g., "Primary, button").
-- Icon-only buttons announce the `aria-label` value along with the button role.
-- Toggle buttons announce their pressed/unpressed state (e.g., "Activity Stream, toggle button,
-  pressed" and check out the [Segmented Control component](/components/buttons/segmented-control/)).
-
-### Touch Target Size
-
-- All buttons meet the minimum 24px by 24px touch target size requirement for mobile accessibility.
-- Button padding ensures adequate spacing between interactive elements to prevent accidental
-  activation.
-
-### Button Groups
+The primary accessibility goal is a visible, programmatically determinable name on a native control
+that performs an in-page action (submit, open, dismiss, and similar). This page covers
+**`PrimaryButton`**, **`SecondaryButton`**, **`TertiaryButton`**, and **`DeleteButton`**. Use
+[Hyperlink](https://workday.github.io/canvas-kit/?path=/docs/components-hyperlink--docs) when the
+control navigates to another URL or in-page location. For
+[Toolbar](https://workday.github.io/canvas-kit/?path=/docs/components-buttons-toolbar--docs)
+icon and dropdown controls, see that component’s documentation. For a control that opens a menu,
+compose [Menu](/components/popups/menu/) so **`Menu.Target`** wires popup state. When users choose
+one value from **two or more** mutually exclusive options, use
+[Segmented Control](/components/buttons/segmented-control/) (`SegmentedControl.List` with multiple
+**`SegmentedControl.Item`** components)—not a lone variant button.
+
+See the [Button pattern (APG)](https://www.w3.org/WAI/ARIA/apg/patterns/button/) and Canvas Kit
+[Accessibility overview](https://workday.github.io/canvas-kit/?path=/docs/guides-accessibility-overview--docs).
+
+### Minimum Accessible Structure
+
+The following matches the [PrimaryButton](#primarybutton) examples: visible text for the default case,
+text plus a decorative icon, and an icon-only control with an accessible name.
+
+```tsx
+import {PrimaryButton} from '@workday/canvas-kit-react/button';
+import {Tooltip} from '@workday/canvas-kit-react/tooltip';
+import {plusIcon, relatedActionsVerticalIcon} from '@workday/canvas-system-icons-web';
+
+<PrimaryButton>Save</PrimaryButton>;
+
+<PrimaryButton icon={plusIcon}>Add item</PrimaryButton>;
+
+<Tooltip title="Related Actions">
+  <PrimaryButton icon={relatedActionsVerticalIcon} />
+</Tooltip>;
+```
 
-- Related buttons can be grouped together with HTML unordered list elements or with `<fieldset>` and
-  `<legend>` elements. This can help give additional context to screen readers about the purpose of
-  the group.
+For icon-only buttons, prefer **`Tooltip`** with **`title`** and default `type="label"` (which sets
+**`aria-label`** from **`title`** so sighted users also see the label). If the spec explicitly says
+not to use a tooltip, set **`aria-label`** on the button instead. The same patterns apply to
+**`SecondaryButton`**, **`TertiaryButton`**, and **`DeleteButton`**.
+
+### Built-in Behaviors
+
+Canvas Kit applies these automatically on **`PrimaryButton`**, **`SecondaryButton`**,
+**`TertiaryButton`**, and **`DeleteButton`**. **Do not duplicate them** in consuming code.
+
+**ARIA and DOM** (_applied by button components_):
+
+- **Variant buttons**: Render a native `<button type="button">` (via **`BaseButton`**). Do not add
+  `role="button"`.
+- **Visible label**: Button text is rendered in **`BaseButton.Label`** (`<span>`) inside the
+  `<button>` so its text contributes to the accessible name.
+- **`icon`**: Renders **`BaseButton.Icon`** (`SystemIcon`). Canvas Kit icon SVG markup uses
+  `role="presentation"` and `focusable="false"`, so icons beside visible text are not announced
+  separately.
+- **`disabled`**: Maps to the native `disabled` attribute; disabled buttons are skipped in the tab
+  order.
+- **Focus**: Visible focus styling uses `:focus-visible` (and a `.focus` class twin for visual
+  testing).
+- **`ref`**: Forwards to the underlying `<button>`.
+- **Native button attributes**: Standard props (for example `aria-label`, `aria-pressed`,
+  `aria-expanded`, `id`, `onClick`) pass through to the `<button>` unless you change the element with
+  **`as`**. Variant buttons do not set **`aria-pressed`** unless you pass it for a deliberate toggle
+  design.
+- **Menus**: Variant buttons do **not** set `aria-haspopup` or `aria-expanded`.
+  **`Menu.Target`** (and related Menu APIs) apply those when a menu is attached.
+
+**Keyboard** (_native `<button>` behavior_):
+
+Variant buttons use native button keyboard support: <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd>
+for focus order, and <kbd>Enter</kbd> or <kbd>Space</kbd> to activate. Do not replace the
+`<button>` with a non-focusable element or suppress activation keys.
+
+**Screen reader expectations** (_when built-in behaviors are used as intended_):
+
+- On focus, assistive technology announces the button name (visible text and/or `aria-label`) and
+  role (for example, "Save, button").
+- Icons rendered with **`icon`** next to visible text are not announced as separate images.
+- Disabled buttons are announced as unavailable and are not in the tab order.
+- When the button opens a menu through **`Menu`**, **`Menu.Target`** exposes popup and expanded
+  state; see [Menu accessibility](/components/popups/menu/#accessibility).
+
+### Accessibility Requirements
+
+Required in application code for an accessible button. Rows marked _(conditional)_ apply only when the
+situation matches—otherwise omit.
+
+**If no design spec is provided:** use a **`PrimaryButton`** (or the variant that matches the design)
+with non-empty visible text. Omit **`icon`**, **`disabled`**, **`Tooltip`**, **`aria-label`**, custom
+**`id`**, **`as`**, and a **`ref`** unless the spec requires them.
+
+| Requirement                            | How to satisfy                                                                                                                                                                                                                                                                 |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Accessible name                        | Non-empty visible text inside the variant button                                                                                                                                                                                                                               |
+| Icon-only name _(conditional)_         | **`Tooltip`** with `type="label"` and **`title`** (preferred; see [PrimaryButton](#primarybutton)), or **`aria-label`** when the spec explicitly says not to use a tooltip. Do not use `type="muted"` on **`Tooltip`**—it does not set an accessible name                      |
+| Variant choice                         | **`PrimaryButton`**, **`SecondaryButton`**, **`TertiaryButton`**, or **`DeleteButton`** per design; **`DeleteButton`** only for destructive actions                                                                                                                            |
+| Decorative icon _(conditional)_        | **`icon`** with visible text—no extra ARIA on the icon; meaning comes from button text                                                                                                                                                                                         |
+| Mutually exclusive group _(conditional)_ | [Segmented Control](/components/buttons/segmented-control/) with two or more **`SegmentedControl.Item`** siblings and **`aria-label`** on **`SegmentedControl.List`**—not for a single button or lone on/off control                                                         |
+| Toggle pressed state _(conditional)_   | **`aria-pressed`** on a variant button for a standalone on/off control, or [Toolbar](https://workday.github.io/canvas-kit/?path=/docs/components-buttons-toolbar--docs) per toolbar specs—not for one-shot actions (Save, Delete, Open)                                       |
+| Menu trigger _(conditional)_           | **`Menu`** + **`Menu.Target`** (or **`Menu.ContextTarget`**) as the button—do not hand-wire `aria-haspopup` / `aria-expanded` without the Menu model; see [Menu accessibility](/components/popups/menu/#accessibility)                                                       |
+| Related button groups _(conditional)_  | Semantic grouping (`<ul>` / `<li>` or `<fieldset>` / `<legend>`) when several buttons share one question or legend; each control still needs its own accessible name                                                                                                            |
+| Disabled _(conditional)_               | Native **`disabled`** on the variant button when the spec marks the action unavailable                                                                                                                                                                                       |
+| Navigation _(conditional)_           | [Hyperlink](https://workday.github.io/canvas-kit/?path=/docs/components-hyperlink--docs) instead of a variant button when the action is navigation                                                                                                                             |
+| Programmatic focus _(conditional)_     | `ref` on the variant button and `focus()` only when the product must move focus after an action—omit by default                                                                                                                                                                |
+
+**Summary for code generation:**
+
+- **REQUIRED:** variant button with a non-empty accessible name (visible text for text buttons; for
+  icon-only, **`Tooltip`** with `type="label"` preferred, or **`aria-label`** when the spec says not
+  to use a tooltip)
+- **CONDITIONAL:** **`icon`**; icon-only naming; **`disabled`**; **`aria-pressed`** for toggle
+  specs; **`Menu`** for menus; **`Hyperlink`** for navigation; grouping markup; programmatic focus
+  via `ref`
+
+### Anti-Patterns
+
+Do **not** generate code that does the following (see **Accessibility Requirements** above for what
+to supply instead):
+
+- Use a `<div>` or `<span>` with `onClick` instead of a variant button—use **`PrimaryButton`**, **`SecondaryButton`**, **`TertiaryButton`**, or **`DeleteButton`** so keyboard and assistive technology get native `<button>` behavior
+- Add `role="button"` on variant buttons—the control is already a `<button>`
+- Use a variant button (or `type="submit"` without an intentional form action) for URL
+  navigation—use
+  [Hyperlink](https://workday.github.io/canvas-kit/?path=/docs/components-hyperlink--docs)
+- Leave icon-only buttons without a name—prefer **`Tooltip`** with `type="label"`, or
+  **`aria-label`** when the spec says not to use a tooltip; do not rely on the icon graphic alone
+- Use **`Tooltip`** with `type="muted"` on icon-only buttons—muted tooltips do not set an accessible
+  name
+- Use **`aria-label`** on icon-only buttons when the spec allows tooltips—prefer **`Tooltip`** with
+  `type="label"` unless the spec explicitly says not to use a tooltip
+- Set `aria-haspopup` or `aria-expanded` on a variant button without **`Menu`**—use
+  **`Menu.Target`** so open state stays in sync with the menu model
+- Set **`aria-pressed`** on one-shot actions (Save, Delete, Open)—see **Toggle pressed state** in the
+  requirements table
+- Use **`SegmentedControl`** for a single option or a lone on/off control—see **Mutually exclusive
+  group** in the requirements table
+- Add `aria-hidden` or change the **`role`** on **`icon`** when visible button text already conveys
+  meaning—Canvas Kit icons are presentational.
+- Use **`aria-disabled`** instead of **`disabled`**—variant buttons map unavailability to the
+  native **`disabled`** attribute
+- Duplicate menu ARIA that **`Menu.Target`** already applies
 
 ## Component API
 

From ff4268e9c5b3c39ebd4f1151f171b52b45b0181d Mon Sep 17 00:00:00 2001
From: Purva Sane <purva.sane@workday.com>
Date: Tue, 6 Oct 2026 15:23:45 -0400
Subject: [PATCH 2/2] docs(button): Expand accessibility docs for AI codegen

Update Button accessibility guidance per review, use Tooltip in ThemeOverrides, fix Storybook Canvas path rewrites, and use a static list-box selector in MenuCard for Vite.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .storybook/main.ts                            |   5 +-
 .storybook/remark-rewrite-canvas-routes.ts    |  32 ++++
 .storybook/routes.js                          |   7 +-
 .../vite-plugin-redirect-mdx-to-github.ts     |  12 +-
 .../react/button/stories/button/Button.mdx    | 153 +++++++-----------
 .../button/examples/ThemeOverrides.tsx        |   9 +-
 modules/react/collection/index.ts             |   7 +-
 modules/react/collection/lib/ListBox.tsx      |   3 +
 modules/react/menu/lib/MenuCard.tsx           |   6 +-
 9 files changed, 132 insertions(+), 102 deletions(-)
 create mode 100644 .storybook/remark-rewrite-canvas-routes.ts

diff --git a/.storybook/main.ts b/.storybook/main.ts
index 37954fc0ff..20b5bd1cfb 100644
--- a/.storybook/main.ts
+++ b/.storybook/main.ts
@@ -11,6 +11,7 @@ import {ExportedSymbol, Value} from '@workday/canvas-kit-docs/docgen/docTypes';
 import {version} from '../lerna.json' assert {type: 'json'};
 import stylingConfig from '../styling.config';
 import { vitePluginInlineSpecifications } from './vite-plugin-inline-specifications';
+import {remarkRewriteCanvasRoutes} from './remark-rewrite-canvas-routes';
 import { vitePluginRedirectMDXToGithub } from './vite-plugin-redirect-mdx-to-github';
 import { vitePluginWholeSource } from './vite-plugin-whole-source';
 import { vitePluginTypescriptWithTransformers } from '@workday/canvas-kit-styling-transform/vite';
@@ -44,7 +45,7 @@ const config: StorybookConfig = {
       options: {
         mdxPluginOptions: {
           mdxCompileOptions: {
-            remarkPlugins: [remarkGfm],
+            remarkPlugins: [remarkGfm, remarkRewriteCanvasRoutes],
           },
         },
       },
@@ -73,7 +74,7 @@ const config: StorybookConfig = {
             ...mdx({
               include: '*.md',
               providerImportSource: '@mdx-js/react',
-              remarkPlugins: [remarkGfm],
+              remarkPlugins: [remarkGfm, remarkRewriteCanvasRoutes],
             }),
           },
           vitePluginWholeSource(),
diff --git a/.storybook/remark-rewrite-canvas-routes.ts b/.storybook/remark-rewrite-canvas-routes.ts
new file mode 100644
index 0000000000..1762b54f7f
--- /dev/null
+++ b/.storybook/remark-rewrite-canvas-routes.ts
@@ -0,0 +1,32 @@
+import type {Plugin} from 'unified';
+import {visit} from 'unist-util-visit';
+
+import routes from './routes';
+
+/**
+ * Rewrites Canvas site paths (`/components/.../`) to Storybook manager URLs for local docs and
+ * GitHub Pages. Runs during MDX compile so links in tables and nested MDX are included.
+ */
+export function remarkRewriteCanvasRoutes(): Plugin {
+  const routeKeys = new Set(Object.keys(routes));
+
+  return tree => {
+    visit(tree, 'link', node => {
+      const url = node.url;
+      if (typeof url !== 'string' || !url.startsWith('/')) {
+        return;
+      }
+
+      const hashIndex = url.indexOf('#');
+      const pathPart = hashIndex === -1 ? url : url.slice(0, hashIndex);
+      const hash = hashIndex === -1 ? '' : url.slice(hashIndex + 1);
+
+      if (!routeKeys.has(pathPart)) {
+        return;
+      }
+
+      const storyId = routes[pathPart as keyof typeof routes];
+      node.url = `../?path=/docs/${storyId}${hash ? `#${hash}` : ''}`;
+    });
+  };
+}
diff --git a/.storybook/routes.js b/.storybook/routes.js
index 5f17176fb5..1be755060f 100644
--- a/.storybook/routes.js
+++ b/.storybook/routes.js
@@ -10,8 +10,10 @@ const routes = {
   // Components
   '/components/buttons/action-bar/': 'components-buttons-action-bar--docs',
   '/components/buttons/button/': 'components-buttons--docs',
-  '/components/buttons/segmented-control/': 'preview-segmented-control--docs',
+  '/components/buttons/segmented-control/': 'components-buttons-segmented-control--docs',
+  '/components/buttons/toolbar/': 'components-buttons-toolbar--docs',
   '/components/containers/card/': 'components-containers-card--docs',
+  '/components/containers/expandable/': 'components-containers-expandable--docs',
   '/components/containers/side-panel/': 'preview-side-panel--docs',
   '/components/containers/table/': 'components-containers-table--docs',
   '/components/containers/tabs/': 'components-containers-tabs--docs',
@@ -23,6 +25,7 @@ const routes = {
   '/components/inputs/color-input/': 'components-inputs-color-picker-color-input--docs',
   '/components/inputs/form-field/': 'components-inputs-form-field--docs',
   '/components/inputs/radio/': 'preview-inputs-radio--docs',
+  '/preview/inputs/radio/': 'preview-inputs-radio--docs',
   '/components/inputs/select/': 'components-inputs-select--docs',
   '/components/inputs/switch/': 'preview-inputs-switch-new--docs',
   '/components/inputs/text-area/': 'components-inputs-textarea--docs',
@@ -44,7 +47,9 @@ const routes = {
   '/components/text/subtext/': 'components-text-subtext--docs',
   '/components/text/text/': 'components-text-text--docs',
   '/components/text/title/': 'components-text-title--docs',
+  '/components/hyperlink/': 'components-hyperlink--docs',
   // Get Started
+  '/guides/accessibility/overview/': 'guides-accessibility-overview--docs',
   '/get-started/for-developers/theming/overview/': 'features-theming-overview--docs',
   '/get-started/for-contributors/code/': 'guides-contributing--docs',
   '/get-started/for-developers/guides/combobox/': 'features-combobox--docs',
diff --git a/.storybook/vite-plugin-redirect-mdx-to-github.ts b/.storybook/vite-plugin-redirect-mdx-to-github.ts
index 4b317304fc..9e2a405e89 100644
--- a/.storybook/vite-plugin-redirect-mdx-to-github.ts
+++ b/.storybook/vite-plugin-redirect-mdx-to-github.ts
@@ -18,14 +18,22 @@ export function vitePluginRedirectMDXToGithub(): PluginOption {
       if (/.mdx?$/.test(id)) {
         return code
           .replace(/\[([^\]]+)\]\((\/[^\)]+)\)/g, function replacer(_match, p1, p2) {
-            const [url, hash] = p2.split('#');
+            const hashIndex = p2.indexOf('#');
+            const url = hashIndex === -1 ? p2 : p2.slice(0, hashIndex);
+            const hash = hashIndex === -1 ? '' : p2.slice(hashIndex + 1);
             if (routeKeys.includes(url)) {
-              return `[${p1}](?path=/docs/${routes[url]}${hash ? '#' + hash : ''})`;
+              // `../?path=` so links from the docs iframe resolve to the manager URL
+              // (e.g. `/?path=/docs/...` locally and `/canvas-kit/?path=...` on GitHub Pages).
+              return `[${p1}](../?path=/docs/${routes[url]}${hash ? `#${hash}` : ''})`;
             }
             // no match, return original
             return `[${p1}](${p2})`;
           })
           .replace(/\[([^\]]+)\]\((\.\.?[^\)]+)\)/g, function replacer(match, p1, p2) {
+            // Storybook doc links rewritten by `remarkRewriteCanvasRoutes` / the route replacer above
+            if (p2.startsWith('../?path=') || p2.startsWith('./?path=') || p2.startsWith('?path=')) {
+              return match;
+            }
             // extract the directory from the resourcePath given by Webpack
             const {dir} = path.parse(id);
 
diff --git a/modules/react/button/stories/button/Button.mdx b/modules/react/button/stories/button/Button.mdx
index 9d1a9b82da..28874887be 100644
--- a/modules/react/button/stories/button/Button.mdx
+++ b/modules/react/button/stories/button/Button.mdx
@@ -118,25 +118,20 @@ tokens with the fallback being `brand.primary.**`.
 
 ## Accessibility
 
-The primary accessibility goal is a visible, programmatically determinable name on a native control
-that performs an in-page action (submit, open, dismiss, and similar). This page covers
-**`PrimaryButton`**, **`SecondaryButton`**, **`TertiaryButton`**, and **`DeleteButton`**. Use
-[Hyperlink](https://workday.github.io/canvas-kit/?path=/docs/components-hyperlink--docs) when the
-control navigates to another URL or in-page location. For
-[Toolbar](https://workday.github.io/canvas-kit/?path=/docs/components-buttons-toolbar--docs)
-icon and dropdown controls, see that component’s documentation. For a control that opens a menu,
-compose [Menu](/components/popups/menu/) so **`Menu.Target`** wires popup state. When users choose
-one value from **two or more** mutually exclusive options, use
-[Segmented Control](/components/buttons/segmented-control/) (`SegmentedControl.List` with multiple
-**`SegmentedControl.Item`** components)—not a lone variant button.
-
-See the [Button pattern (APG)](https://www.w3.org/WAI/ARIA/apg/patterns/button/) and Canvas Kit
-[Accessibility overview](https://workday.github.io/canvas-kit/?path=/docs/guides-accessibility-overview--docs).
+The primary accessibility goal is a visible, programmatically determinable name on a native control that performs an in-page action (submit, open, dismiss, and similar). This page covers **`PrimaryButton`**, **`SecondaryButton`**, **`TertiaryButton`**, and **`DeleteButton`**.
+
+Use [Hyperlink](/components/hyperlink/) when the control navigates to another URL or in-page location.
+
+For [Toolbar](/components/buttons/toolbar/) icon and dropdown controls, see that component’s documentation. For a control that opens a menu, dialog, or expandable, see [Menu accessibility](/components/popups/menu/#accessibility), [Dialog accessibility](/components/popups/dialog/#accessibility), and [Expandable accessibility](/components/containers/expandable/#accessibility).
+
+When users choose one value from **two or more** mutually exclusive options, use
+[Segmented Control](/components/buttons/segmented-control/)—not a lone variant button. Use [Radio](/preview/inputs/radio/) when the selection needs radio semantics or native form submission.
+
+See the [Button pattern (APG)](https://www.w3.org/WAI/ARIA/apg/patterns/button/) and Canvas Kit [Accessibility overview](/guides/accessibility/overview/).
 
 ### Minimum Accessible Structure
 
-The following matches the [PrimaryButton](#primarybutton) examples: visible text for the default case,
-text plus a decorative icon, and an icon-only control with an accessible name.
+The following matches the [PrimaryButton](#primarybutton) examples: visible text for the default case, text plus a decorative icon, and an icon-only control with an accessible name.
 
 ```tsx
 import {PrimaryButton} from '@workday/canvas-kit-react/button';
@@ -152,111 +147,87 @@ import {plusIcon, relatedActionsVerticalIcon} from '@workday/canvas-system-icons
 </Tooltip>;
 ```
 
-For icon-only buttons, prefer **`Tooltip`** with **`title`** and default `type="label"` (which sets
-**`aria-label`** from **`title`** so sighted users also see the label). If the spec explicitly says
-not to use a tooltip, set **`aria-label`** on the button instead. The same patterns apply to
-**`SecondaryButton`**, **`TertiaryButton`**, and **`DeleteButton`**.
+For icon-only buttons, prefer **`Tooltip`** with **`title`** and default `type="label"` (which sets **`aria-label`** from **`title`** so sighted users also see the label). **`Tooltip`** with `type="label"` overwrites the wrapped control’s accessible name—use it on icon-only buttons only; visible button text already supplies the name. If the spec explicitly says not to use a tooltip, set **`aria-label`** on the button instead. The same patterns apply to **`SecondaryButton`**, **`TertiaryButton`**, and **`DeleteButton`**.
 
 ### Built-in Behaviors
 
-Canvas Kit applies these automatically on **`PrimaryButton`**, **`SecondaryButton`**,
-**`TertiaryButton`**, and **`DeleteButton`**. **Do not duplicate them** in consuming code.
+Canvas Kit applies these automatically on **`PrimaryButton`**, **`SecondaryButton`**, **`TertiaryButton`**, and **`DeleteButton`**. **Do not duplicate them** in consuming code.
 
 **ARIA and DOM** (_applied by button components_):
 
-- **Variant buttons**: Render a native `<button type="button">` (via **`BaseButton`**). Do not add
-  `role="button"`.
-- **Visible label**: Button text is rendered in **`BaseButton.Label`** (`<span>`) inside the
-  `<button>` so its text contributes to the accessible name.
-- **`icon`**: Renders **`BaseButton.Icon`** (`SystemIcon`). Canvas Kit icon SVG markup uses
-  `role="presentation"` and `focusable="false"`, so icons beside visible text are not announced
-  separately.
-- **`disabled`**: Maps to the native `disabled` attribute; disabled buttons are skipped in the tab
-  order.
-- **Focus**: Visible focus styling uses `:focus-visible` (and a `.focus` class twin for visual
-  testing).
+- **Variant buttons**: Render a native `<button>` (via **`BaseButton`**) with default **`type="button"`**. A passed **`type`** prop overrides that default—use **`type="submit"`** only when the button submits its form.
+- **Visible label**: Button text is rendered in **`BaseButton.Label`** (`<span>`) inside the `<button>` so its text contributes to the accessible name.
+- **`icon`**: Renders **`BaseButton.Icon`** (`SystemIcon`). Canvas Kit icon SVG markup uses `role="presentation"` and `focusable="false"`, so icons beside visible text are not announced separately.
+- **`disabled`**: Maps to the native `disabled` attribute; disabled buttons are skipped in the tab order.
+- **Focus**: Visible focus styling uses `:focus-visible`.
 - **`ref`**: Forwards to the underlying `<button>`.
-- **Native button attributes**: Standard props (for example `aria-label`, `aria-pressed`,
-  `aria-expanded`, `id`, `onClick`) pass through to the `<button>` unless you change the element with
-  **`as`**. Variant buttons do not set **`aria-pressed`** unless you pass it for a deliberate toggle
-  design.
-- **Menus**: Variant buttons do **not** set `aria-haspopup` or `aria-expanded`.
-  **`Menu.Target`** (and related Menu APIs) apply those when a menu is attached.
+- **Native button attributes**: Standard props (for example `aria-label`, `aria-pressed`, `aria-expanded`, `id`, `onClick`) pass through to the `<button>` unless you change the element with **`as`**. Variant buttons do not set **`aria-pressed`** unless you pass it for a deliberate toggle design.
+- **Popup triggers**: Variant buttons do **not** set `aria-haspopup` or `aria-expanded`. `Menu.Target`, `Expandable.Target`, and `Dialog.Target` own those per their docs.
 
 **Keyboard** (_native `<button>` behavior_):
 
-Variant buttons use native button keyboard support: <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd>
-for focus order, and <kbd>Enter</kbd> or <kbd>Space</kbd> to activate. Do not replace the
-`<button>` with a non-focusable element or suppress activation keys.
+Variant buttons use native button keyboard support: <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> for focus order, and <kbd>Enter</kbd> or <kbd>Space</kbd> to activate.
 
 **Screen reader expectations** (_when built-in behaviors are used as intended_):
 
-- On focus, assistive technology announces the button name (visible text and/or `aria-label`) and
-  role (for example, "Save, button").
+- On focus, assistive technology announces the button name (visible text and/or `aria-label`) and role (for example, "Save, button").
 - Icons rendered with **`icon`** next to visible text are not announced as separate images.
 - Disabled buttons are announced as unavailable and are not in the tab order.
-- When the button opens a menu through **`Menu`**, **`Menu.Target`** exposes popup and expanded
-  state; see [Menu accessibility](/components/popups/menu/#accessibility).
+- When a variant button has `aria-pressed` and a stable visible label, assistive technology announces the name, “toggle button,” and pressed or not pressed (for example, “Bold, toggle button, pressed”).
+- When a variant button is a popup **`*.Target`**, assistive technology follows that component’s documented popup and expanded behavior.
 
 ### Accessibility Requirements
 
-Required in application code for an accessible button. Rows marked _(conditional)_ apply only when the
-situation matches—otherwise omit.
+Required in application code for an accessible button. Rows marked _(conditional)_ apply only when the situation matches—otherwise omit.
 
-**If no design spec is provided:** use a **`PrimaryButton`** (or the variant that matches the design)
-with non-empty visible text. Omit **`icon`**, **`disabled`**, **`Tooltip`**, **`aria-label`**, custom
-**`id`**, **`as`**, and a **`ref`** unless the spec requires them.
+**If no design spec is provided:** use **`PrimaryButton`** with non-empty visible text and default **`type="button"`**. Omit **`icon`**, **`disabled`**, **`Tooltip`**, **`aria-label`**, custom **`id`**, **`as`**, **`type="submit"`**, and a **`ref`** unless the spec requires them.
 
-| Requirement                            | How to satisfy                                                                                                                                                                                                                                                                 |
+| Requirement  | How to satisfy  |
 | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Accessible name                        | Non-empty visible text inside the variant button                                                                                                                                                                                                                               |
-| Icon-only name _(conditional)_         | **`Tooltip`** with `type="label"` and **`title`** (preferred; see [PrimaryButton](#primarybutton)), or **`aria-label`** when the spec explicitly says not to use a tooltip. Do not use `type="muted"` on **`Tooltip`**—it does not set an accessible name                      |
-| Variant choice                         | **`PrimaryButton`**, **`SecondaryButton`**, **`TertiaryButton`**, or **`DeleteButton`** per design; **`DeleteButton`** only for destructive actions                                                                                                                            |
-| Decorative icon _(conditional)_        | **`icon`** with visible text—no extra ARIA on the icon; meaning comes from button text                                                                                                                                                                                         |
-| Mutually exclusive group _(conditional)_ | [Segmented Control](/components/buttons/segmented-control/) with two or more **`SegmentedControl.Item`** siblings and **`aria-label`** on **`SegmentedControl.List`**—not for a single button or lone on/off control                                                         |
-| Toggle pressed state _(conditional)_   | **`aria-pressed`** on a variant button for a standalone on/off control, or [Toolbar](https://workday.github.io/canvas-kit/?path=/docs/components-buttons-toolbar--docs) per toolbar specs—not for one-shot actions (Save, Delete, Open)                                       |
-| Menu trigger _(conditional)_           | **`Menu`** + **`Menu.Target`** (or **`Menu.ContextTarget`**) as the button—do not hand-wire `aria-haspopup` / `aria-expanded` without the Menu model; see [Menu accessibility](/components/popups/menu/#accessibility)                                                       |
-| Related button groups _(conditional)_  | Semantic grouping (`<ul>` / `<li>` or `<fieldset>` / `<legend>`) when several buttons share one question or legend; each control still needs its own accessible name                                                                                                            |
-| Disabled _(conditional)_               | Native **`disabled`** on the variant button when the spec marks the action unavailable                                                                                                                                                                                       |
-| Navigation _(conditional)_           | [Hyperlink](https://workday.github.io/canvas-kit/?path=/docs/components-hyperlink--docs) instead of a variant button when the action is navigation                                                                                                                             |
-| Programmatic focus _(conditional)_     | `ref` on the variant button and `focus()` only when the product must move focus after an action—omit by default                                                                                                                                                                |
+| Accessible name  | Non-empty visible text inside the variant button  |
+| Icon-only name _(conditional)_         | **`Tooltip`** with `type="label"` and **`title`** on icon-only buttons (see [PrimaryButton](#primarybutton)), or **`aria-label`** when the spec explicitly says not to use a tooltip  |
+| Variant choice                         | **`PrimaryButton`**, **`SecondaryButton`**, **`TertiaryButton`**, or **`DeleteButton`** per design; **`DeleteButton`** only for destructive actions  |
+| Decorative icon _(conditional)_        | **`icon`** with visible text—meaning comes from button text  |
+| Form submit _(conditional)_            | **`type="submit"`** on the variant button inside a form that should submit when activated; omit **`type="submit"`** otherwise (default **`type="button"`**)  |
+| Mutually exclusive group _(conditional)_ | [Segmented Control](/components/buttons/segmented-control/) for two or more in-page mutually exclusive options—not a single variant button or lone on/off control; use [Radio](/preview/inputs/radio/) when the selection is a form value |
+| Toggle pressed state _(conditional)_   | On/off controls: use **`aria-pressed`** only when the visible label stays stable while state changes (not Mute/Unmute-style labels); set **`aria-pressed`** in both states and include or ask the user for visual styling for pressed state—variant buttons do not provide default pressed visuals. Omit for one-shot actions (Save, Delete, Open). For a toolbar toggle, use **`ToolbarIconButton`**—see [Toolbar](/components/buttons/toolbar/)  |
+| Menu trigger _(conditional)_           | Compose **`Menu`** with **`Menu.Target as={PrimaryButton}`** (**`Menu.Target`** defaults to **`SecondaryButton`**). Context menus: **`Menu.ContextTarget`**. See [Menu accessibility](/components/popups/menu/#accessibility) and **Menu trigger composition** below          |
+| Related button groups _(conditional)_  | Semantic grouping (`<ul>` / `<li>` or `<fieldset>` / `<legend>`) when several buttons share one question or legend; each control still needs its own accessible name  |
+| Disabled _(conditional)_               | Native **`disabled`** on the variant button when the spec marks the action unavailable  |
+| Navigation _(conditional)_           | [Hyperlink](/components/hyperlink/) instead of a variant button when the action is navigation  |
+| Programmatic focus _(conditional)_     | `ref` on the variant button and `focus()` only when the product must move focus after an action—omit by default  |
+
+**Menu trigger composition** _(conditional)_:
+
+**`Menu.Target`** renders the trigger—do not nest a variant button inside it. Use **`as`** for a different variant. Add **`Menu.Popper`**, **`Menu.Card`**, and **`Menu.List`** per [Menu accessibility](/components/popups/menu/#accessibility).
+
+```tsx
+import {PrimaryButton} from '@workday/canvas-kit-react/button';
+import {Menu} from '@workday/canvas-kit-react/menu';
+
+<Menu>
+  <Menu.Target as={PrimaryButton}>Open</Menu.Target>
+  {/* Menu.Popper, Menu.Card, Menu.List — see Menu accessibility */}
+</Menu>;
+```
 
 **Summary for code generation:**
 
-- **REQUIRED:** variant button with a non-empty accessible name (visible text for text buttons; for
-  icon-only, **`Tooltip`** with `type="label"` preferred, or **`aria-label`** when the spec says not
-  to use a tooltip)
-- **CONDITIONAL:** **`icon`**; icon-only naming; **`disabled`**; **`aria-pressed`** for toggle
-  specs; **`Menu`** for menus; **`Hyperlink`** for navigation; grouping markup; programmatic focus
-  via `ref`
+- **REQUIRED:** variant button with a non-empty accessible name (visible text for text buttons; for icon-only, **`Tooltip`** with `type="label"` preferred, or **`aria-label`** when the spec says not to use a tooltip)
+- **CONDITIONAL:** **`icon`**; icon-only naming; **`disabled`**; **`type="submit"`**; **`Menu`** composition with **`Menu.Target as={…}`**; **`ToolbarIconButton`** / **`aria-pressed`** per toggle row; **`Hyperlink`** for navigation; grouping markup; programmatic focus via `ref`
 
 ### Anti-Patterns
 
 Do **not** generate code that does the following (see **Accessibility Requirements** above for what
 to supply instead):
 
-- Use a `<div>` or `<span>` with `onClick` instead of a variant button—use **`PrimaryButton`**, **`SecondaryButton`**, **`TertiaryButton`**, or **`DeleteButton`** so keyboard and assistive technology get native `<button>` behavior
-- Add `role="button"` on variant buttons—the control is already a `<button>`
-- Use a variant button (or `type="submit"` without an intentional form action) for URL
-  navigation—use
-  [Hyperlink](https://workday.github.io/canvas-kit/?path=/docs/components-hyperlink--docs)
-- Leave icon-only buttons without a name—prefer **`Tooltip`** with `type="label"`, or
-  **`aria-label`** when the spec says not to use a tooltip; do not rely on the icon graphic alone
-- Use **`Tooltip`** with `type="muted"` on icon-only buttons—muted tooltips do not set an accessible
-  name
-- Use **`aria-label`** on icon-only buttons when the spec allows tooltips—prefer **`Tooltip`** with
-  `type="label"` unless the spec explicitly says not to use a tooltip
-- Set `aria-haspopup` or `aria-expanded` on a variant button without **`Menu`**—use
-  **`Menu.Target`** so open state stays in sync with the menu model
-- Set **`aria-pressed`** on one-shot actions (Save, Delete, Open)—see **Toggle pressed state** in the
-  requirements table
-- Use **`SegmentedControl`** for a single option or a lone on/off control—see **Mutually exclusive
-  group** in the requirements table
-- Add `aria-hidden` or change the **`role`** on **`icon`** when visible button text already conveys
-  meaning—Canvas Kit icons are presentational.
-- Use **`aria-disabled`** instead of **`disabled`**—variant buttons map unavailability to the
-  native **`disabled`** attribute
-- Duplicate menu ARIA that **`Menu.Target`** already applies
+- Use a `<div>`, `<span>`, `role="button"`, or other non-`<button>` with `onClick`, or suppress <kbd>Enter</kbd> / <kbd>Space</kbd> on a control that should act as a button—use **`PrimaryButton`**, **`SecondaryButton`**, **`TertiaryButton`**, or **`DeleteButton`** for native keyboard and assistive technology behavior
+- Use a variant button when the action is URL navigation—use [Hyperlink](/components/hyperlink/)
+- Leave icon-only buttons unnamed, rely on the icon alone, use **`Tooltip`** with `type="muted"`, or use **`aria-label`** when the spec allows **`Tooltip`** with `type="label"`—see **Icon-only name**
+- Nest a variant button inside **`Menu.Target`**, or hand-set **`aria-haspopup`** or **`aria-expanded`** when **`Menu.Target`**, **`Expandable.Target`**, or **`Dialog.Target`** owns that state—use **`Menu.Target as={…}`** (and the matching popup docs) instead
+- Set **`aria-pressed`** on one-shot actions (Save, Delete, Open) or on buttons whose visible label changes with state (for example Mute/Unmute)—see **Toggle pressed state**
+- Use **`SegmentedControl`** for a single option or a lone on/off control—see **Mutually exclusive group**
+- Use **`aria-disabled`** instead of native **`disabled`** on variant buttons
 
 ## Component API
 
diff --git a/modules/react/button/stories/button/examples/ThemeOverrides.tsx b/modules/react/button/stories/button/examples/ThemeOverrides.tsx
index 00dd82a2ad..d805d09f7e 100644
--- a/modules/react/button/stories/button/examples/ThemeOverrides.tsx
+++ b/modules/react/button/stories/button/examples/ThemeOverrides.tsx
@@ -4,6 +4,7 @@ import {PrimaryButton} from '@workday/canvas-kit-react/button';
 import {CanvasProvider} from '@workday/canvas-kit-react/common';
 import {Flex} from '@workday/canvas-kit-react/layout';
 import {Heading} from '@workday/canvas-kit-react/text';
+import {Tooltip} from '@workday/canvas-kit-react/tooltip';
 import {createStyles} from '@workday/canvas-kit-styling';
 import {
   caretDownIcon,
@@ -48,7 +49,9 @@ export const ThemeOverrides = () => (
         <PrimaryButton icon={caretDownIcon} iconPosition="end">
           Primary
         </PrimaryButton>
-        <PrimaryButton aria-label="Related Actions" icon={relatedActionsVerticalIcon} />
+        <Tooltip title="Related Actions">
+          <PrimaryButton icon={relatedActionsVerticalIcon} />
+        </Tooltip>
       </Flex>
     </CanvasProvider>
     <Heading size="medium" as="h3">
@@ -63,7 +66,9 @@ export const ThemeOverrides = () => (
         <PrimaryButton icon={caretDownIcon} iconPosition="end">
           Primary
         </PrimaryButton>
-        <PrimaryButton aria-label="Related Actions" icon={relatedActionsVerticalIcon} />
+        <Tooltip title="Related Actions">
+          <PrimaryButton icon={relatedActionsVerticalIcon} />
+        </Tooltip>
       </Flex>
     </div>
   </div>
diff --git a/modules/react/collection/index.ts b/modules/react/collection/index.ts
index 8755e17acd..e8b1724ade 100644
--- a/modules/react/collection/index.ts
+++ b/modules/react/collection/index.ts
@@ -19,7 +19,12 @@ export * from './lib/useListItemRemoveOnDeleteKey';
 export * from './lib/focusOnCurrentCursor';
 export * from './lib/listItemRemove';
 export * from './lib/isElementDisabled';
-export {ListBox, type ListBoxProps, listBoxContainerStencil} from './lib/ListBox';
+export {
+  ListBox,
+  type ListBoxProps,
+  listBoxContainerPartSelector,
+  listBoxContainerStencil,
+} from './lib/ListBox';
 export {keyboardEventToCursorEvents} from './lib/keyUtils';
 export {
   singleSelectionManager,
diff --git a/modules/react/collection/lib/ListBox.tsx b/modules/react/collection/lib/ListBox.tsx
index b810249cae..65072bd583 100644
--- a/modules/react/collection/lib/ListBox.tsx
+++ b/modules/react/collection/lib/ListBox.tsx
@@ -51,6 +51,9 @@ export const useListBox = createElemPropsHook(useListModel)(model => {
   };
 });
 
+/** Selector for `listBoxContainerStencil.parts.listBoxContainer` for use in other stencils' `base` rules. */
+export const listBoxContainerPartSelector = '[data-part="list-box-container"]';
+
 export const listBoxContainerStencil = createStencil({
   parts: {
     listBoxContainer: 'list-box-container',
diff --git a/modules/react/menu/lib/MenuCard.tsx b/modules/react/menu/lib/MenuCard.tsx
index ebf7fbf6e9..f7e671d8b9 100644
--- a/modules/react/menu/lib/MenuCard.tsx
+++ b/modules/react/menu/lib/MenuCard.tsx
@@ -1,7 +1,7 @@
 import * as React from 'react';
 
 import {Card} from '@workday/canvas-kit-react/card';
-import {listBoxContainerStencil} from '@workday/canvas-kit-react/collection';
+import {listBoxContainerPartSelector} from '@workday/canvas-kit-react/collection';
 import {
   ExtractProps,
   cornerShapeStencil,
@@ -51,10 +51,10 @@ export const menuCardStencil = createStencil({
     '.wd-no-animation &': {
       animation: 'none',
     },
-    [`&:where(:has(${listBoxContainerStencil.parts.listBoxContainer.selector}))`]: {
+    [`&:where(:has(${listBoxContainerPartSelector}))`]: {
       overflow: 'hidden',
     },
-    [`& :where(${listBoxContainerStencil.parts.listBoxContainer.selector})`]: {
+    [`& :where(${listBoxContainerPartSelector})`]: {
       // slightly smaller border radius
       borderRadius: system.legacy.shape.lg,
       // Card is a flex column container. Without this, a flex child won't shrink below its