@acronis-platform/ui-react 3.0.0 → 4.0.0

package/dist/llms/timer.md

@@ -0,0 +1,259 @@
+# Timer
+
+> An elapsed-time readout paired with a hairline-separated cluster of icon-only actions, in a single bordered 32px box. Displays a caller-formatted value; it does not tick.
+
+**Status:** ready · **Category:** data-display · **Since:** v0.63.0
+
+## Import
+
+```tsx
+import { Timer, ButtonGroupItem } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+const [elapsed, setElapsed] = useState(0);
+
+<Timer value={formatDuration(elapsed)} actionsLabel="Time tracking">
+  <ButtonGroupItem aria-label="Pause" onClick={pause}>
+    <CirclePauseIcon size={16} />
+  </ButtonGroupItem>
+  <ButtonGroupItem aria-label="Rename" onClick={rename}>
+    <PencilIcon size={16} />
+  </ButtonGroupItem>
+  <ButtonGroupItem aria-label="Add entry" onClick={addEntry}>
+    <PlusIcon size={16} />
+  </ButtonGroupItem>
+</Timer>
+
+{/* Read-only: no actions, so no toolbar and no divider */}
+<Timer value="00:12:30" />
+```
+
+An elapsed-time readout paired with a hairline-separated cluster of icon-only
+actions, in a single bordered 32px box. The readout displays a value the caller
+formats; the actions are ButtonGroup items the caller supplies.
+
+## When to use
+
+- A **time-tracking control** in a toolbar, table row, or card header: show the
+  elapsed time on a task and offer the two or three actions that operate on it
+  (pause, rename, add an entry).
+- A **stopwatch or session counter** the user can act on — pause, resume, stop —
+  where the count and its controls should read as one compact unit.
+- A **read-only duration** that belongs in the same visual family as the
+  interactive ones. Omit the actions and the box becomes just the readout.
+
+## When not to use
+
+- **A duration inside prose or a data table cell.** A bordered 32px box next to
+  plain text is chrome for nothing; render the formatted string directly.
+- **A countdown that must announce itself.** `role="timer"` is deliberately
+  silent (`aria-live="off"`) so it doesn't flood a screen reader once a second.
+  If a threshold matters, announce that event from a separate status region.
+- **Actions unrelated to the time shown.** The shared box claims the readout and
+  the actions are one control; unrelated actions belong outside it.
+- **Labelled actions.** The cluster is icon-only by design. For text actions
+  next to a duration, compose a `Toolbar` with plain `Button`s.
+- **As a clock.** The component holds no timer of its own (see Notes).
+
+## Example (React — implemented)
+
+```tsx
+import { Timer, ButtonGroupItem } from '@acronis-platform/ui-react';
+import {
+  CirclePauseIcon,
+  PencilIcon,
+  PlusIcon,
+} from '@acronis-platform/icons-react/stroke-mono';
+
+<Timer value={formatDuration(elapsed)} actionsLabel="Time tracking">
+  <ButtonGroupItem aria-label="Pause" onClick={pause}>
+    <CirclePauseIcon size={16} />
+  </ButtonGroupItem>
+  <ButtonGroupItem aria-label="Rename" onClick={rename}>
+    <PencilIcon size={16} />
+  </ButtonGroupItem>
+  <ButtonGroupItem aria-label="Add entry" onClick={addEntry}>
+    <PlusIcon size={16} />
+  </ButtonGroupItem>
+</Timer>;
+```
+
+Read-only — no actions, so no toolbar and no divider:
+
+```tsx
+<Timer value="00:12:30" />
+```
+
+Vue and Web Component implementations are planned and will target the same
+contract — see `api.yaml` `adapters`.
+
+## Parts
+
+| Part      | Element    | Notes                                                                                               |
+| --------- | ---------- | --------------------------------------------------------------------------------------------------- |
+| container | `div`      | The bordered box. No role — it owns the border, radius, background, height, and the clipping.       |
+| `readout` | `div`      | `role="timer"`. The formatted value, in tabular figures.                                            |
+| `divider` | _(border)_ | The readout's inline-end border, dropped when there are no actions. Not an element, so not in a11y. |
+| `actions` | `div`      | `role="toolbar"` — a `ButtonGroup` in its `inlined` style, holding the caller's `ButtonGroupItem`s. |
+
+## Notes
+
+- **It does not tick.** The component holds no clock and starts no interval: it
+  renders whatever `value` it is handed. The caller owns the interval, the
+  format, and the state the actions mutate — which is what lets the same
+  component serve a stopwatch, a countdown, and a static duration.
+- **Formatting is yours too**, including whether hours appear and how the locale
+  renders the separators. The readout only guarantees that whatever you pass
+  keeps its width as digits change, via tabular figures.
+- **Actions are ButtonGroup items**, imported from `ButtonGroup` rather than
+  re-exported under a Timer name. The Timer renders the group itself so it can
+  always pick the `inlined` style — its own box already draws the border and
+  radius an `outlined` group would duplicate — but everything about an item
+  (separators, one Tab stop, arrow-key roving, hover/active/focus/disabled) is
+  ButtonGroup's contract, unchanged.
+- **Name the actions.** Each icon-only item needs its own `aria-label`, and a
+  play/pause control's name must track its current function rather than its
+  icon. The toolbar's own name comes from `actionsLabel`, whose default is an
+  untranslated English string. See `accessibility.md`.
+- **The box hugs its content.** Figma's 224px frame is the measured width of the
+  sample value plus three actions, not a fixed size — a longer value simply
+  makes the box wider.
+- **RTL-safe.** The divider is an inline-end border, so the whole layout mirrors
+  under `dir="rtl"` with no extra work.
+- **No variants, no states.** Figma models this as a single component, not a
+  component set: there is no size or style axis, and every interaction state
+  lives on the individual actions.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `value` | `string | Node` | — | yes | The formatted time to display, e.g. `12:01:45`. The component holds no clock: it neither ticks nor formats, so the caller owns the interval and the format (including whether hours are shown and how a locale renders the separators). Rendered with tabular figures so the readout keeps its width as the digits change. |
+| `actions-label` | `string` | `'Timer actions'` | no | Accessible name for the action cluster's toolbar. Exists because the caller cannot reach that element directly — the Timer renders it — and the default is an unlocalized English string, so translate it. |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | The actions, as ButtonGroup items in visual order. Each is icon-only and needs its own accessible name. Omit them for a read-only readout: the toolbar is then not rendered at all and the divider goes with it. |
+
+## Behavior
+
+### The readout
+
+**Given** a timer
+**When** it renders
+**Then** the `value` it was given is displayed verbatim inside the readout, with
+tabular figures so every digit occupies the same width.
+
+**Given** a running timer whose `value` changes from `12:01:45` to `12:01:46`
+**When** the new value renders
+**Then** the readout's width is unchanged and nothing to its inline-end shifts,
+because the figures are tabular and the box hugs its content rather than
+re-measuring per frame.
+
+**Given** a timer
+**When** time passes without the caller supplying a new `value`
+**Then** the readout does not change. The component owns no clock and starts no
+interval — ticking, formatting, pausing, and resetting all belong to the caller,
+who also owns whatever the actions operate on.
+
+**Given** a `value` longer than the design's sample (e.g. `128:59:59`)
+**When** it renders
+**Then** the box grows to fit it. The readout hugs its content plus the
+horizontal padding; the Figma frame's 224px width is the measured result of the
+sample content, not a fixed width.
+
+### The action cluster
+
+**Given** a timer with one or more actions
+**When** it renders
+**Then** they appear inline-end of the readout as a single toolbar, in the order
+given, separated from the readout by a hairline divider and from each other by
+the ButtonGroup's own separators.
+
+**Given** a timer with no actions
+**When** it renders
+**Then** no toolbar element is rendered at all, and the divider is dropped too —
+the readout is the last child, and the divider is its own `:last-child`-reset
+inline-end border.
+
+**Given** an action
+**When** it is hovered, activated, focused by keyboard, or disabled
+**Then** it behaves exactly as a ButtonGroup item does; the timer adds nothing
+and overrides nothing. See the ButtonGroup spec.
+
+**Given** the action cluster
+**When** it renders
+**Then** it is always the `inlined` ButtonGroup style — never `outlined`. The
+timer's own box already draws the border and radius an outlined group would
+duplicate, and this is how the design instantiates it. It is not configurable.
+
+### Container
+
+**Given** a timer whose trailing action is hovered or focused
+**When** the fill or the inset focus ring paints
+**Then** it is clipped to the container's radius, so no square corner escapes
+the rounded box.
+
+**Given** a timer under `dir="rtl"`
+**When** it renders
+**Then** the readout sits at the inline start and the actions at the inline end,
+mirrored — the divider is an inline-end border, not a right-hand one. The value
+itself is not reordered; formatting the time for the locale is the caller's job.
+
+## Accessibility
+
+- **Roles:** the readout is `role="timer"` — a live-region role for a numeric
+  counter of elapsed or remaining time. The action cluster is the ButtonGroup's
+  `role="toolbar"`. The container itself carries no role; it is a box, not a
+  widget. The divider is a CSS border rather than an element, so it correctly
+  contributes nothing to the accessibility tree.
+
+- **Live-region politeness:** `role="timer"` is implicitly `aria-live="off"`,
+  which is the right default: a per-second announcement would flood a screen
+  reader and drown out everything else on the page. Do **not** raise it to
+  `polite` for a ticking clock. If a milestone matters (a limit reached, a
+  session about to expire), announce that event from a separate status region
+  rather than making the timer itself chatty.
+
+- **Accessible name — readout:** optional. The value speaks for itself in most
+  contexts; where several timers appear together, name each one by putting
+  `aria-labelledby` on the container's own visible label, or pass `aria-label`
+  through to the container.
+
+- **Accessible name — action cluster:** supplied by `actions-label`, which
+  defaults to the English string `Timer actions`. Translate it. The property
+  exists precisely because the caller cannot reach the toolbar element directly.
+
+- **Accessible name — actions:** each action is icon-only, so it has no text to
+  name it. Every one MUST be given an `aria-label` (or `aria-labelledby`);
+  decorative glyphs inside stay `aria-hidden`. A play/pause action's name must
+  track its current function ("Pause" while running, "Resume" while paused), not
+  its icon.
+
+- **Keyboard:** the timer adds no key handling of its own. The action cluster is
+  a **single Tab stop** with a roving tabindex — Tab enters it and the next Tab
+  leaves; the arrow keys move between actions; Enter and Space activate. See the
+  ButtonGroup spec for the full pattern, including how a disabled action stays
+  focusable.
+
+- **Focus visibility:** an action's focus ring is drawn inset, so the
+  container's clipping cannot shave it off at the rounded corners.
+
+- **Contrast:** the readout uses `--ui-timer-value-color` on
+  `--ui-timer-container-color` and the action glyphs use
+  `--ui-glyph-on-surface-primary`; both pairs meet WCAG AA in the light and dark
+  themes of every shipped brand. The divider and the container border are
+  decorative hairlines and are not held to a text-contrast ratio.
+
+- **Text sizing:** the readout is 18px with a 24px line-height inside a 32px
+  box. It scales with the user's font size; the container's height token is the
+  design's fixed 32px, so a large browser zoom scales the whole box rather than
+  clipping the digits.
+
+- **Motion:** none. The value updates are plain text changes with no transition,
+  so nothing here is affected by `prefers-reduced-motion`.

package/dist/llms/toast.md

@@ -0,0 +1,241 @@
+# Toast
+
+> A transient notification in a corner stack: a neutral card carrying its severity through a status-colored border and a status line down the leading edge, with a fixed status icon per severity, an optional description, and optional action buttons. Triggered imperatively via the `toast(...)` API and rendered by a single `<Toaster>` region.
+
+**Status:** stable · **Category:** feedback · **Since:** v0.41.0
+
+## Import
+
+```tsx
+import { Toaster, toast } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+// once, near the app root:
+<Toaster />
+
+// anywhere:
+toast.success('Profile saved', { description: 'Your changes were saved.' });
+toast.danger('Delete failed', {
+  description: 'Please try again or contact support.',
+  actions: [{ label: 'Retry', onClick: retry }],
+});
+```
+
+A transient notification shown in a corner stack — triggered imperatively with
+the `toast(...)` API and rendered by a single `<Toaster>` region.
+
+Visually it is `Alert` plus a drop shadow: a neutral card whose severity is
+carried by a 1px status-colored border, a 6px status line down the leading edge,
+and a fixed status icon. Every value comes from the `--ui-toast-*` tier, mirroring
+the Figma "Toast" component set (node `7421:126262`). Built on the Base UI toast
+manager — no Sonner dependency.
+
+## When to use
+
+- Brief, low-priority feedback for an action (saved, copied, undo).
+- Background operation status (loading → success/danger via `toast.promise`).
+
+## When not to use
+
+- For information the user must act on or must not miss — use a `Dialog` or an
+  inline message; toasts auto-dismiss.
+- For persistent, in-page status — use `Alert`, which is the same card without the
+  shadow and without the auto-dismiss.
+
+## Setup
+
+Render one `<Toaster>` near the app root, then call `toast` anywhere. **Exactly
+one** region per page: the queue is a module-level singleton scoped to the package
+instance, so a micro-frontend host must share a single `@acronis-platform/ui-react`
+instance. With two copies loaded, `toast(...)` from one is invisible to the other's
+region (queued, never rendered) and two regions overlap in the same corner.
+
+```tsx
+import { Toaster, toast } from '@acronis-platform/ui-react';
+
+// app root
+<Toaster />;
+
+// anywhere
+toast.success('Profile saved', { description: 'Your changes were saved.' });
+toast.danger('Delete failed', {
+  description: 'Please try again or contact support.',
+  actions: [
+    { label: 'Retry', onClick: retry },
+    { label: 'Get help', onClick: openSupport },
+  ],
+});
+
+// tie to a promise
+toast.promise(save(), {
+  loading: 'Saving…',
+  success: 'Saved',
+  error: 'Could not save',
+});
+```
+
+The severity comes from the method: `toast.info` / `success` / `warning` /
+`critical` / `danger` match the Figma variants, a bare `toast(...)` is `info`, and
+`toast.loading` shows a persistent spinner (no Figma variant of its own).
+
+## Parts
+
+| Part                | Element    | Purpose                                     |
+| ------------------- | ---------- | ------------------------------------------- |
+| `root`              | div        | The `role="region"` viewport / toast stack. |
+| `toast`             | div        | A single notification card.                 |
+| `toast-status-line` | `::before` | The 6px status bar on the leading edge.     |
+| `toast-icon`        | div        | Status glyph, or a spinner while loading.   |
+| `toast-content`     | div        | The column beside the icon.                 |
+| `toast-text`        | div        | Title + description block.                  |
+| `toast-title`       | h5         | The notification's heading.                 |
+| `toast-description` | div        | Optional supporting text (3-line clamp).    |
+| `toast-actions`     | div        | Optional wrapping row of action buttons.    |
+| `toast-close`       | button     | Optional dismiss (✕) button.                |
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `timeout` | `number` | `5000` | no | Default auto-dismiss delay (ms) for toasts that don't set their own. `0` keeps a toast until dismissed. |
+| `limit` | `number` | `3` | no | Maximum toasts shown at once; the oldest is dropped past it. |
+| `label` | `string` | `'Notifications'` | no | Accessible name for the toast region. |
+| `closeAriaLabel` | `string` | `'Close'` | no | Accessible name for each toast's dismiss control. |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `options.dismissable` | Whether the toast renders its dismiss control and can be swiped away. Defaults to true, matching the Figma's `dismissable` boolean. Setting it false also revokes swipe-to-dismiss, so the control and the capability never disagree; combined with `timeout: 0` the toast can then only be removed with `toast.dismiss(id)`. |
+| `options.actions` | Action-button descriptors — `{ label, onClick?, variant? }` — rendered in a wrapping row under the text. The first defaults to the `secondary` button style and the rest to `ghost`, matching the Figma. Clicking one runs its handler; it does not dismiss the toast. |
+
+## Behavior
+
+Toast is imperative: render one `<Toaster>` region, then push notifications with
+the `toast(...)` API from anywhere (including outside React — the manager is
+module-level). The severity is chosen by which method is called, not by a prop.
+
+```gherkin
+Scenario: Show a toast
+  Given a mounted <Toaster>
+  When toast('Event created', { description: 'Monday at 6:00 PM' }) is called
+  Then a card with the title and description appears in the bottom-end stack
+  And it uses the info severity (the Figma's default variant)
+  And it auto-dismisses after the timeout (default 5000ms)
+```
+
+```gherkin
+Scenario: Severities
+  Given toast.info / success / warning / critical / danger is called
+  Then the card keeps its neutral surface
+  And its border and 6px leading status line take that severity's color
+  And it shows that severity's multicolor status icon
+```
+
+```gherkin
+Scenario: No description
+  Given a toast created without a description
+  Then only the title renders, and the icon stays aligned with its first line
+```
+
+```gherkin
+Scenario: Long description
+  Given a description longer than three lines
+  Then it is clamped to three lines with a trailing ellipsis
+```
+
+```gherkin
+Scenario: Loading
+  Given toast.loading('Processing…') is called
+  Then the card shows a spinner in place of the status glyph
+  And it borrows the info border and status line (there is no Figma loading variant)
+  And it does NOT auto-dismiss
+  And toast.dismiss(id) or toast.promise resolution removes it
+```
+
+```gherkin
+Scenario: Actions
+  Given a toast created with actions: [{ label: 'View' }, { label: 'Undo' }]
+  Then a wrapping row renders under the text
+  And the first action uses the secondary button style, the rest ghost
+  When an action is clicked
+  Then its onClick runs and the toast stays open
+```
+
+```gherkin
+Scenario: Promise lifecycle
+  Given toast.promise(p, { loading, success, error }) is called
+  Then a persistent loading toast appears
+  And on fulfilment it becomes a success toast
+  And on rejection it becomes a danger toast
+```
+
+```gherkin
+Scenario: Manual dismiss
+  Given a visible toast
+  When the close (✕) button is clicked
+  Then the toast animates out and is removed
+```
+
+```gherkin
+Scenario: Not dismissable
+  Given a toast created with dismissable: false
+  Then no close (✕) button renders
+  And swiping it does not dismiss it either
+  And it leaves only on its timeout, or via toast.dismiss(id)
+```
+
+```gherkin
+Scenario: Direction
+  Given dir="rtl" on an ancestor
+  Then the stack pins to the bottom-left corner
+  And the status line sits on the right (leading) edge
+  And toasts slide in from the left
+  And the status icons do NOT mirror
+```
+
+```gherkin
+Scenario: Limit
+  Given more than `limit` toasts (default 3) are active
+  Then the oldest is dropped to make room for the newest
+```
+
+```gherkin
+Scenario: Update in place
+  Given toast(..., { id: 'x' }) is called twice with the same id
+  Then the existing toast updates and its auto-dismiss timer resets
+```
+
+## Accessibility
+
+- The `<Toaster>` region is a live region (`role="region"`, `aria-live="polite"`)
+  named by the `label` prop (default `"Notifications"`), so screen readers
+  announce new toasts without moving focus. Pass `label` to localize it.
+- Base UI manages the announcement: it exposes an off-screen copy of each toast's
+  text to assistive tech and marks the visible card `aria-hidden`, so the message
+  is announced once and not duplicated. The card's accessible name comes from its
+  title.
+- The dismiss and action buttons are reachable by keyboard via the viewport's
+  focus management (F6 / Tab into the region). The dismiss control's accessible
+  name comes from `closeAriaLabel` (default `"Close"`) — pass it to localize —
+  and it shows a visible focus ring (`--ui-focus-primary`) via ButtonIcon.
+- Severity is never conveyed by color alone: each severity has its own status
+  icon, and the title/description carry the message in words.
+- Don't put essential, time-critical information only in a toast — it
+  auto-dismisses. Pair destructive confirmations with a persistent surface, and
+  prefer `Alert` (the same visual, inline and persistent) when the message must
+  stay on screen.
+
+## Contrast
+
+The card uses `--ui-toast-global-content-text-container-title-color` (title) and
+`--ui-toast-global-content-text-container-description-color` (description) over
+the neutral `--ui-toast-global-container-background`, meeting text contrast in
+light and dark. The severity border and status line
+(`--ui-toast-<severity>-border-color` / `-left-line`) are decorative — they
+reinforce the status icon rather than carrying meaning on their own — so they are
+not held to text contrast. Action buttons and the dismiss control inherit the
+contrast-checked `--ui-button-*` / `--ui-button-icon-*` tiers.

package/dist/llms/toggle-group.md

@@ -0,0 +1,121 @@
+# ToggleGroup
+
+> A set of pressable toggle buttons (single or multiple selection) — plus a standalone Toggle. Built on Base UI's Toggle / ToggleGroup. Ported from the legacy shadcn-uikit `toggle-group`.
+
+**Status:** draft · **Category:** forms · **Since:** v0.51.0
+
+## Import
+
+```tsx
+import { Toggle, ToggleGroup, ToggleGroupItem } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<ToggleGroup defaultValue={['grid']}>
+  <ToggleGroupItem value="grid" aria-label="Grid">▦</ToggleGroupItem>
+  <ToggleGroupItem value="list" aria-label="List">≣</ToggleGroupItem>
+</ToggleGroup>
+```
+
+A set of pressable toggle buttons (single or multiple selection), plus a
+standalone `Toggle`. Built on Base UI's Toggle / ToggleGroup.
+
+> Design-pending v1, ported from the legacy shadcn-uikit `toggle-group`.
+
+## When to use
+
+- A small set of mutually-exclusive (or multi-select) view/format options —
+  view-mode switchers, text-formatting toolbars.
+
+## When not to use
+
+- Choosing one option from a list / form value — use `RadioGroup` or `InputSelect`.
+- A single on/off setting with a label — use `Switch`.
+
+## Parts
+
+| Export            | Purpose                                            |
+| ----------------- | -------------------------------------------------- |
+| `ToggleGroup`     | The group — tracks the pressed value(s).           |
+| `ToggleGroupItem` | A pressable button in the group (needs a `value`). |
+| `Toggle`          | A standalone pressable button (same styling).      |
+
+## Example
+
+```tsx
+import { ToggleGroup, ToggleGroupItem } from '@acronis-platform/ui-react';
+
+<ToggleGroup defaultValue={['grid']} aria-label="View mode">
+  <ToggleGroupItem value="grid" aria-label="Grid view">
+    <GridIcon />
+  </ToggleGroupItem>
+  <ToggleGroupItem value="list" aria-label="List view">
+    <ListIcon />
+  </ToggleGroupItem>
+</ToggleGroup>;
+```
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `value` | `string[]` | — | no | The pressed item value(s) (controlled, on ToggleGroup). |
+| `defaultValue` | `string[]` | — | no | The initially pressed value(s) (uncontrolled, on ToggleGroup). |
+| `pressed` | `boolean` | — | no | Whether a standalone Toggle is pressed (controlled). |
+| `defaultPressed` | `boolean` | `false` | no | Whether a standalone Toggle is initially pressed (uncontrolled). |
+| `disabled` | `boolean` | `false` | no | Disables the group / toggle. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `onValueChange` | `(value: string[], eventDetails) => void` | Fired when the pressed set changes (ToggleGroup). |
+| `onPressedChange` | `(pressed: boolean, eventDetails) => void` | Fired when a standalone Toggle's pressed state changes. |
+
+## Behavior
+
+```gherkin
+Scenario: Press an item
+  Given a ToggleGroup with items
+  When the user clicks an item
+  Then it becomes pressed (tinted) and its value is added to the group value
+```
+
+```gherkin
+Scenario: Single vs. multiple
+  Given a single-selection group
+  When the user presses another item
+  Then the previously pressed item is released
+  (a multiple-selection group keeps both pressed)
+```
+
+```gherkin
+Scenario: Standalone toggle
+  Given a standalone Toggle
+  When the user clicks it
+  Then it flips its pressed state (onPressedChange fires)
+```
+
+```gherkin
+Scenario: Disabled
+  Given disabled is set
+  Then the toggle(s) cannot be pressed or focused
+```
+
+## Accessibility
+
+- Built on Base UI's Toggle / ToggleGroup: each toggle is a `<button>` with
+  `aria-pressed`, operable with Enter/Space; the group supports arrow-key roving
+  focus. Give each toggle an accessible name (`aria-label` for icon-only toggles)
+  and the group an `aria-label`.
+- Don't rely on the pressed tint alone — for icon-only toggles the `aria-pressed`
+  state conveys selection to assistive tech.
+
+## Contrast
+
+Idle is transparent (text/icon use the foreground); hover uses
+`--ui-background-surface-hover` and pressed uses `--ui-background-surface-active`,
+both meeting contrast against the page in light and dark; the focus ring uses
+`--ui-focus-primary`.