@acronis-platform/ui-react 3.0.0 → 4.1.0

package/dist/llms/breadcrumb.md

@@ -0,0 +1,326 @@
+# Breadcrumb
+
+> Displays a hierarchical navigation path showing the user's current location. A set of composable parts (list, item, link, current page, separator, ellipsis) — the last item is a non-link current page; chevron separators sit between items.
+
+**Status:** ready · **Category:** navigation · **Since:** v0.6.0
+
+## Import
+
+```tsx
+import { Breadcrumb, BreadcrumbList, BreadcrumbItem, BreadcrumbLink, BreadcrumbPage, BreadcrumbSeparator, BreadcrumbEllipsis } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<Breadcrumb>
+  <BreadcrumbList>
+    <BreadcrumbItem>
+      <BreadcrumbLink render={<Link to="/" />}>Home</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/products">Products</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbPage>Settings</BreadcrumbPage>
+    </BreadcrumbItem>
+  </BreadcrumbList>
+</Breadcrumb>
+```
+
+Displays a hierarchical navigation path showing the user's current location and
+offering quick navigation back through the page hierarchy. Built as a set of
+composable parts so the trail's structure stays explicit in markup.
+
+## When to Use
+
+- Show the user's position in a multi-level navigation hierarchy.
+- Provide quick navigation back to parent pages.
+- Orient users who arrive via deep links or search results.
+
+## When NOT to Use
+
+- **Flat navigation** with no hierarchy — breadcrumbs add no value.
+- **Single-level pages** with no parent to navigate to.
+- **Step-by-step wizards** — use a Stepper.
+- **Sibling/tab navigation** — use Tabs.
+
+## Parts
+
+| Part                  | Element                                | Role                                       |
+| --------------------- | -------------------------------------- | ------------------------------------------ |
+| `Breadcrumb`          | `<nav aria-label="breadcrumb">`        | Navigation landmark wrapping the trail     |
+| `BreadcrumbList`      | `<ol>`                                 | Horizontal, wrapping list of items         |
+| `BreadcrumbItem`      | `<li>`                                 | A single entry                             |
+| `BreadcrumbLink`      | `<a>` (polymorphic via `render`)       | Interactive link to a parent page          |
+| `BreadcrumbPage`      | `<span aria-current="page">`           | The current page (non-link, always last)   |
+| `BreadcrumbSeparator` | `<li aria-hidden>`                     | Divider between items (chevron by default) |
+| `BreadcrumbEllipsis`  | `<span aria-hidden>` + `sr-only` label | Stands in for collapsed middle items       |
+
+## Quick Examples
+
+### React
+
+```tsx
+import {
+  Breadcrumb,
+  BreadcrumbList,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+} from '@acronis-platform/ui-react';
+
+function PageBreadcrumb() {
+  return (
+    <Breadcrumb>
+      <BreadcrumbList>
+        <BreadcrumbItem>
+          <BreadcrumbLink href="/">Home</BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbItem>
+          <BreadcrumbLink href="/products">Products</BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbItem>
+          <BreadcrumbPage>Settings</BreadcrumbPage>
+        </BreadcrumbItem>
+      </BreadcrumbList>
+    </Breadcrumb>
+  );
+}
+```
+
+Render a breadcrumb link as a router link via the `render` prop:
+
+```tsx
+<BreadcrumbLink render={<Link to="/products" />}>Products</BreadcrumbLink>
+```
+
+## Truncation
+
+Truncation is author-driven: collapse the middle items yourself and drop a
+`BreadcrumbEllipsis` (optionally wrapped in a dropdown/menu) in their place. The
+first and last items should stay visible.
+
+## Spec Files
+
+| File               | Contents                                                          |
+| ------------------ | ----------------------------------------------------------------- |
+| `index.yaml`       | Identity, status, category, dependencies, Figma link              |
+| `anatomy.yaml`     | Root, parts, layout, pseudo-states                                |
+| `api.yaml`         | Framework-agnostic contract + framework adapters                  |
+| `tokens.yaml`      | `--ui-breadcrumb-*` token references                              |
+| `behavior.md`      | Given/When/Then behavior scenarios                                |
+| `accessibility.md` | ARIA roles, keyboard map, screen-reader and contrast requirements |
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `render` | `RenderProp` | `undefined` | no | Base UI composition prop on the root and on the link part — replaces the rendered element with another component (e.g. a router `Link`) while merging props and classes. React-only; other frameworks use their own polymorphism (e.g. Vue `<RouterLink>` in the link slot). |
+| `href` | `string` | `undefined` | no | Target URL of the link part. Omit on the current-page part — the last item is plain text, not a link. |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | The composed trail. Author it from the parts: a list wrapping items; each non-final item holds a link followed by a separator; the final item holds the current page. An ellipsis part may stand in for collapsed middle items. |
+
+## Behavior
+
+### Structure
+
+#### Renders a navigation landmark
+
+**Given** a Breadcrumb wrapping a list of items
+**When** the component renders
+**Then** the root is a `<nav>` with `aria-label="breadcrumb"`
+**And** the trail is an `<ol>` of `<li>` items
+
+#### Renders the default chevron separator
+
+**Given** a BreadcrumbSeparator with no children
+**When** it renders
+**Then** a 16px chevron-right icon appears
+**And** the separator is `aria-hidden`
+
+#### Renders a custom separator
+
+**Given** a BreadcrumbSeparator with children (e.g. `"/"`)
+**When** it renders
+**Then** the children replace the default chevron
+**And** no icon is rendered
+
+---
+
+### Current Page
+
+#### Marks the current page
+
+**Given** the last item is a BreadcrumbPage
+**When** the trail renders
+**Then** that element has `aria-current="page"` and `aria-disabled="true"`
+**And** it exposes `role="link"` but carries no `href` (a disabled current-page link)
+**And** no separator follows it
+
+#### Non-final items are interactive links
+
+**Given** a BreadcrumbItem containing a BreadcrumbLink
+**When** the trail renders
+**Then** the item is an interactive link
+**And** it does not carry `aria-current`
+
+---
+
+### Links
+
+#### Underlines on hover
+
+**Given** a BreadcrumbLink
+**When** the pointer hovers it
+**Then** the link text is underlined
+**And** the underline is removed again while the link is pressed (`:active`)
+
+#### Shows a focus-ring on keyboard focus
+
+**Given** a BreadcrumbLink
+**When** it receives keyboard focus
+**Then** it shows a 3px focus-ring (`--ui-focus-primary`) flush to the label
+**And** the link text is not underlined
+
+#### Composes with a router link
+
+**Given** a BreadcrumbLink with `render={<Link to="/" />}`
+**When** it renders
+**Then** the router `Link` is the rendered element
+**And** the breadcrumb link classes and props are merged onto it
+**And** no extra `<a>` wrapper is produced
+
+---
+
+### Truncation (ellipsis)
+
+#### Stands in for collapsed items
+
+**Given** a long trail where middle items are collapsed
+**When** a BreadcrumbEllipsis is placed between the first and last items
+**Then** an ellipsis icon is shown
+**And** it carries an `sr-only` "More" label for assistive tech
+
+> Truncation is author-driven in this composable API: the consumer decides
+> which items to collapse and renders a BreadcrumbEllipsis (optionally wrapping
+> it in a dropdown/menu) in their place. The component does not auto-collapse.
+
+---
+
+### Edge Cases
+
+#### Single item
+
+**Given** a Breadcrumb with only a current page
+**When** it renders
+**Then** the page is shown with `aria-current="page"`
+**And** no separator is rendered
+
+#### Icon inside a link
+
+**Given** a BreadcrumbLink containing an icon and text
+**When** it renders
+**Then** the icon and text sit inline within the link
+
+## Accessibility
+
+Implements the [WAI-ARIA Breadcrumb pattern](https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/).
+
+## ARIA Roles and Attributes
+
+### Root (`nav`)
+
+| Attribute    | Value          | Reason                                                  |
+| ------------ | -------------- | ------------------------------------------------------- |
+| `<nav>`      | —              | Exposes the trail as a navigation landmark              |
+| `aria-label` | `"breadcrumb"` | Distinguishes it from other `nav` landmarks on the page |
+
+### List / items
+
+- The trail is an ordered list (`<ol>`) of `<li>` items — order is meaningful.
+- Link items render a native `<a>` (or the element supplied via `render`).
+
+### Current page (`page` part)
+
+| Attribute       | Value    | Reason                                                         |
+| --------------- | -------- | -------------------------------------------------------------- |
+| `role`          | `"link"` | Exposes the current page as a (disabled) link in the trail     |
+| `aria-current`  | `"page"` | Identifies the current page within the trail                   |
+| `aria-disabled` | `"true"` | Signals the item is not actionable                             |
+| no `href`       | —        | Not navigable; rendered as a `<span>`, so not in the tab order |
+
+### Separator (`separator` part)
+
+| Attribute     | Value            | Reason                                  |
+| ------------- | ---------------- | --------------------------------------- |
+| `role`        | `"presentation"` | Marks the separator as decorative       |
+| `aria-hidden` | `"true"`         | Keeps screen readers from announcing it |
+
+### Ellipsis (`ellipsis` part)
+
+| Attribute     | Value    | Reason                                                           |
+| ------------- | -------- | ---------------------------------------------------------------- |
+| `aria-hidden` | `"true"` | The icon itself is decorative                                    |
+| `sr-only`     | "More"   | Provides an accessible name when collapsed items are represented |
+
+When the ellipsis triggers an interactive menu of hidden items, wrap it in a
+focusable control (e.g. a Button/menu trigger) that carries `aria-expanded`,
+`aria-haspopup`, and an accessible label.
+
+---
+
+## Keyboard Navigation
+
+| Key       | Element         | Action                           |
+| --------- | --------------- | -------------------------------- |
+| Tab       | Breadcrumb link | Moves focus to the next link     |
+| Shift+Tab | Breadcrumb link | Moves focus to the previous link |
+| Enter     | Breadcrumb link | Activates / navigates            |
+
+The current-page item is not a link and is not focusable. Separators are not
+focusable.
+
+---
+
+## Screen Reader Requirements
+
+1. The navigation landmark is announced with its "breadcrumb" label.
+2. Each link item announces its text as a link.
+3. The current page announces with `aria-current="page"`.
+4. Separators are not announced.
+
+---
+
+## Color and Contrast
+
+| Element                         | Minimum Ratio | Standard               |
+| ------------------------------- | ------------- | ---------------------- |
+| Link text vs background         | 4.5:1         | WCAG 1.4.3 (AA)        |
+| Current-page text vs background | 4.5:1         | WCAG 1.4.3 (AA)        |
+| Separator icon vs background    | 3:1           | WCAG 1.4.11 (non-text) |
+| Focus indicator                 | 3:1           | WCAG 1.4.11            |
+
+Links are distinguished by more than color: they underline on hover, and
+keyboard focus shows a 3px focus-ring (`--ui-focus-primary`).
+
+---
+
+## Testing Checklist
+
+- [ ] `<nav aria-label="breadcrumb">` on the root
+- [ ] Trail is an `<ol>` of `<li>` items
+- [ ] Last item is a disabled current-page link (`role="link"`, `aria-current="page"`, `aria-disabled`, no `href`)
+- [ ] Separators are `aria-hidden` / `role="presentation"`
+- [ ] All link items are reachable via Tab; current page is skipped
+- [ ] Ellipsis exposes an accessible "More" name
+- [ ] Link / current-page text meet 4.5:1; focus ring meets 3:1

package/dist/llms/button-group.md

@@ -0,0 +1,298 @@
+# ButtonGroup
+
+> A compact cluster of related icon-only actions sharing a single box, hairline-separated. Two container styles (outlined, inlined) around a variadic list of 32px-tall items.
+
+**Status:** ready · **Category:** actions · **Since:** v0.63.0
+
+## Import
+
+```tsx
+import { ButtonGroup, ButtonGroupItem } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<ButtonGroup aria-label="View mode">
+  <ButtonGroupItem aria-label="List view" onClick={showList}>
+    <ListIcon size={16} />
+  </ButtonGroupItem>
+  <ButtonGroupItem aria-label="Grid view" onClick={showGrid}>
+    <GridIcon size={16} />
+  </ButtonGroupItem>
+  <ButtonGroupItem aria-label="Table view" disabled>
+    <TableIcon size={16} />
+  </ButtonGroupItem>
+</ButtonGroup>
+
+{/* Borderless, for a surface that already has its own chrome */}
+<ButtonGroup aria-label="Zoom" variant="inlined">
+  <ButtonGroupItem aria-label="Zoom out"><MinusIcon size={16} /></ButtonGroupItem>
+  <ButtonGroupItem aria-label="Zoom in"><PlusIcon size={16} /></ButtonGroupItem>
+</ButtonGroup>
+```
+
+A compact cluster of related icon-only actions sharing a single box, separated
+by hairlines. Two container styles — `outlined` (bordered, 4px radius) and
+`inlined` (no chrome of its own) — around a variadic list of 32px-tall items.
+
+## When to use
+
+- Two to about five **related** icon actions that belong together and read as
+  one control: a view switcher (list / grid / table), zoom in / zoom out,
+  text alignment, a map's pan / fit / reset cluster.
+- A dense surface — a table header, a chart toolbar, a card's corner — where
+  separate buttons would waste space and read as unrelated.
+- Use `inlined` when the group sits inside something that already draws a
+  border, so you don't double up on chrome.
+
+## When not to use
+
+- **Persistent selection** — a group where one option stays visibly chosen
+  (a segmented control). This component's `active` fill is transient
+  activation feedback and releases; use a toggle group, whose items expose
+  `aria-pressed`.
+- **Unrelated actions** placed side by side. The shared box and separators
+  claim the actions are one unit; separate `ButtonIcon`s say they aren't.
+- **Labelled actions.** The design is icon-only (32px tall, 12px inline
+  padding). For text actions in a row, use `Toolbar` or plain `Button`s.
+- **A single action** — use `ButtonIcon`.
+- **A long or overflowing list** of actions. This group neither scrolls nor
+  collapses; `Toolbar`'s action list handles overflow into a "More" menu.
+
+## Example (React — implemented)
+
+```tsx
+import { ButtonGroup, ButtonGroupItem } from '@acronis-platform/ui-react';
+
+<ButtonGroup aria-label="View mode">
+  <ButtonGroupItem aria-label="List view" onClick={showList}>
+    <ListIcon size={16} />
+  </ButtonGroupItem>
+  <ButtonGroupItem aria-label="Grid view" onClick={showGrid}>
+    <GridIcon size={16} />
+  </ButtonGroupItem>
+  <ButtonGroupItem aria-label="Table view" disabled>
+    <TableIcon size={16} />
+  </ButtonGroupItem>
+</ButtonGroup>;
+```
+
+Vue and Web Component implementations are planned and will target the same
+contract — see `api.yaml` `adapters`.
+
+## Parts
+
+| Part        | Element    | Notes                                                                                             |
+| ----------- | ---------- | ------------------------------------------------------------------------------------------------- |
+| container   | `div`      | `role="toolbar"`. Owns the border/radius (`outlined` only) and clips its children to that radius. |
+| `item`      | `button`   | One action. Icon-only; needs its own `aria-label`. Polymorphic via `render`.                      |
+| `icon`      | `svg`      | The item's glyph — sized to 16px, tinted through `currentColor`.                                  |
+| `separator` | _(border)_ | The item's inline-end border, dropped on the last item. Not an element, so not in the a11y tree.  |
+
+## Notes
+
+- **Accessible names are on you.** The container takes no default `aria-label`
+  (a generic one would be unlocalizable noise), and icon-only items have no text
+  to name them. Label both. See `accessibility.md`.
+- **Position is normally not a prop.** Figma models item position as an `order`
+  variant (first / middle / last), but it only selects whether the trailing
+  separator is drawn — derived here from `:last-child`, so the group stays
+  variadic and you never restate the DOM order. `order` exists as an **optional
+  escape hatch** for the one case that derivation cannot survive: wrapping each
+  item in another element makes every button a `:last-child` and erases every
+  separator. Pass it there, and nowhere else.
+- **One Tab stop.** The group follows the WAI-ARIA toolbar pattern: Tab enters
+  and leaves, the arrow keys move between items. Home/End are unsupported (a
+  Base UI limitation).
+- **RTL-safe.** The separator is an inline-end border, so it mirrors under
+  `dir="rtl"` with no extra work.
+- **No disabled design.** Figma defines no disabled state for this component,
+  so a disabled item dims its glyph to the shared
+  `--ui-glyph-on-surface-disabled` semantic token. Worth revisiting if design
+  ships a dedicated token.
+- **Disabled items stay focusable**, unlike elsewhere in this library — the arrow
+  keys land on them and they are marked `aria-disabled` rather than natively
+  disabled. That is required, not preference: a natively disabled _first_ item
+  would take the whole group out of the tab order. See `accessibility.md`.
+- **Not a segmented control.** The `active` fill is transient activation
+  feedback, not selection, and Figma defines no selected state. For one option
+  that stays visibly chosen, use a toggle group.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `variant` | `'outlined' | 'inlined'` | `'outlined'` | no | Container style, on the container part. `outlined` draws the 1px border and 4px radius around the cluster; `inlined` draws neither, for a group sitting inside a surface that already provides its own chrome. Items are unaffected — including their separators. |
+| `disabled` | `boolean` | `false` | no | Disables interaction. On an item it disables that action; on the container it disables every item in the group. A disabled item keeps its idle fill and dims its glyph to the shared disabled glyph token. Per the WAI-ARIA toolbar pattern it stays focusable (exposed as `aria-disabled`, not the native disabled attribute) so it remains discoverable, while click and Enter/Space activation are suppressed. |
+| `order` | `'first' | 'middle' | 'last'` | `undefined` | no | On an item: its position in the group, mirroring the Figma `order` variant. Controls exactly one thing — whether the trailing separator is drawn (`last` omits it). Leave it unset in normal use; position is derived from the item's own position in the DOM. Pass it only when each item is wrapped in another element, which defeats that derivation and would otherwise erase every separator. |
+| `loop-focus` | `boolean` | `true` | no | On the container: whether arrow-key navigation wraps from the last item back to the first (and vice versa) instead of stopping at the ends. |
+| `render` | `RenderProp` | `undefined` | no | Base UI composition prop on the container and the item — replaces the rendered element with another component while merging props and classes. Pass `native-button: false` alongside it when the item renders something other than a real `<button>`, so the button semantics are supplied by the component. React-only; other frameworks use their own polymorphism. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `click` | `MouseEvent` | Fired on activation of an item (pointer or keyboard). Not fired while that item or the group is disabled. |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | On the container: the items, in visual order. On an item: its glyph — an SVG, auto-sized to 16px and tinted via `currentColor`. Items are icon-only in the design, and each one needs its own accessible name. |
+
+## Behavior
+
+### Container styles
+
+**Given** a button group
+**When** `variant` is `outlined` (the default)
+**Then** a 1px border and a 4px radius are drawn around the whole cluster, and
+the first and last item's fill is clipped to those rounded corners.
+
+**Given** a button group
+**When** `variant` is `inlined`
+**Then** no container border or radius is drawn, but the items and their
+separators are unchanged — including the clipping behavior, which still applies
+(there is simply no radius left to clip to).
+
+### Separators
+
+**Given** a group with two or more items
+**When** it renders
+**Then** every item except the last draws a hairline divider on its inline-end
+edge, so exactly one divider sits between each adjacent pair and none is drawn
+on the outer edges.
+
+**Given** a group with exactly one item
+**When** it renders
+**Then** no divider is drawn — the only item is also the last item.
+
+**Given** items that are each wrapped in another element
+**When** they render without an explicit `order`
+**Then** every divider disappears, because each item is the last child of its
+own wrapper. Passing `order` on each item restores them: `first` and `middle`
+draw a divider unconditionally and `last` draws none, replacing the positional
+derivation rather than layering on top of it.
+
+**Given** a group rendered under `dir="rtl"`
+**When** it renders
+**Then** the dividers move to the items' left edges and the item order mirrors,
+because the divider is an inline-end border, not a right border.
+
+### Activation
+
+**Given** an enabled item
+**When** it is clicked, or focused and activated with Enter or Space
+**Then** its `click` handler fires.
+
+**Given** an item
+**When** the pointer hovers it
+**Then** its fill changes to the hover fill; **when** it is being activated,
+**then** its fill changes to the active fill. Neither state persists after
+release — this component expresses transient action feedback, not selection.
+For a persistent selected state, use a toggle group instead.
+
+### Keyboard navigation
+
+**Given** a group with three enabled items
+**When** Tab moves focus into it
+**Then** exactly one item receives focus and the group is a single Tab stop —
+a second Tab leaves the group rather than moving to the next item.
+
+**Given** focus on an item
+**When** Right Arrow (or Down Arrow) is pressed
+**Then** focus moves to the next item; **when** Left Arrow (or Up Arrow) is
+pressed, **then** focus moves to the previous item.
+
+**Given** focus on the last item and `loop-focus` left at its default
+**When** Right Arrow is pressed
+**Then** focus wraps to the first item. **When** `loop-focus` is `false`,
+**then** focus stays on the last item.
+
+**Given** focus on an item
+**When** Home or End is pressed
+**Then** focus does not move. This is a gap in the underlying Base UI toolbar
+primitive, which does not forward its `enableHomeAndEndKeys` option — not a
+deliberate choice.
+
+### Disabled
+
+**Given** an item with `disabled`
+**When** the group renders
+**Then** that item keeps its idle fill, dims its glyph to the disabled glyph
+token, and ignores both clicks and Enter/Space activation.
+
+**Given** focus on the item before a disabled one
+**When** Right Arrow is pressed
+**Then** focus lands **on** the disabled item rather than skipping it. Per the
+WAI-ARIA toolbar pattern a disabled item stays focusable (it is exposed as
+`aria-disabled`, not the native disabled attribute) so a keyboard user can still
+discover that the action exists and is unavailable.
+
+**Given** a group whose **first** item is disabled
+**When** Tab moves focus into it
+**Then** focus lands on that first, disabled item and the group is reachable as
+normal. This is the reason the item is never natively disabled: the roving
+tabindex parks its single `tabindex="0"` on the first item, and a browser skips
+a natively disabled button — which would leave every item unreachable and drop
+the entire group out of the tab order.
+
+**Given** the container with `disabled`
+**When** the group renders
+**Then** every item is disabled and marked as such for styling, whether or not
+it sets `disabled` itself.
+
+## Accessibility
+
+- **Roles:** the container is `role="toolbar"` with `aria-orientation="horizontal"`;
+  each item is a native `<button>`. The separator is a CSS border rather than an
+  element, so it correctly contributes nothing to the accessibility tree (there
+  is no `role="separator"` to announce).
+
+- **Accessible name — container:** a toolbar SHOULD be named. Pass `aria-label`
+  (or `aria-labelledby`) describing what the actions have in common, e.g.
+  `aria-label="View mode"`. The component deliberately supplies **no** default:
+  a generic fallback like "button group" would tell a screen reader user
+  nothing, and it would hardcode an unlocalizable English string.
+
+- **Accessible name — items:** items are icon-only in the design, so they have
+  no text to name them. Each one MUST be given an `aria-label` (or
+  `aria-labelledby`). Decorative glyphs inside should stay `aria-hidden`.
+
+- **Keyboard:** the group is a **single Tab stop** with a roving tabindex —
+  Tab enters the group and the next Tab leaves it; the arrow keys move between
+  items, wrapping at the ends unless `loop-focus` is `false`. Enter and Space
+  activate the focused item (native button behavior). Home/End are not
+  supported — the underlying Base UI toolbar primitive does not forward its
+  `enableHomeAndEndKeys` option.
+
+- **Focus visible:** keyboard focus draws a 3px `--ui-focus-primary` ring
+  **inside** the item, via `:focus-visible` (no ring on pointer activation).
+  The ring is inset rather than outset for a functional reason: the container
+  clips its children, so an outset ring would be cut off. Being an inset
+  shadow, it is clipped to the padding edge and so stops short of the
+  separator instead of painting over it.
+
+- **Disabled:** a disabled item follows the ARIA Authoring Practices' toolbar
+  advice — it stays focusable and is exposed as `aria-disabled="true"`, **not**
+  with the native `disabled` attribute. So the arrow keys land on it and it keeps
+  its place in the roving sequence, while click and Enter/Space activation are
+  suppressed. This differs from the rest of the library, where a disabled control
+  drops out of the tab order, and the difference is load-bearing rather than
+  stylistic: a roving tabindex parks the group's single `tabindex="0"` on the
+  first item, and a browser skips a natively disabled button — so a natively
+  disabled _first_ item would leave every item unreachable and strand the whole
+  group outside the tab order. Base UI's `Toolbar.Root` offers no way to relocate
+  that initial tab stop. A disabled _group_ propagates the state to every item.
+
+- **State is not conveyed by color alone:** hover and active are transient
+  pointer/activation feedback, not information. The group carries no selected
+  state — if you need one, use a toggle group, whose items expose
+  `aria-pressed`.
+
+- **Contrast:** the glyph and per-state fills come from the design tokens,
+  which are authored to meet WCAG contrast in both light and dark themes.
+
+- **WCAG:** 2.1.1 (keyboard), 2.4.7 (focus visible), 1.4.3 / 1.4.11 (contrast),
+  4.1.2 (name/role/value).