@workday/canvas-kit-docs 16.2.0-0622-next.0 → 16.2.0-0634-next.0

package/dist/es6/lib/specs.js

@@ -6667,7 +6667,7 @@ module.exports = {specifications: [
               },
               {
                 "type": "it",
-                "name": "should not show the \"More\" button"
+                "name": "should not show the \"More\" overflow tab"
               },
               {
                 "type": "it",
@@ -6687,7 +6687,7 @@ module.exports = {specifications: [
                     "children": [
                       {
                         "type": "it",
-                        "name": "should focus on the tab panel"
+                        "name": "should move focus out of the tablist to the next focusable (width control)"
                       }
                     ]
                   }
@@ -6703,11 +6703,11 @@ module.exports = {specifications: [
                   },
                   {
                     "type": "it",
-                    "name": "should show the \"More\" button"
+                    "name": "should show the \"More\" overflow tab"
                   },
                   {
                     "type": "it",
-                    "name": "should show only 3 tab items"
+                    "name": "should show visible content tabs plus the More overflow tab"
                   },
                   {
                     "type": "it",
@@ -6719,11 +6719,11 @@ module.exports = {specifications: [
                     "children": [
                       {
                         "type": "describe",
-                        "name": "when the Tab key is pressed",
+                        "name": "when the Right Arrow key is pressed until the More overflow tab",
                         "children": [
                           {
                             "type": "it",
-                            "name": "should focus on the \"More\" button"
+                            "name": "should focus on the \"More\" overflow tab"
                           }
                         ]
                       }
@@ -6731,7 +6731,7 @@ module.exports = {specifications: [
                   },
                   {
                     "type": "describe",
-                    "name": "when the \"More\" button is clicked",
+                    "name": "when the \"More\" overflow tab is clicked",
                     "children": [
                       {
                         "type": "it",
@@ -6751,7 +6751,7 @@ module.exports = {specifications: [
                           },
                           {
                             "type": "it",
-                            "name": "should move focus back to the \"More\" button"
+                            "name": "should move focus to the Sixth Tab"
                           }
                         ]
                       }
@@ -6769,7 +6769,7 @@ module.exports = {specifications: [
                   },
                   {
                     "type": "it",
-                    "name": "should show the \"More\" button"
+                    "name": "should show the \"More\" overflow tab"
                   },
                   {
                     "type": "it",
@@ -6777,11 +6777,11 @@ module.exports = {specifications: [
                   },
                   {
                     "type": "it",
-                    "name": "should show only 1 tab item"
+                    "name": "should show 2 content tabs plus the More overflow tab (3 total)"
                   },
                   {
                     "type": "describe",
-                    "name": "when the \"More\" button is clicked",
+                    "name": "when the \"More\" overflow tab is clicked",
                     "children": [
                       {
                         "type": "it",
@@ -6789,7 +6789,7 @@ module.exports = {specifications: [
                       },
                       {
                         "type": "it",
-                        "name": "should have the second Tab as the first menu item"
+                        "name": "should have the third Tab as the first menu item"
                       }
                     ]
                   }
@@ -6805,7 +6805,7 @@ module.exports = {specifications: [
                   },
                   {
                     "type": "it",
-                    "name": "should show the \"More\" button"
+                    "name": "should show the \"More\" overflow tab"
                   },
                   {
                     "type": "it",
@@ -6813,11 +6813,11 @@ module.exports = {specifications: [
                   },
                   {
                     "type": "it",
-                    "name": "should show no tab items"
+                    "name": "should show only the More overflow tab (1 tab when all content tabs overflow)"
                   },
                   {
                     "type": "describe",
-                    "name": "when the \"More\" button is clicked",
+                    "name": "when the \"More\" overflow tab is clicked",
                     "children": [
                       {
                         "type": "it",
@@ -6825,7 +6825,7 @@ module.exports = {specifications: [
                       },
                       {
                         "type": "it",
-                        "name": "should have the third Tab as the first menu item"
+                        "name": "should have focus on the first menu item (First Tab)"
                       }
                     ]
                   }
@@ -6837,7 +6837,7 @@ module.exports = {specifications: [
                 "children": [
                   {
                     "type": "it",
-                    "name": "should not show the \"More\" button"
+                    "name": "should not show the \"More\" overflow tab"
                   },
                   {
                     "type": "it",

package/dist/es6/lib/stackblitzFiles/packageJSONFile.js

@@ -18,11 +18,11 @@ export const packageJSONFile = `{
     "@emotion/react": "11.11.4",
     "@types/react": "18.2.60",
     "@types/react-dom": "18.2.19",
-    "@workday/canvas-kit-labs-react": "16.1.5",
-    "@workday/canvas-kit-preview-react": "16.1.5",
-    "@workday/canvas-kit-react": "16.1.5",
-    "@workday/canvas-kit-react-fonts": "^16.1.5",
-    "@workday/canvas-kit-styling": "16.1.5",
+    "@workday/canvas-kit-labs-react": "16.1.8",
+    "@workday/canvas-kit-preview-react": "16.1.8",
+    "@workday/canvas-kit-react": "16.1.8",
+    "@workday/canvas-kit-react-fonts": "^16.1.8",
+    "@workday/canvas-kit-styling": "16.1.8",
     "@workday/canvas-system-icons-web": "^5.0.3",
     "@workday/canvas-expressive-icons-web": "1.0.1",
     "@workday/canvas-tokens-web": "4.4.0-beta.11"

package/dist/es6/lib/stackblitzFiles/packageJSONFile.ts

@@ -19,11 +19,11 @@ export const packageJSONFile = `{
     "@emotion/react": "11.11.4",
     "@types/react": "18.2.60",
     "@types/react-dom": "18.2.19",
-    "@workday/canvas-kit-labs-react": "16.1.5",
-    "@workday/canvas-kit-preview-react": "16.1.5",
-    "@workday/canvas-kit-react": "16.1.5",
-    "@workday/canvas-kit-react-fonts": "^16.1.5",
-    "@workday/canvas-kit-styling": "16.1.5",
+    "@workday/canvas-kit-labs-react": "16.1.8",
+    "@workday/canvas-kit-preview-react": "16.1.8",
+    "@workday/canvas-kit-react": "16.1.8",
+    "@workday/canvas-kit-react-fonts": "^16.1.8",
+    "@workday/canvas-kit-styling": "16.1.8",
     "@workday/canvas-system-icons-web": "^5.0.3",
     "@workday/canvas-expressive-icons-web": "1.0.1",
     "@workday/canvas-tokens-web": "4.4.0-beta.11"

package/dist/mdx/API_PATTERN_GUIDELINES.mdx

@@ -13,7 +13,7 @@ Some of the below rules are inspired by painpoints we've encountered in this pro
 - [Patterns](#patterns)
   - [Event Handlers](#event-handlers-1)
   - [Grow Interface](#grow-interface)
-  - [Input Provider](#input-provider)
+  - [Focus indicators](#focus-indicators)
   - [Prop Spread Behavior](#prop-spread-behavior)
   - [Controlled Components](#controlled-components)
   - [Accessibility](#accessibility)
@@ -135,22 +135,18 @@ If objects are desired, the keys follow these rules:
 - Then use the `grow` boolean prop in your styles to achieve the desired effect (e.g.
   `width: grow ? '100%' : undefined`)
 
-#### Input Provider
+#### Focus indicators
 
-- All Canvas Kit components should support an `InputProvider` component to provide the cleanest
-  experience for mouse users. Read the docs
-  [here](https://github.com/Workday/canvas-kit/tree/master/modules/core/react#input-provider).
-- Do not use `InputProvider` within your components. It is meant to be used only once in your
-  application. It does not require wrapping any children
-- Make sure you provide fully accessible styling by default, and only override for mouse usage.
--
+- Visible focus indicators are required by default. Use **`:focus-visible`** so browser heuristics
+  show the ring for keyboard (and other non-pointer) focus. Pair it with a `&.focus` class twin for
+  Chromatic / `StaticStates` visual testing.
+- Do **not** use `data-whatinput` or `InputProvider` — those were removed in v14. Never remove
+  `outline` on `:focus` without a `:focus-visible` replacement.
 
 ```tsx
-[`[data-whatinput='mouse'] &:focus,
-  [data-whatinput='touch'] &:focus,
-  [data-whatinput='pointer'] &:focus`]: {
-  outline: 'none',
-  border: 'none',
+'&:is(.focus, :focus-visible)': {
+  outline: `2px solid ${system.legacy.color.brand.border.primary}`,
+  outlineOffset: '-2px',
 },
 ```
 

package/dist/mdx/preview-react/tabs/examples/OverflowTabs.tsx

@@ -3,6 +3,7 @@ import React from 'react';
 import {Tabs, useTabsModel} from '@workday/canvas-kit-preview-react/tabs';
 import {Box} from '@workday/canvas-kit-react/layout';
 import {SegmentedControl} from '@workday/canvas-kit-react/segmented-control';
+import {Heading} from '@workday/canvas-kit-react/text';
 import {px2rem} from '@workday/canvas-kit-styling';
 import {system} from '@workday/canvas-tokens-web';
 
@@ -42,13 +43,17 @@ export default () => {
           </Tabs.Menu.Popper>
           <Tabs.Panels>
             {(item: MyTabItem) => (
-              <Tabs.Panel cs={{marginBlockStart: system.gap.lg}}>{item.contents}</Tabs.Panel>
+              <Tabs.Panel tabIndex={-1} cs={{marginBlockStart: system.gap.lg}}>
+                {item.contents}
+              </Tabs.Panel>
             )}
           </Tabs.Panels>
         </Tabs>
       </Box>
       <hr />
-      <h4>Change Tabs container size</h4>
+      <Heading size="small" as="h4">
+        Change Tabs container size
+      </Heading>
       <SegmentedControl onSelect={data => setContainerWidth(data.id)}>
         <SegmentedControl.List aria-label="container width control">
           <SegmentedControl.Item data-id="100%">100%</SegmentedControl.Item>

package/dist/mdx/react/action-bar/ActionBar.mdx

@@ -1,10 +1,11 @@
 import {ExampleCodeBlock, SymbolDoc} from '@workday/canvas-kit-docs';
 import Basic from './examples/Basic';
-import Icons from './examples/Icons';
 import DeleteAction from './examples/DeleteAction';
+import Icons from './examples/Icons';
 import OverflowActionBar from './examples/OverflowActionBar';
 import OverflowActionBarCustomButtonCount from './examples/OverflowActionBarCustomButtonCount';
 
+
 # Canvas Kit Action Bar
 
 Action Bar is a [compound component](/get-started/for-developers/documentation/compound-components/)
@@ -71,13 +72,144 @@ You can change it from the default of 3 to any number greater than 1 and less th
 
 ## Accessibility
 
-Grouping the actions into an HTML `<section>` element with an `aria-label` string is recommended.
-This can be useful for helping screen reader users quickly jump down to the actions at the bottom of
-a page.
+The primary accessibility goal is a clearly named group of page-level actions where every action is
+a native, keyboard-operable button. Use Action Bar for the primary and secondary actions of a page
+or task. For a single action, use a [Button](/components/buttons/button/#accessibility) directly.
+For a dense set of icon or dropdown controls that behaves as one tab stop, use
+[Toolbar](https://workday.github.io/canvas-kit/?path=/docs/components-buttons-toolbar--docs). For
+actions that open a task flow, compose [Modal](/components/popups/modal/#accessibility) or
+[Dialog](/components/popups/dialog/#accessibility) from an **`ActionBar.Item`**.
+
+See the [Menu Button pattern (APG)](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/), the
+[Button pattern (APG)](https://www.w3.org/WAI/ARIA/apg/patterns/button/), and the Canvas Kit
+[Accessibility overview](https://workday.github.io/canvas-kit/?path=/docs/guides-accessibility-overview--docs).
+
+### Minimum Accessible Structure
+
+The following matches the [Basic Example](#basic-example): an **`ActionBar.List`** rendered as a
+labelled `section`, with a primary action first and secondary actions after it. **`ActionBar.List`**
+and **`ActionBar.Item`** should always be inside **`ActionBar`**.
+
+```tsx
+import {ActionBar} from '@workday/canvas-kit-react/action-bar';
+import {PrimaryButton} from '@workday/canvas-kit-react/button';
+
+<ActionBar>
+  <ActionBar.List as="section" aria-label="Page actions">
+    <ActionBar.Item as={PrimaryButton} onClick={() => console.log('first action')}>
+      First Action
+    </ActionBar.Item>
+    <ActionBar.Item>Second Action</ActionBar.Item>
+  </ActionBar.List>
+</ActionBar>;
+```
 
-Refer to [Button](/components/buttons/button/#accessibility) and
-[Menus](/components/popups/menu/#accessibility) for more information about accessibiliy of these
-components in the Action Bar.
+Provide a translated, descriptive **`aria-label`** on **`ActionBar.List`**. Every
+**`ActionBar.Item`** needs non-empty visible text, which becomes its accessible name.
+
+### Built-in Behaviors
+
+Canvas Kit applies these automatically. **Do not duplicate them** in consuming code.
+
+**ARIA and DOM** (_applied by hooks/subcomponents_):
+
+- **`ActionBar`**: Does not render an element. It creates the model and wraps its children in
+  **`Menu`** so the overflow menu shares state.
+- **`ActionBar.List`**: Renders a `div` by default. It has no role of its own—use `as="section"`
+  with **`aria-label`** to expose a landmark. It is positioned fixed to the bottom of the viewport
+  unless you override `position`.
+- **`ActionBar.Item`**: Renders a native `<button>` through **`SecondaryButton`** (or the component
+  passed to `as`). It inherits the [Button accessibility](/components/buttons/button/#accessibility)
+  behavior, including visible label wiring and decorative `icon` handling.
+- **Overflow**: Items that do not fit, or that exceed `maximumVisible`, receive `aria-hidden`,
+  `inert`, and `disabled`, so they are removed from the tab order and the accessibility tree and
+  appear in the overflow menu instead.
+- **`ActionBar.OverflowButton`**: Renders a **`SecondaryButton`** with the related-actions icon,
+  `aria-haspopup`, and `aria-expanded` through the **`Menu.Target`**. It is `aria-hidden` with
+  `tabIndex={-1}` while no items overflow, and gains `tabIndex={0}` once items overflow.
+- **`ActionBar.Menu`**: Is the standard [Menu](/components/popups/menu/#accessibility).
+  **`ActionBar.Menu.List`** has `role="menu"` labelled by the overflow button, and
+  **`ActionBar.Menu.Item`** has `role="menuitem"` with roving `tabIndex`.
+
+**Focus** (_applied by the model_):
+
+- Opening the overflow menu moves focus to its first item.
+- Selecting an item closes the menu.
+- Closing the menu (Escape, outside click, or selection) returns focus to **`ActionBar.OverflowButton`**.
+
+**Keyboard**:
+
+| Key                                                   | Behavior                                                                                                                                                 |
+| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd>      | Moves between each visible **`ActionBar.Item`** and the overflow button. Every visible item is its own tab stop; Action Bar does not use roving tabindex |
+| <kbd>Enter</kbd> / <kbd>Space</kbd>                   | Activates the focused item, or opens the overflow menu                                                                                                   |
+| <kbd>ArrowDown</kbd> / <kbd>ArrowUp</kbd>             | Opens the overflow menu from the overflow button                                                                                                         |
+| <kbd>ArrowDown</kbd> / <kbd>ArrowUp</kbd> inside menu | Moves between overflow menu items                                                                                                                        |
+| <kbd>Escape</kbd>                                     | Closes the overflow menu and returns focus to the overflow button                                                                                        |
+| <kbd>Tab</kbd> inside menu                            | Closes the menu and moves focus to the next focusable element on the page                                                                                |
+
+**Screen reader expectations** (_when built-in behaviors are used as intended_):
+
+- On entering the group, the landmark is announced with the **`aria-label`** (for example, "Page
+  actions, region").
+- Each visible item is announced by its text and role (for example, "First Action, button").
+- The overflow button is announced with its **`aria-label`** and as a menu button with expanded or
+  collapsed state (for example, "More actions, menu button, collapsed").
+- Items moved into the overflow menu are no longer announced as buttons in the bar. They are
+  announced as menu items when the menu is open.
+
+### Accessibility Requirements
+
+Required in application code for an accessible Action Bar. Rows marked _(conditional)_ apply only
+when the situation matches—otherwise omit.
+
+**If no design spec is provided:** render **`ActionBar`** → **`ActionBar.List`** with `as="section"`
+and a translated **`aria-label`**, one primary **`ActionBar.Item`** first, followed by secondary
+**`ActionBar.Item`** components with visible text. Omit `icon`, `disabled`, the overflow API, custom
+`maximumVisible`, and custom `data-id` unless the spec requires them.
+
+| Requirement                          | How to satisfy                                                                                                                                                                                                           |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Group label                          | `as="section"` and a translated **`aria-label`** on **`ActionBar.List`** that is unique among landmarks on the page                                                                                                      |
+| Item accessible name                 | Non-empty visible text as the child of every **`ActionBar.Item`**                                                                                                                                                        |
+| Composition order                    | **`ActionBar`** → **`ActionBar.List`** → **`ActionBar.Item`**; add **`ActionBar.Menu`** as a sibling of **`ActionBar.List`** for overflow                                                                                |
+| Primary action _(conditional)_       | **`as={PrimaryButton}`** on only the first **`ActionBar.Item`**; secondary actions use the default; do not use **`TertiaryButton`**                                                                                      |
+| Destructive action _(conditional)_   | **`as={DeleteButton}`** only for destructive actions, per design                                                                                                                                                         |
+| Decorative icon _(conditional)_      | **`icon`** on **`ActionBar.Item`** with visible text—no extra ARIA on the icon                                                                                                                                           |
+| Overflow button name _(conditional)_ | Translated **`aria-label`** on **`ActionBar.OverflowButton`** (required by its type), passed through **`overflowButton`** on **`ActionBar.List`**                                                                        |
+| Overflow menu _(conditional)_        | Dynamic API: `items` on **`useActionBarModel`**, render props on both **`ActionBar.List`** and **`ActionBar.Menu.List`**, and **`ActionBar.Menu.Popper`** → **`Card`** → **`List`** → **`Item`** with the same item text |
+| Menu item activation _(conditional)_ | The same `onClick` handler on **`ActionBar.Item`** and its **`ActionBar.Menu.Item`** counterpart so an action behaves the same wherever it renders                                                                       |
+| Fixed placement _(conditional)_      | **`ActionBar.List`** is `position: fixed` at the bottom of the viewport. Reserve space so page content and focused controls are not hidden behind it, or pass `position="relative"` when the bar sits in the page flow   |
+| Disabled action _(conditional)_      | Native **`disabled`** on **`ActionBar.Item`** when the spec marks the action unavailable                                                                                                                                 |
+
+**Summary for code generation:**
+
+- **REQUIRED:** **`ActionBar.List`** with `as="section"` and a translated **`aria-label`**; every
+  **`ActionBar.Item`** with visible text; one primary action first
+- **CONDITIONAL:** **`icon`**; **`DeleteButton`**; **`overflowButton`** with an **`aria-label`**;
+  matching **`ActionBar.Menu`** items and handlers; `position="relative"`; **`disabled`**
+
+### Anti-Patterns
+
+Do **not** generate code that does the following (see **Accessibility Requirements** above for what
+to supply instead):
+
+- Omit `as="section"` or **`aria-label`** on **`ActionBar.List`**, which leaves the group
+  unidentifiable to screen reader users
+- Reuse the same **`aria-label`** for **`ActionBar.List`** and another landmark on the page
+- Use more than one **`PrimaryButton`** or any **`TertiaryButton`** in an Action Bar
+- Render **`ActionBar.Item`** without visible text or as a non-button element with `onClick`
+- Add `role="toolbar"`, `role="group"`, roving tabindex, or arrow-key handlers to
+  **`ActionBar.List`**—each item must be a separate tab stop
+- Render **`ActionBar.OverflowButton`** without **`aria-label`**
+- Set `aria-haspopup`, `aria-expanded`, or `aria-hidden` on **`ActionBar.OverflowButton`** or
+  **`ActionBar.Item`**—the model sets them
+- Hide overflowing items with CSS, `hidden`, or conditional rendering—use the dynamic API
+  and `maximumVisible`
+- Use the overflow behavior with static children—it requires `items` on the model and render props
+- Provide an overflow menu whose items differ in text or behavior from the action bar items
+- Move focus manually after the overflow menu closes—**`Menu`** returns focus to the overflow button
+- Leave the fixed **`ActionBar.List`** covering page content or focused controls
 
 ## Component API
 

package/dist/mdx/react/button/button/Button.mdx

@@ -113,47 +113,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
 

package/dist/mdx/react/tabs/examples/OverflowTabs.tsx

@@ -3,6 +3,7 @@ import React from 'react';
 import {Box} from '@workday/canvas-kit-react/layout';
 import {SegmentedControl} from '@workday/canvas-kit-react/segmented-control';
 import {Tabs, useTabsModel} from '@workday/canvas-kit-react/tabs';
+import {Heading} from '@workday/canvas-kit-react/text';
 import {px2rem} from '@workday/canvas-kit-styling';
 import {system} from '@workday/canvas-tokens-web';
 
@@ -43,13 +44,17 @@ export default () => {
           </Tabs.Menu.Popper>
           <Tabs.Panels>
             {(item: MyTabItem) => (
-              <Tabs.Panel cs={{marginBlockStart: system.gap.lg}}>{item.contents}</Tabs.Panel>
+              <Tabs.Panel tabIndex={-1} cs={{marginBlockStart: system.gap.lg}}>
+                {item.contents}
+              </Tabs.Panel>
             )}
           </Tabs.Panels>
         </Tabs>
       </Box>
       <hr />
-      <h4>Change Tabs container size</h4>
+      <Heading size="small" as="h4">
+        Change Tabs container size
+      </Heading>
       <SegmentedControl onSelect={data => setContainerWidth(data.id)}>
         <SegmentedControl.List aria-label="container width control">
           <SegmentedControl.Item data-id="100%">100%</SegmentedControl.Item>