@primer/react-brand 0.77.1-rc.bd5b9efe → 0.78.0-rc.85e39cb4

package/docs/components/ActionMenu/index.md

@@ -29,6 +29,23 @@ import {ActionMenu} from '@primer/react-brand'
 </ActionMenu>
 ```
 
+### Icon button trigger-only
+
+Use `ActionMenu.IconButton` when a familiar icon clearly communicates that contextual actions are available. Always provide a concise, context-specific `aria-label`, which also supplies content for the visible tooltip.
+
+Prefer `ActionMenu.Button` when the icon would be ambiguous without a visible label.
+
+```jsx
+<ActionMenu>
+  <ActionMenu.IconButton icon={KebabHorizontalIcon} aria-label="File actions" />
+  <ActionMenu.Overlay aria-label="File actions">
+    <ActionMenu.Item value="Copy link">Copy link</ActionMenu.Item>
+    <ActionMenu.Item value="Rename file">Rename file</ActionMenu.Item>
+    <ActionMenu.Item value="Move to archive">Move to archive</ActionMenu.Item>
+  </ActionMenu.Overlay>
+</ActionMenu>
+```
+
 ### Single selection
 
 In single selection mode it is important to apply an `aria-label` to the
@@ -62,28 +79,43 @@ render(<App />)
 
 ### Split-button layout
 
-In this `mode`, the `ActionMenu` can be shown as a split button with an action (left) and dropdown button (right) with an additional list of actions.
+In this `mode`, the `ActionMenu` can be shown as a split button with an action on the left and a dropdown button with additional actions on the right.
+
+The primary action may use a visible label or a familiar icon. For an icon-only primary action, ensure that its `aria-label` names the action, while the required `ActionMenu.Overlay` label names the generated menu trigger.
 
 ```jsx
-<ActionMenu mode="split-button">
-  <ActionMenu.Button variant="subtle" as="a" href="#location-for-link" leadingVisual={<StarIcon />}>
-    Action 1
-  </ActionMenu.Button>
-  <ActionMenu.Overlay aria-label="Alternative actions">
-    <ActionMenu.Item as="a" href="#location-for-link" leadingVisual={<StarIcon />}>
+<Stack direction="horizontal" alignItems="center" gap="condensed">
+  <ActionMenu mode="split-button">
+    <ActionMenu.Button variant="subtle" as="a" href="#location-for-link" leadingVisual={<StarIcon />}>
       Action 1
-    </ActionMenu.Item>
-    <ActionMenu.Item as="a" href="#location-for-link-2" leadingVisual={<StarIcon />}>
-      Action 2
-    </ActionMenu.Item>
-    <ActionMenu.Item as="a" href="#location-for-link-3" leadingVisual={<StarIcon />}>
-      Action 3
-    </ActionMenu.Item>
-    <ActionMenu.Item as="a" href="#location-for-link-4" leadingVisual={<StarIcon />}>
-      Action 4
-    </ActionMenu.Item>
-  </ActionMenu.Overlay>
-</ActionMenu>
+    </ActionMenu.Button>
+    <ActionMenu.Overlay aria-label="Alternative actions">
+      <ActionMenu.Item as="a" href="#location-for-link" leadingVisual={<StarIcon />}>
+        Action 1
+      </ActionMenu.Item>
+      <ActionMenu.Item as="a" href="#location-for-link-2" leadingVisual={<StarIcon />}>
+        Action 2
+      </ActionMenu.Item>
+      <ActionMenu.Item as="a" href="#location-for-link-3" leadingVisual={<StarIcon />}>
+        Action 3
+      </ActionMenu.Item>
+      <ActionMenu.Item as="a" href="#location-for-link-4" leadingVisual={<StarIcon />}>
+        Action 4
+      </ActionMenu.Item>
+    </ActionMenu.Overlay>
+  </ActionMenu>
+  <ActionMenu mode="split-button">
+    <ActionMenu.IconButton as="a" href="#new-document" icon={PlusIcon} aria-label="Create document" />
+    <ActionMenu.Overlay aria-label="Creation options">
+      <ActionMenu.Item as="a" href="#new-document">
+        New document
+      </ActionMenu.Item>
+      <ActionMenu.Item as="a" href="#upload-file">
+        Upload file
+      </ActionMenu.Item>
+    </ActionMenu.Overlay>
+  </ActionMenu>
+</Stack>
 ```
 
 ### Sizes
@@ -135,6 +167,20 @@ In this `mode`, the `ActionMenu` can be shown as a split button with an action (
 | `onClick`       | `(event: MouseEvent) => void`          | `undefined` | `false`  | Handles activation of the button                 |
 | `leadingVisual` | `ReactElement`                         | `undefined` | `false`  | Renders a leading visual before the button label |
 
+### ActionMenu.IconButton
+
+| name               | type                          | default       | required | description                                                   |
+| ------------------ | ----------------------------- | ------------- | -------- | ------------------------------------------------------------- |
+| `icon`             | `Icon`                        |               | `true`   | Icon that represents the menu trigger                         |
+| `aria-label`       | `string`                      |               | `true`   | Action-oriented accessible label and visible tooltip text     |
+| `as`               | `ElementType`                 | `'button'`    | `false`  | Element rendered for the primary action                       |
+| `href`             | `string`                      | `undefined`   | `false`  | Link destination when the primary action renders as an anchor |
+| `variant`          | `IconButtonVariants`          | `'secondary'` | `false`  | Sets the icon button styling variation                        |
+| `description`      | `string`                      | `undefined`   | `false`  | Supplies supplementary tooltip text                           |
+| `tooltipDirection` | `TooltipDirection`            | `'s'`         | `false`  | Preferred direction for the automatic tooltip                 |
+| `rounded`          | `boolean`                     | `false`       | `false`  | Uses a fully rounded shape                                    |
+| `onClick`          | `(event: MouseEvent) => void` | `undefined`   | `false`  | Handles activation; toggles the menu only in default mode     |
+
 ### ActionMenu.Overlay `Required`
 
 | name         | type           | default | required | description                                                      |

package/docs/components/ButtonGroup/index.md

@@ -8,10 +8,12 @@ keywords: ['buttons', 'control', 'action', 'group', 'paired']
 
 ## Usage
 
-Use button group to group a set of actions that are related between them or to a single application. E,g, "Log in" and "Sign up" or "Try it out" and "Learn more".
+Use a button group for actions that are related to each other or to a single task, such as “Log in” and “Sign up” or “Try it out” and “Learn more.”
 
 Use button group to display a pair of primary and a secondary actions. The primary button is used for the main call to action while the secondary button is a related, less important action.
 
+Join controls when they represent closely related peer actions with equal hierarchy. Icon-only actions must use a familiar symbol and have a concise, action-oriented accessible name.
+
 **✅ Do**
 
 ![](https://github.com/primer/brand/assets/6951037/c69ae38e-819b-4e03-9b92-665a479f188a)
@@ -52,11 +54,12 @@ _Don't stack the buttons horizontally when there's not enough space to avoid tex
 
 ### Size
 
-The button group component has two sizes: `medium` and `large`. The `medium` size should be used for most cases. The `large` size should be used when the button group is used in large headings that introduces a page, as in the [Hero](../Hero/index.md) component.
+Use the default size in most cases. Use the smallest size in compact toolbars and the largest size alongside prominent page introductions.
 
 ## Related components
 
-- [Button](../Button/index.md): To display a button that performs an action.
-- Link: To display a link that navigates to another page.
-- [Hero](../Hero/index.md): To display a large heading and a description with a button group.
-- [CTA banner](../CTABanner/index.md): To draw attention to or create urgency around a user action.
+- [Button](../Button/index.md): To display an action with a visible label.
+- [Icon button](../IconButton/index.md): To display a familiar icon-only action with an accessible name.
+- Link: To navigate to another page.
+- [Hero](../Hero/index.md): To introduce a page with a large heading, description, and actions.
+- [CTA banner](../CTABanner/index.md): To draw attention to or create urgency around an action.

package/docs/components/ButtonGroup/react.md

@@ -8,7 +8,7 @@ storybook: '/brand/storybook/?path=/story/components-buttongroup--playground'
 ---
 
 ```js
-import {ActionMenu, Button, ButtonGroup} from '@primer/react-brand'
+import {ActionMenu, Button, ButtonGroup, IconButton} from '@primer/react-brand'
 ```
 
 ## Examples
@@ -24,9 +24,28 @@ This is the default variant for the ButtonGroup component. The first item in the
 </ButtonGroup>
 ```
 
+### Joined buttons and icon buttons
+
+Set `variant="joined"` to connect any number of `Button` and `IconButton` children. Joined controls use the `secondary` variant by default so they share one visual hierarchy; explicit child variants override that default.
+
+```jsx
+<Stack direction="vertical" alignItems="flex-start" gap="condensed">
+  <ButtonGroup variant="joined">
+    <Button>Previous</Button>
+    <Button>Today</Button>
+    <Button>Next</Button>
+  </ButtonGroup>
+  <ButtonGroup variant="joined">
+    <IconButton icon={DownloadIcon} aria-label="Download" />
+    <IconButton icon={ShareIcon} aria-label="Share" />
+    <IconButton icon={KebabHorizontalIcon} aria-label="More actions" />
+  </ButtonGroup>
+</Stack>
+```
+
 ### Action menus
 
-`ButtonGroup` supports up to two `Button` or `ActionMenu` children and applies a default `variant` to each one.
+The default ButtonGroup variant supports up to two children and applies `primary` to the first action and `secondary` to the second. Joined groups support any number of `Button` and `IconButton` children. `ActionMenu` is supported only by the default variant.
 
 Explicit `variant` overrides to `Button` or `ActionMenu.Button` will override the default values.
 
@@ -75,7 +94,8 @@ The `Button` component can render as a `button` or `a` HTML element. By default,
 
 ### ButtonGroup
 
-| Name         | Type                             |   Default  | Description                             |
-| :----------- | :------------------------------- | :--------: | :-------------------------------------- |
-| `buttonSize` | `'small' \| 'medium' \| 'large'` | `'medium'` | The size variations available in Button |
-| `buttonsAs`  | `'button' \| 'a'`                | `'button'` | The HTML variations available in Button |
+| Name         | Type                             |   Default   | Description                             |
+| :----------- | :------------------------------- | :---------: | :-------------------------------------- |
+| `buttonSize` | `'small' \| 'medium' \| 'large'` |  `'medium'` | The size variations available in Button |
+| `buttonsAs`  | `'button' \| 'a'`                |  `'button'` | The HTML variations available in Button |
+| `variant`    | `ButtonGroupVariants`            | `'default'` | The visual presentation of the group    |

package/docs/components/IconButton/index.md

@@ -0,0 +1,99 @@
+---
+title: Icon button
+description: Use an icon button to represent an action with an Octicon instead of a visible text label.
+keywords: ['action', 'button', 'control', 'icon', 'interactive']
+ready: true
+---
+
+## Usage
+
+Icon buttons represent an action with an [Octicon](https://primer.style/octicons) instead of a visible text label. Always choose a familiar Octicon whose meaning is clear in context. Otherwise, use a [button](../Button/index.md) with a visible text label.
+
+Every icon button displays a tooltip on hover and keyboard focus. The tooltip repeats the accessible label by default, helping users confirm the action before activating it.
+
+**✅ Do**
+
+_Use an Octicon that clearly represents the action._
+
+**❌ Don't**
+
+_Don't pair a familiar Octicon with an unrelated action._
+
+## Labels
+
+Every icon button needs a concise name that describes what happens when someone activates it. Begin with a clear verb when possible, such as Search, Share, Close, or Delete item.
+
+Describe the action rather than the icon's appearance. Keep supplementary tooltip text short and non-essential.
+
+**✅ Do**
+
+_Describe the action the button performs._
+
+**❌ Don't**
+
+_Don't describe the icon's appearance._
+
+## Hierarchy and emphasis
+
+Use the default visual appearance for most icon buttons. Only use the stronger accent colors for the highest-priority action in a group.
+
+Reserve danger styling for destructive actions. The icon and accessible name must still communicate the destructive outcome without relying on color alone.
+
+Use the invisible appearance only when the surrounding interface already provides enough structure and the control remains discoverable in every interaction state.
+
+## Grouping
+
+Join closely related peer actions so their relationship is visually clear. Keep unrelated actions separate and provide enough space between their targets.
+
+**✅ Do**
+
+_Join closely related icon buttons into one group._
+
+**❌ Don't**
+
+_Don't separate icon buttons that represent one related set of actions._
+
+## Shape
+
+Icon buttons are available in two shapes, with square the default.
+
+Use the standard square shape for most use-cases. Use a rounded shape only when it matches an established interaction pattern, such as sending a chat message or advancing through media quickly.
+
+Keep shape consistent among related controls. Do not use shape alone to communicate an action's meaning or state.
+
+**✅ Do**
+
+_Use a consistent shape for related icon buttons._
+
+**❌ Don't**
+
+_Don't mix shapes unless the difference communicates an established pattern._
+
+## Loading
+
+Show progress in place when an action takes time to complete. Keep focus on the control, prevent repeated activation, and announce that work is in progress. Use a specific announcement when the surrounding context does not make the operation clear.
+
+**✅ Do**
+
+_Replace the Octicon with a loading indicator while the action is in progress._
+
+**❌ Don't**
+
+_Don't use only disabled styling to communicate that an action is in progress._
+
+## Accessibility
+
+- Give every icon button an accessible name, even when the icon seems self-explanatory.
+- Ensure the name describes the action and remains accurate when the button's state changes.
+- Keep the tooltip available on both pointer hover and keyboard focus.
+- Ensure the control has a visible focus indicator.
+- Maintain at least a 24x24 pixel target size and provide enough spacing from nearby controls.
+- Treat the Octicon as decorative because the accessible name communicates the purpose.
+- Do not rely on color, shape, or iconography alone to communicate state.
+
+## Related components
+
+- [Button](../Button/index.md): For actions with a visible text label.
+- [Button group](../ButtonGroup/index.md): For a set of closely related actions.
+- [Tooltip](../Tooltip/index.md): For guidance on concise labels and supplementary information.
+- [Octicons](https://primer.style/octicons): For the icon library used by icon buttons.

package/docs/components/IconButton/react.md

@@ -0,0 +1,189 @@
+---
+title: Icon button
+description: Use an icon button to represent an action with an Octicon instead of a visible text label.
+keywords: ['action', 'button', 'control', 'icon', 'interactive']
+ready: true
+a11yReviewed: false
+source: https://github.com/primer/brand/blob/main/packages/react/src/IconButton/IconButton.tsx
+storybook: '/brand/storybook/?path=/story/components-iconbutton--playground'
+---
+
+```js
+import {IconButton} from '@primer/react-brand'
+```
+
+## Examples
+
+### Default
+
+```jsx
+<IconButton icon={HeartIcon} aria-label="Favorite" />
+```
+
+### Variants
+
+IconButton inherits standard variants from Button and adds `danger` and `invisible` variants.
+
+```jsx
+<Stack direction={{narrow: 'vertical', regular: 'horizontal'}}>
+  <IconButton icon={HeartIcon} aria-label="Favorite" variant="primary" />
+  <IconButton icon={HeartIcon} aria-label="Favorite" variant="secondary" />
+  <IconButton icon={HeartIcon} aria-label="Favorite" variant="subtle" />
+  <IconButton icon={TrashIcon} aria-label="Delete item" variant="danger" />
+  <IconButton icon={HeartIcon} aria-label="Favorite" variant="invisible" />
+</Stack>
+```
+
+### Sizes
+
+```jsx
+<Stack direction="horizontal" alignItems="center">
+  <IconButton icon={SearchIcon} aria-label="Search" size="small" />
+  <IconButton icon={SearchIcon} aria-label="Search" size="medium" />
+  <IconButton icon={SearchIcon} aria-label="Search" size="large" />
+</Stack>
+```
+
+### Rounded
+
+Use `rounded` for circular controls, such as a chat submit action.
+
+```jsx
+<IconButton rounded icon={ArrowUpIcon} aria-label="Send message" variant="primary" />
+```
+
+### In a `ButtonGroup`
+
+Use `variant="joined"` to display related `IconButton` components.
+
+```jsx
+<ButtonGroup variant="joined">
+  <IconButton icon={DownloadIcon} aria-label="Download" />
+  <IconButton icon={ShareIcon} aria-label="Share" />
+  <IconButton icon={KebabHorizontalIcon} aria-label="More actions" />
+</ButtonGroup>
+```
+
+### In a toolbar
+
+Use small icon buttons for familiar actions in compact toolbars.
+
+```jsx filename="noinline"
+const App = () => {
+  const {isMedium} = useWindowSize()
+
+  return (
+    <Box padding="condensed" backgroundColor="subtle" borderRadius="medium">
+      <Stack direction="horizontal" alignItems="center" gap="condensed">
+        {isMedium !== false && (
+          <FormControl fullWidth>
+            <FormControl.Label visuallyHidden>Search files</FormControl.Label>
+            <TextInput type="search" size="small" leadingVisual={<SearchIcon />} placeholder="Search files" fullWidth />
+          </FormControl>
+        )}
+        <Stack direction="horizontal" alignItems="center" gap={4} padding="none">
+          <ActionMenu mode="split-button" size="small">
+            <ActionMenu.IconButton as="a" href="#new-project" icon={PlusIcon} aria-label="Create project" />
+            <ActionMenu.Overlay aria-label="Creation options">
+              <ActionMenu.Item as="a" href="#new-project">
+                New project
+              </ActionMenu.Item>
+              <ActionMenu.Item as="a" href="#upload-files">
+                Upload files
+              </ActionMenu.Item>
+            </ActionMenu.Overlay>
+          </ActionMenu>
+          <IconButton size="small" icon={ShareIcon} aria-label="Share workspace" />
+          <IconButton size="small" icon={InboxIcon} aria-label="Open notifications" />
+          <Avatar size={32} src="/images/avatar-mona.png" alt="Mona profile" />
+        </Stack>
+      </Stack>
+    </Box>
+  )
+}
+
+render(<App />)
+```
+
+### In an `ActionMenu`
+
+Use an icon button as the trigger when a familiar icon clearly communicates that contextual actions are available. The menu label also supplies the accessible name for the generated menu trigger.
+
+```jsx
+<Stack direction="horizontal" alignItems="center" gap="condensed">
+  <ActionMenu>
+    <ActionMenu.IconButton icon={KebabHorizontalIcon} aria-label="File actions" />
+    <ActionMenu.Overlay aria-label="File actions">
+      <ActionMenu.Item value="Copy link">Copy link</ActionMenu.Item>
+      <ActionMenu.Item value="Rename file">Rename file</ActionMenu.Item>
+      <ActionMenu.Item value="Move to archive">Move to archive</ActionMenu.Item>
+    </ActionMenu.Overlay>
+  </ActionMenu>
+  <ActionMenu mode="split-button">
+    <ActionMenu.IconButton as="a" href="#new-document" icon={PlusIcon} aria-label="Create document" />
+    <ActionMenu.Overlay aria-label="Creation options">
+      <ActionMenu.Item as="a" href="#new-document">
+        New document
+      </ActionMenu.Item>
+      <ActionMenu.Item as="a" href="#upload-file">
+        Upload file
+      </ActionMenu.Item>
+    </ActionMenu.Overlay>
+  </ActionMenu>
+</Stack>
+```
+
+### Description
+
+Use `description` to add supplementary information to the tooltip while keeping `aria-label` as the action name.
+
+```jsx
+<IconButton icon={InboxIcon} aria-label="Notifications" description="You have unread notifications" />
+```
+
+### Delayed tooltip
+
+Wrap IconButton in Tooltip with `delay="long"` when familiar controls appear in a dense group and immediate pointer tooltips would be distracting. Keyboard focus remains immediate.
+
+```jsx
+<Tooltip text="Favorite" delay="long">
+  <IconButton icon={HeartIcon} aria-label="Favorite" />
+</Tooltip>
+```
+
+### Loading
+
+```jsx
+<IconButton loading loadingAnnouncement="Saving favorite" icon={HeartIcon} aria-label="Favorite" />
+```
+
+### Inactive
+
+Inactive controls use the same muted style for every variant and retain focus and activation so they can explain why an action is unavailable. They render with `aria-disabled="true"` and must not perform their normal action.
+
+```jsx
+<IconButton
+  inactive
+  icon={HeartIcon}
+  aria-label="Favorite"
+  description="Favorites are temporarily unavailable"
+  onClick={() => window.alert('Favorites are temporarily unavailable. Try again later.')}
+/>
+```
+
+## Component props
+
+| Name                  | Type                 |    Default    | Required | Description                                                                             |
+| :-------------------- | :------------------- | :-----------: | :------: | :-------------------------------------------------------------------------------------- |
+| `icon`                | `Icon`               |               |  `true`  | Octicon component rendered in the center of the button                                  |
+| `aria-label`          | `string`             |               |  `true`  | Required non-empty accessible action name and default tooltip label                     |
+| `variant`             | `IconButtonVariants` | `'secondary'` |  `false` | Button variants plus IconButton-only `danger` and `invisible` variations                |
+| `size`                | `IconButtonSizes`    |   `'medium'`  |  `false` | Control sizes inherited from Button                                                     |
+| `description`         | `string`             |  `undefined`  |  `false` | Supplementary tooltip description                                                       |
+| `tooltipDirection`    | `TooltipDirections`  |     `'s'`     |  `false` | Preferred tooltip direction                                                             |
+| `inactive`            | `boolean`            |    `false`    |  `false` | Applies variant-independent muted styling while preserving input for required feedback  |
+| `loading`             | `boolean`            |    `false`    |  `false` | Replaces the icon with a loading indicator and blocks activation without removing focus |
+| `loadingAnnouncement` | `string`             |  `'Loading'`  |  `false` | Polite live-region message announced while loading                                      |
+| `rounded`             | `boolean`            |    `false`    |  `false` | Renders the control with a fully circular shape                                         |
+| `disabled`            | `boolean`            |    `false`    |  `false` | Disables the control using Button's native or polymorphic behavior                      |
+| `as`                  | `React.ElementType`  |   `'button'`  |  `false` | Element rendered by Button; provide `href` when rendering an anchor                     |

package/docs/components/SubNav/index.md

@@ -45,6 +45,37 @@ import {SubNav} from '@primer/react-brand'
 </div>
 ```
 
+### Localized menu controls
+
+Internal `SubNav` labels such as the "More" link are rendered in `en` by default. Use `menuLabels` to customize these to different locales.
+
+```jsx
+<div style={{position: 'relative', height: 360, width: '100%'}}>
+  <SubNav
+    menuLabels={{
+      menuLabel: 'Menú de navegación',
+      closeLabel: 'Cerrar menú de navegación',
+      activeLabel: 'Menú de navegación. Página actual:',
+      closeActiveLabel: 'Cerrar menú de navegación. Página actual:',
+      overflowMenuLabel: 'Más',
+    }}
+  >
+    <SubNav.Heading href="#">AI</SubNav.Heading>
+    <SubNav.SubHeading href="#">GitHub Copilot</SubNav.SubHeading>
+    <SubNav.Link href="#">Aplicación de escritorio</SubNav.Link>
+    <SubNav.Link href="#" aria-current="page">
+      Copilot en VS Code
+    </SubNav.Link>
+    <SubNav.Link href="#">Agentes en GitHub</SubNav.Link>
+    <SubNav.Link href="#">Copilot CLI</SubNav.Link>
+    <SubNav.Link href="#">Revisión de código de Copilot</SubNav.Link>
+    <SubNav.Link href="#">Para empresas</SubNav.Link>
+    <SubNav.Link href="#">Tutoriales</SubNav.Link>
+    <SubNav.Link href="#">Planes y precios</SubNav.Link>
+  </SubNav>
+</div>
+```
+
 ### Optional CTA
 
 ```jsx
@@ -72,7 +103,7 @@ Submenus appear as a dropdown by default.
     <SubNav.Heading href="#">Features</SubNav.Heading>
     <SubNav.Link href="#" aria-current="page">
       Actions
-      <SubNav.SubMenu>
+      <SubNav.SubMenu aria-label="Actions submenu">
         <SubNav.Link href="#">Actions feature one</SubNav.Link>
         <SubNav.Link href="#">Actions feature two</SubNav.Link>
         <SubNav.Link href="#">Actions feature three</SubNav.Link>
@@ -116,9 +147,22 @@ Ensure that the text of each `SubNav.Link` within the anchor-based submenu fits
 
 ### SubNav `Required`
 
-| name        | type      | default | required | description                                                                   |
-| ----------- | --------- | ------- | -------- | ----------------------------------------------------------------------------- |
-| `fullWidth` | `boolean` | `false` | `false`  | Allows the SubNav to be used at full width, removing default internal padding |
+| name         | type                        | default        | required | description                                                                   |
+| ------------ | --------------------------- | -------------- | -------- | ----------------------------------------------------------------------------- |
+| `fullWidth`  | `boolean`                   | `false`        | `false`  | Allows the SubNav to be used at full width, removing default internal padding |
+| `menuLabels` | `Partial<SubNavMenuLabels>` | English labels | `false`  | Customizes the menu's accessible labels                                       |
+
+`SubNavMenuLabels` is exported from `@primer/react-brand`.
+
+#### Menu labels
+
+| Field               | Type     | English default                        | Purpose                                                                       |
+| ------------------- | -------- | -------------------------------------- | ----------------------------------------------------------------------------- |
+| `menuLabel`         | `string` | `Navigation menu`                      | Accessible label while the narrow menu is closed                              |
+| `closeLabel`        | `string` | `Close navigation menu`                | Accessible label while the narrow menu is open                                |
+| `activeLabel`       | `string` | `Navigation menu. Current page:`       | Complete prefix while the narrow menu is closed and a current page is present |
+| `closeActiveLabel`  | `string` | `Close navigation menu. Current page:` | Complete prefix while the narrow menu is open and a current page is present   |
+| `overflowMenuLabel` | `string` | `More`                                 | Visible and accessible label for the desktop overflow menu                    |
 
 ### SubNav.Heading `Required`
 
@@ -150,7 +194,8 @@ Ensure that the text of each `SubNav.Link` within the anchor-based submenu fits
 
 ### SubNav.SubMenu
 
-| name       | type                    | default     | required | description                           |
-| ---------- | ----------------------- | ----------- | -------- | ------------------------------------- |
-| `children` | `SubNav.Link`           |             | `false`  | Container for submenu links           |
-| `variant`  | `SubNavSubMenuVariants` | `'default'` | `false`  | Alternative presentation for submenus |
+| name         | type                    | default                      | required | description                                                                                                       |
+| ------------ | ----------------------- | ---------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
+| `children`   | `SubNav.Link`           |                              | `false`  | Container for submenu links                                                                                       |
+| `variant`    | `SubNavSubMenuVariants` | `'default'`                  | `false`  | Alternative presentation for submenus                                                                             |
+| `aria-label` | `string`                | `'Sub navigation'` (content) | `false`  | Complete accessible name for the submenu toggle and content; names the navigation landmark for the anchor variant |

package/docs/components/SubdomainNavBar/index.md

@@ -288,5 +288,7 @@ render(<LocalizedMenu />)
 | `className`  | `string`          |         | Applies a custom class                                   |
 | `href`       | `string`          |         | Destination path for the anchor element                  |
 | `isExternal` | `boolean`         | `false` | Renders an external-link icon after the link when `true` |
+| `rel`        | `string`          |         | Sets the relationship between the current page and link  |
+| `target`     | `string`          |         | Sets where the linked document opens                     |
 
-Additional props are passed to the wrapping `<li>` element. [See MDN for accepted list item attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/li#attributes).
+The `target` and `rel` props are passed to the rendered anchor. Other additional props are passed to the wrapping `<li>` element.

package/docs/components/Tooltip/index.md

@@ -23,7 +23,8 @@ import {Tooltip} from '@primer/react-brand'
 
 ### Custom direction
 
-By default, tooltips appear below the element. You can change the direction by passing the `direction` prop with a value of `n`, `e`, `s`, or `w`.
+By default, tooltips appear below the element. You can change the direction by passing the `direction` prop with a cardinal or diagonal direction.
+Supported values are `n`, `ne`, `e`, `se`, `s`, `sw`, `w`, and `nw`.
 
 As long as there is enough room in the viewport, the tooltip will appear in the specified direction. If there is not enough room, the tooltip will appear in whatever direction it can place the tooltip without overflowing the viewport.
 
@@ -33,29 +34,39 @@ As long as there is enough room in the viewport, the tooltip will appear in the
 </Tooltip>
 ```
 
-### Substitute a visible label
+### Delay
 
-If a ubiquitously understood icon is used in place of a text label, you can use the `type` to provide a text label for assistive technologies such as screen readers.
+Tooltips use a short pointer delay by default to avoid appearing while the pointer passes over a trigger. Use `medium` or `long` for groups of familiar controls where immediate tooltips would be distracting. Keyboard focus always opens the tooltip immediately.
+
+```jsx
+<Tooltip text="Sample tooltip content" delay="long">
+  <Button>Long delay</Button>
+</Tooltip>
+```
+
+### With an icon button
+
+Use `IconButton` when a familiar Octicon can replace a visible text label. Its required `aria-label` provides the accessible name and automatically appears in a tooltip on hover and keyboard focus, so it does not need to be wrapped in `Tooltip`.
 
 Use this with caution. It is generally better to use a visible label for better usability and accessibility.
 
 ```jsx
-<Tooltip text="Go fullscreen" type="label">
-  <Button>
-    <ScreenFullIcon />
-  </Button>
-</Tooltip>
+<IconButton icon={ScreenFullIcon} aria-label="Go fullscreen" />
 ```
 
+For other custom icon-only controls, use `type="label"` to make the tooltip text the trigger's accessible name.
+
 ## Component props
 
-| name        | type                       | default         | required | description                                                                                                                                                                                                |
-| ----------- | -------------------------- | --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `direction` | `'n' \| 'e' \| 's' \| 'w'` | `'s'`           | `false`  | The side the tooltip appears on                                                                                                                                                                            |
-| `text`      | `string`                   | `undefined`     | `true`   | The text to be displayed in the tooltip                                                                                                                                                                    |
-| `type`      | `'description' \| 'label'` | `'description'` | `false`  | The type of tooltip. `label` is used for labelling the element that triggers tooltip. `description` is used for describing or adding a supplementary information to the element that triggers the tooltip. |
+| name        | type                       | default         | required | description                                                                                                                                                                              |
+| ----------- | -------------------------- | --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `direction` | `TooltipDirections`        | `'s'`           | `false`  | The side the tooltip appears on                                                                                                                                                          |
+| `delay`     | `TooltipDelays`            | `'short'`       | `false`  | Pointer hover delay: `short` (50ms), `medium` (400ms), or `long` (1200ms). Keyboard focus is immediate.                                                                                  |
+| `text`      | `string`                   | `undefined`     | `true`   | The text to be displayed in the tooltip                                                                                                                                                  |
+| `type`      | `'description' \| 'label'` | `'description'` | `false`  | The tooltip's semantic relationship to its trigger. `label` provides the accessible name, while `description` provides supplementary information alongside the trigger's existing label. |
 
 ## Related components
 
 - Popover: For displaying more complex interactive content that appears when triggered
 - [Button](../Button/index.md): Often used in conjunction with tooltips
+- [Icon button](../IconButton/index.md): For familiar icon-only actions with automatic tooltips