@acronis-platform/ui-react 3.0.0 → 4.1.0

package/dist/llms/dialog.md

@@ -0,0 +1,403 @@
+# Dialog
+
+> A higher-level "recipe" dialog built on top of the DialogRoot primitive parts. A single `variant` prop selects one of seven canned use-cases (default, rename, save changes, reset password, discard changes, accept, read-only) — each with its own title, body copy and footer buttons — plus a legacy `wide` escape hatch (no Figma preset, free-form footer via the `footer` prop) kept for backward compatibility with pre-Figma call sites. `children` overrides the body slot and `hasLoading` shows a `Loading` overlay. Colors, typography, and container/header/footer geometry resolve to the `--ui-dialog-*`/`--ui-footer-*` token tier (see tokens.yaml). In Figma the matching component set is named "DialogDefault"; the code-facing name is `Dialog`.
+
+**Status:** draft · **Category:** overlays · **Since:** v0.58.0
+
+## Import
+
+```tsx
+import { Dialog } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<Dialog
+  variant="discard changes"
+  open={open}
+  onOpenChange={setOpen}
+  onPrimaryAction={() => { discard(); setOpen(false); }}
+/>
+
+{/* Override the body slot */}
+<Dialog variant="default" defaultOpen>
+  <p>Any custom content.</p>
+</Dialog>
+
+{/* Interpolate the real object name into the canned title/body */}
+<Dialog variant="rename" objectName="Q3 Report.xlsx" open onOpenChange={setOpen} />
+
+{/* Hide the header and/or footer chrome (beyond the Figma contract) */}
+<Dialog hasHeader={false} open>
+  <p>Body-only content — no title bar, no close button.</p>
+</Dialog>
+
+{/* Legacy wide variant — free-form footer, kept for backward compatibility */}
+<Dialog variant="wide" size="large" title="Configure discovery agent" open
+  footer={<>
+    <DialogClose render={<Button variant="ghost">Cancel</Button>} />
+    <Button>Configure</Button>
+  </>}
+/>
+```
+
+A higher-level "recipe" dialog built on top of the DialogRoot primitive parts.
+One `variant` prop selects a ready-made title, body copy and footer for the
+seven most common dialog use-cases, so product code doesn't reassemble the
+same `DialogRoot` + `DialogHeader` + `DialogFooter` boilerplate each time. In
+Figma the matching component set is named "DialogDefault"; the code-facing
+name is `Dialog`.
+
+> **Status: draft.** Container/header/footer geometry and color resolve to the
+> `--ui-dialog-*`/`--ui-footer-*` token tier (reconciled against the Figma
+> "DialogDefault" node). `size="large"` (832px) is the one exception — a legacy
+> backward-compatibility value with no matching token. See `tokens.yaml`.
+
+## When to use
+
+- One of the seven canned use-cases fits: `default`, `rename`, `save changes`,
+  `reset password`, `discard changes`, `accept`, `read-only`.
+- You want a consistent confirmation/decision dialog without hand-composing the
+  DialogRoot parts.
+- You have a legacy call site that needs a wider popup and fully custom footer
+  buttons — use `variant="wide"` (see below). This is a backward-compatibility
+  escape hatch, not a recommended pattern for new work.
+- You need a body-only dialog with no title bar and/or no action bar — set
+  `hasHeader`/`hasFooter` to `false`. Both default to `true`; this is beyond
+  the strict Figma contract (all seven canned variants always show both).
+
+## When not to use
+
+- You need a bespoke layout or extra parts none of the seven variants (or the
+  `wide` escape hatch) cover — this is a gap to raise with the design system
+  team (the underlying `DialogRoot` primitive is internal-only, not a public
+  escape hatch).
+- For transient, non-blocking feedback — use a toast.
+- For contextual hints anchored to an element — use a tooltip or popover.
+
+## Variants
+
+| Variant           | Title              | Footer                                    |
+| ----------------- | ------------------ | ----------------------------------------- |
+| `default`         | Dialog title       | Cancel · Label                            |
+| `rename`          | Rename object name | Cancel · Rename (body: text field)        |
+| `save changes`    | Save changes       | Go back · Save                            |
+| `reset password`  | Reset password     | Cancel · Reset                            |
+| `discard changes` | Discard changes    | Go back · **Confirm** (destructive)       |
+| `accept`          | Accept object name | Cancel · Accept                           |
+| `read-only`       | License agreement  | Done (single primary action)              |
+| `wide`            | (caller-supplied)  | Free-form, via `footer` — no Figma preset |
+
+`rename`, `discard changes`, and `accept`'s canned title/body embed a generic
+"object name" placeholder — pass `objectName` to interpolate the real name
+(e.g. a file name) instead of overriding `title`/`children` by hand.
+
+## Parts
+
+| Part              | Element (default)  | Purpose                                              |
+| ----------------- | ------------------ | ---------------------------------------------------- |
+| `container`       | `div[role=dialog]` | The portaled, centered popup card.                   |
+| `header`          | `div`              | Top bar; title + close button.                       |
+| `title`           | `h2`               | Accessible dialog name (`aria-labelledby`).          |
+| `close-button`    | `button`           | Icon button that dismisses the dialog.               |
+| `body`            | `div`              | Variant copy or the `children` override.             |
+| `footer`          | `div`              | Right-aligned action bar; or the free-form `footer`. |
+| `loading-overlay` | `div`              | Spinner scrim shown while `hasLoading`.              |
+
+## Example
+
+```tsx
+import { Dialog } from '@acronis-platform/ui-react';
+
+// Canned use-case, controlled open state
+<Dialog variant="discard changes" open={open} onOpenChange={setOpen} />;
+
+// Override the body slot (header + footer chrome preserved)
+<Dialog variant="default" defaultOpen>
+  <p>Any custom body content.</p>
+</Dialog>;
+
+// Busy state
+<Dialog variant="save changes" hasLoading open />;
+
+// Localize the canned copy (title/secondaryLabel/primaryLabel/closeLabel all
+// override the variant's default English string)
+<Dialog
+  variant="discard changes"
+  title="Modifications non enregistrées"
+  secondaryLabel="Retour"
+  primaryLabel="Confirmer"
+  closeLabel="Fermer"
+  open
+/>;
+
+// Interpolate the real object name into the rename/discard changes/accept
+// variants' canned title/body, instead of the generic placeholder text
+<Dialog
+  variant="rename"
+  objectName="Q3 Report.xlsx"
+  open
+  onOpenChange={setOpen}
+/>;
+
+// Hide the header and/or footer chrome (beyond the Figma contract)
+<Dialog hasHeader={false} open>
+  <p>Body-only content — no title bar, no close button.</p>
+</Dialog>;
+
+// Legacy wide variant — free-form footer, kept for backward compatibility
+import { Button, DialogClose } from '@acronis-platform/ui-react';
+
+<Dialog
+  variant="wide"
+  size="large"
+  title="Configure discovery agent"
+  open
+  footer={
+    <>
+      <DialogClose render={<Button variant="ghost">Cancel</Button>} />
+      <Button>Configure</Button>
+    </>
+  }
+>
+  <p>The discovery agent will obtain the neighbor IP addresses…</p>
+</Dialog>;
+```
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `variant` | `'default' | 'rename' | 'save changes' | 'reset password' | 'discard changes' | 'accept' | 'read-only' | 'wide'` | `'default'` | no | Selects the canned title, body copy and footer buttons. `discard changes` uses a destructive primary action; `read-only` shows a single primary action (no secondary button). `wide` has no Figma preset — a legacy escape hatch kept for backward compatibility, meant to be paired with `size="large"` and the `footer` prop. |
+| `hasLoading` | `boolean` | `false` | no | Shows a spinner overlay across the body + footer (inset from just below the header to the bottom, or from the very top when `hasHeader` is `false`), and makes both `inert` (unfocusable, unclickable, hidden from assistive tech) so a keyboard user can't activate the obscured footer buttons while busy. |
+| `loadingLabel` | `string` | `'Data is loading…'` | no | Overrides the loading overlay's accessible label. Ignored when `hasLoading` is `false`. |
+| `hasHeader` | `boolean` | `true` | no | Shows the header (title + close button). When `false`, the title is still rendered off-screen so the dialog keeps an accessible name — only the visible bar and close button are omitted. Beyond the strict Figma contract (all seven canned variants always show the header) — a ui-react-only extension, like `wide`/`size="large"`. |
+| `hasFooter` | `boolean` | `true` | no | Shows the footer (action buttons). Beyond the strict Figma contract (all seven canned variants always show the footer) — a ui-react-only extension, like `wide`/`size="large"`. When `false`, `footer` is not rendered either. |
+| `title` | `string` | — | no | Overrides the variant's default title, for localization or copy changes. |
+| `objectName` | `string` | — | no | The real name of the object being acted on (e.g. a file or resource name). Interpolated into the `rename`/`discard changes`/`accept` variants' canned title/body in place of the generic placeholder text (e.g. `rename` → "Rename {objectName}" and the field's prefilled value); ignored by variants that don't reference an object name. |
+| `objectNameLabel` | `string` | `'Object name'` | no | Overrides the accessible name of the `rename` variant's text field. Ignored by every other variant. |
+| `secondaryLabel` | `string` | — | no | Overrides the variant's default secondary (dismiss) button label. Passing this on a variant with no secondary button by default (e.g. `read-only`) also makes the button appear. Ignored when `footer` is provided. |
+| `primaryLabel` | `string` | — | no | Overrides the variant's default primary button label. Ignored when `footer` is provided. |
+| `footer` | `ReactNode` | — | no | Replaces the footer's action content entirely with free-form buttons — the escape hatch the `wide` variant is meant to be paired with, for legacy call sites that don't fit one of the seven canned presets. |
+| `closeLabel` | `string` | `'Close'` | no | Overrides the close button's accessible name. |
+| `open` | `boolean` | — | no | Controlled open state. Pair with the change event. |
+| `default-open` | `boolean` | `false` | no | Initial open state when uncontrolled (React `defaultOpen`). |
+| `modal` | `boolean | 'trap-focus'` | `true` | no | Modal behavior — traps focus and locks background scroll while open. `'trap-focus'` keeps the focus trap but allows background interaction. |
+| `size` | `'sm' | 'large'` | `'sm'` | no | Popup max-width (forwarded to the underlying content). Defaults to `sm` (512px, the Figma-defined size), or to `large` (832px) when `variant` is `wide`. `large` predates the Figma node and has no design token — a legacy backward-compatibility size, not a design-system width scale. |
+| `portal` | `boolean` | `true` | no | Render the content inside a portal (forwarded to the underlying content). Required for correct stacking; disable only when supplying your own portal ancestor. |
+| `keepMounted` | `boolean` | — | no | Keep the content mounted while closed (forwarded to the underlying content's portal). |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `open-change` | `boolean` | Fired when the dialog opens or closes (React: `onOpenChange`). Payload is the new open value. |
+| `primary-action` | `void` | Fired when the primary footer button is clicked (React: `onPrimaryAction`). The dialog does not close automatically afterwards — pair it with the open-change event to close it once the action completes. Ignored when `footer` is provided. |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | Body slot. When provided, it replaces the variant's canned body copy while keeping the header and footer chrome. |
+
+## Behavior
+
+Dialog is a recipe over the DialogRoot primitive: it owns the same `open`
+state and modal focus/scroll management, and adds a `variant`-driven preset for
+the title, body and footer.
+
+### Variants
+
+```gherkin
+Scenario: A variant selects its canned content
+  Given a Dialog with variant = "discard changes"
+  When it opens
+  Then the title reads "Discard changes"
+  And the body asks to confirm discarding changes
+  And the footer shows a "Go back" secondary and a destructive "Confirm"
+```
+
+```gherkin
+Scenario: The rename variant embeds a text field
+  Given a Dialog with variant = "rename"
+  When it opens
+  Then the body renders a text field prefilled with the current name
+```
+
+```gherkin
+Scenario: The read-only variant has a single action
+  Given a Dialog with variant = "read-only"
+  When it opens
+  Then the footer shows only a primary "Done" button (no secondary button)
+```
+
+```gherkin
+Scenario: The wide variant is a free-form escape hatch
+  Given a Dialog with variant = "wide" and a footer override
+  When it opens
+  Then the popup defaults to the large (832px) size
+  And the footer renders exactly the caller-supplied buttons, not a canned
+  secondary/primary pair
+```
+
+### Body slot
+
+```gherkin
+Scenario: Children override the canned body
+  Given a Dialog with children provided
+  When it opens
+  Then the body renders the children instead of the variant's default copy
+  And the header title and footer buttons are unchanged
+```
+
+### Object name interpolation
+
+```gherkin
+Scenario: objectName replaces the generic placeholder
+  Given a Dialog with variant = "rename" and objectName = "Q3 Report.xlsx"
+  When it opens
+  Then the title reads "Rename Q3 Report.xlsx"
+  And the body's text field is prefilled with "Q3 Report.xlsx"
+```
+
+```gherkin
+Scenario: objectName is ignored by variants with no placeholder
+  Given a Dialog with variant = "default" and objectName provided
+  When it opens
+  Then the canned title and body render unchanged
+```
+
+### Footer override
+
+```gherkin
+Scenario: The footer prop replaces the canned buttons
+  Given a Dialog with a footer override provided
+  When it opens
+  Then the footer renders the override content
+  And secondaryLabel/primaryLabel are ignored
+```
+
+### Loading
+
+```gherkin
+Scenario: The loading overlay covers body and footer
+  Given an open Dialog with hasLoading = true
+  Then a spinner overlay is shown from just below the header to the bottom
+  And it is hidden when hasLoading is false
+```
+
+```gherkin
+Scenario: The loading overlay actually blocks interaction, not just the click
+  Given an open Dialog with hasLoading = true
+  Then the body and footer are inert — unfocusable, unclickable, and hidden
+  from assistive tech, not merely visually obscured
+  And the popup carries aria-busy="true"
+  And loadingLabel overrides the overlay's accessible name
+```
+
+### Header and footer optionality
+
+```gherkin
+Scenario: Hiding the header keeps the dialog's accessible name
+  Given a Dialog with hasHeader = false
+  When it opens
+  Then the visible title bar and close button are not rendered
+  And the dialog still has an accessible name (the title renders off-screen)
+```
+
+```gherkin
+Scenario: Hiding the footer removes its actions
+  Given a Dialog with hasFooter = false
+  When it opens
+  Then no secondary/primary/footer-override content is rendered
+```
+
+```gherkin
+Scenario: Hiding both leaves only the body
+  Given a Dialog with hasHeader = false and hasFooter = false
+  When it opens
+  Then only the body content is visible
+  And the dialog still has an accessible name
+```
+
+```gherkin
+Scenario: The loading overlay adapts to a hidden header
+  Given a Dialog with hasHeader = false and hasLoading = true
+  When it opens
+  Then the spinner overlay covers from the very top of the popup, not from
+  below a (non-existent) header
+```
+
+### Opening & closing
+
+```gherkin
+Scenario: Dismissing via the secondary button
+  Given an open Dialog with a secondary button
+  When the user activates it
+  Then the dialog closes and open-change(false) fires
+```
+
+```gherkin
+Scenario: Dismissing with the keyboard
+  Given an open modal Dialog
+  When the user presses Escape
+  Then the dialog closes and open-change(false) fires
+```
+
+```gherkin
+Scenario: Controlled
+  Given a Dialog with a fixed open prop
+  When the user attempts to dismiss it
+  Then internal state does NOT change on its own
+  And open-change fires so the consumer can update the open prop
+```
+
+## Accessibility
+
+Dialog inherits the Base UI Dialog primitive's modal semantics, focus
+management and keyboard handling (via `DialogContent`/`DialogTitle`/
+`DialogClose`). The recipe supplies the accessible name and the action controls.
+
+## Roles & semantics
+
+- The popup (`container`) has `role="dialog"` and `aria-modal="true"` when modal.
+- **Name.** Every variant renders a `DialogTitle`, wired to the popup via
+  `aria-labelledby`, so the dialog always has an accessible name.
+- The close button exposes an accessible name ("Close") via an `sr-only` label
+  alongside the icon, and is present whenever the header is shown (the
+  default). Setting `hasHeader = false` removes the header bar, and with it
+  the close button — the dialog is then dismissed via `Escape` or a
+  caller-supplied action instead.
+- The loading overlay's spinner carries `role="status"` with an accessible name
+  (`loadingLabel`, defaulting to `Loading`'s own `'Data is loading…'`) so the
+  busy state is announced. The popup itself carries `aria-busy="true"`, and the
+  body + footer are made `inert` — not just visually obscured — so a keyboard
+  user cannot tab to or activate the footer buttons while `hasLoading` is set.
+- The `rename` variant's text field has a built-in accessible name
+  (`aria-label="Object name"`) — the field renders without a visible label in
+  the design, so the component supplies the label itself.
+- The `wide` variant's `footer` override is free-form — the caller is
+  responsible for giving each action button an accessible name (e.g. visible
+  label text), the same as any other Button usage.
+
+## Keyboard
+
+- **Tab / Shift+Tab** — focus cycles within the dialog only; the focus trap
+  prevents reaching background content while modal.
+- **Escape** — closes the dialog (fires the change event).
+- On open, focus moves into the dialog; on close, focus returns to the opener.
+
+## Screen reader
+
+- Entering the dialog announces its role and name (title).
+- While modal, background content is inert, so assistive tech stays within the
+  dialog.
+
+## Contrast
+
+- Title and body text use `--ui-text-on-surface-primary`; the idle close icon
+  uses `--ui-text-on-surface-secondary`; both meet WCAG AA against the
+  `--ui-background-surface-secondary` container and `--ui-background-surface-primary`
+  header/footer in light and dark themes. The close button shows a
+  `--ui-focus-primary` ring on keyboard focus.

package/dist/llms/dropdown-menu.md

@@ -0,0 +1,193 @@
+# DropdownMenu
+
+> A menu of actions anchored to a trigger (typically a `ButtonMenu`), opened on demand. Composable parts — trigger, content, group (section), item, shortcut, submenu — built on the Base UI Menu primitive. Themed by the `--ui-button-menu-dropdown-*` token tier from @acronis-platform/tokens-pd.
+
+**Status:** stable · **Category:** overlays · **Since:** v0.14.0
+
+## Import
+
+```tsx
+import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubTrigger, DropdownMenuSubContent, ButtonMenu } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<DropdownMenu>
+  <DropdownMenuTrigger render={<ButtonMenu variant="secondary">Actions</ButtonMenu>} />
+  <DropdownMenuContent>
+    <DropdownMenuGroup>
+      <DropdownMenuItem>
+        Profile <DropdownMenuShortcut>⇧⌘P</DropdownMenuShortcut>
+      </DropdownMenuItem>
+      <DropdownMenuItem>Settings</DropdownMenuItem>
+    </DropdownMenuGroup>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+A menu of actions anchored to a trigger, opened on demand. Composable from
+a set of parts — trigger, content, group (section), item, shortcut, submenu —
+built on the Base UI Menu primitive. Themed by the `--ui-button-menu-dropdown-*`
+token tier from `@acronis-platform/tokens-pd`.
+
+## When to use
+
+- A compact list of **actions** triggered from a `ButtonMenu` (row actions,
+  account menu, "more" overflow).
+
+## When not to use
+
+- For selecting a value into a field — use `InputSelect` / `Select`.
+- For secondary content or a form — use a `Popover`.
+- For primary page navigation — use a nav, not a menu.
+
+## Parts
+
+| Part                                                                    | Element              | Purpose                                            |
+| ----------------------------------------------------------------------- | -------------------- | -------------------------------------------------- |
+| `DropdownMenu`                                                          | — (Root)             | Owns the open state.                               |
+| `DropdownMenuTrigger`                                                   | `button`             | Opens the menu (compose with `ButtonMenu`).        |
+| `DropdownMenuContent`                                                   | `div[role=menu]`     | The portaled, positioned popup.                    |
+| `DropdownMenuGroup`                                                     | `div`                | A section of items (auto border-top on non-first). |
+| `DropdownMenuItem`                                                      | `div[role=menuitem]` | An action row (`inset` to align).                  |
+| `DropdownMenuShortcut`                                                  | `span`               | Right-aligned shortcut hint.                       |
+| `DropdownMenuSub` / `DropdownMenuSubTrigger` / `DropdownMenuSubContent` | —                    | A nested submenu.                                  |
+| `DropdownMenuPortal`                                                    | —                    | Portal wrapper.                                    |
+
+## Example
+
+```tsx
+import {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuGroup,
+  DropdownMenuItem,
+  DropdownMenuShortcut,
+  ButtonMenu,
+} from '@acronis-platform/ui-react';
+
+<DropdownMenu>
+  <DropdownMenuTrigger
+    render={<ButtonMenu variant="secondary">Actions</ButtonMenu>}
+  />
+  <DropdownMenuContent>
+    <DropdownMenuGroup>
+      <DropdownMenuItem>
+        Profile <DropdownMenuShortcut>⇧⌘P</DropdownMenuShortcut>
+      </DropdownMenuItem>
+      <DropdownMenuItem>Settings</DropdownMenuItem>
+    </DropdownMenuGroup>
+  </DropdownMenuContent>
+</DropdownMenu>;
+```
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `open` | `boolean` | — | no | Controlled open state. Pair with the change event. |
+| `default-open` | `boolean` | `false` | no | Initial open state when uncontrolled. |
+| `side` | `'top' | 'bottom' | 'left' | 'right' | 'inline-start' | 'inline-end'` | `'bottom'` | no | On the content — which side of the trigger to render on. |
+| `align` | `'start' | 'center' | 'end'` | — | no | On the content — alignment along the chosen side. |
+| `side-offset` | `number` | `4` | no | On the content — distance in px from the trigger. |
+| `inset` | `boolean` | `false` | no | On an item / submenu-trigger — left-pad to align with rows that have a leading indicator. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `open-change` | `boolean` | Fired when the menu opens or closes (React `onOpenChange`). |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | A `trigger` (typically a `ButtonMenu`) plus the `content` popup of `group`s containing `item`s — optionally with `shortcut` hints and nested submenus (`submenu-trigger` + `submenu-content`). |
+
+## Behavior
+
+DropdownMenu shows a menu of actions anchored to a trigger. It owns the open
+state (or the consumer controls it via `open`).
+
+### Opening & closing
+
+```gherkin
+Scenario: Opening from the trigger
+  Given a closed menu
+  When the user activates the trigger (click / Enter / Space / Arrow)
+  Then the popup opens, focus moves into it, and open-change(true) fires
+```
+
+```gherkin
+Scenario: Selecting an item closes the menu
+  Given an open menu
+  When the user activates an item
+  Then the item's action runs and the menu closes (open-change(false))
+```
+
+```gherkin
+Scenario: Dismissing
+  Given an open menu
+  When the user presses Escape or presses outside the popup
+  Then the menu closes and focus returns to the trigger
+```
+
+### Keyboard
+
+```gherkin
+Scenario: Roving navigation and typeahead
+  Given an open menu
+  When the user presses Arrow keys
+  Then highlight moves between items (data-[highlighted])
+  And typing characters jumps to the matching item
+```
+
+### Submenus
+
+```gherkin
+Scenario: Opening a submenu
+  Given a DropdownMenuSubTrigger
+  When the user highlights it (hover or ArrowRight)
+  Then the submenu (data-[popup-open]) opens beside it
+```
+
+## Accessibility
+
+DropdownMenu leans on the Base UI Menu primitive for the WAI-ARIA menu pattern:
+roles, roving focus, typeahead, and dismissal.
+
+## Roles & semantics
+
+- The trigger exposes `aria-haspopup="menu"` and `aria-expanded`; the popup has
+  `role="menu"`.
+- Items are `role="menuitem"`. The shortcut hint is decorative text inside its
+  item. Groups (`DropdownMenuGroup`) visually section items; non-first groups
+  render a top-border separator.
+
+## Keyboard
+
+- **Enter / Space / Arrow Down** on the trigger opens the menu and moves focus
+  to the first item.
+- **Arrow Up / Down** move the highlight (roving); **Home / End** jump to
+  first / last; **typeahead** jumps to a matching item.
+- **Arrow Right** opens a submenu from its trigger; **Arrow Left** / **Escape**
+  closes it (Escape closes the whole menu from the root and returns focus to the
+  trigger).
+- **Enter / Space** activates the highlighted item.
+- **Focus ring** (`--ui-focus-primary`, 3px inset) appears only on keyboard
+  navigation (`focus-visible:not(:hover)`), not on pointer interaction.
+
+## Screen reader
+
+- Opening announces the menu and its first item ("Profile, menu item 1 of 4").
+
+## Contrast
+
+- The popup uses `--ui-button-menu-dropdown-item-label-color` on
+  `--ui-button-menu-dropdown-container-color` with a
+  `--ui-button-menu-dropdown-container-border-color` border; the highlighted
+  item uses `--ui-button-menu-dropdown-item-container-color-hover`; shortcuts
+  use `--ui-button-menu-dropdown-extras-shortcut-label-color` — all meeting
+  WCAG AA in light and dark.