@acronis-platform/ui-react 3.0.0 → 4.1.0

package/dist/llms/date-range-picker.md

@@ -0,0 +1,272 @@
+# DateRangePicker
+
+> A range date field: an `InputDatePicker` trigger opens a popover with a dual-month range `CalendarPanel`, whose own Cancel/Apply footer commits or reverts the draft. Edits stay in a draft until Apply commits them (Cancel or dismissing reverts).
+
+**Status:** draft · **Category:** forms · **Since:** v0.56.0
+
+## Import
+
+```tsx
+import { DateRangePicker } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+const [range, setRange] = React.useState<{ from?: Date; to?: Date }>({});
+
+<DateRangePicker
+  label="Period"
+  placeholder="Select a date range"
+  value={range}
+  onValueChange={setRange}
+/>
+
+{/* Uncontrolled with a default */}
+<DateRangePicker
+  label="Period"
+  defaultValue={{ from: new Date(2026, 6, 1), to: new Date(2026, 6, 15) }}
+  onValueChange={(next) => console.log(next)}
+/>
+
+{/* Localized popup strings + calendar constraints (forwarded to CalendarPanel).
+    `es` comes from `import { es } from 'react-day-picker/locale'`.
+    React names the calendar pass-throughs in camelCase: `disabledDays`,
+    `showOutsideDays`, `weekStartsOn`, `fromYear`, `toYear`, `monthLabel`,
+    `yearLabel`, `formatMonthLabel`, `cancelLabel`, `applyLabel`. */}
+<DateRangePicker
+  label="Período"
+  locale={es}
+  monthLabel="Mes"
+  yearLabel="Año"
+  cancelLabel="Cancelar"
+  applyLabel="Aplicar"
+  disabledDays={{ after: new Date() }}
+  max={31}
+  fromYear={2020}
+  toYear={2030}
+  onValueChange={setRange}
+/>
+```
+
+A range date field: an `InputDatePicker` trigger opens a popover with a dual-month
+range `CalendarPanel`, whose own Cancel/Apply footer commits or reverts the draft.
+
+> It owns no token tier of its own — the trigger uses
+> `--ui-input-date-picker-*` and the popup is themed by the composed
+> `CalendarPanel` (`--ui-calendar-*`). Popover contributes only positioning,
+> portaling and dismissal — its own container chrome is neutralized so
+> CalendarPanel's chrome shows through instead.
+
+## When to use
+
+- Picking a start–end date range with an explicit Apply step (so an in-progress
+  selection never leaks out until confirmed).
+
+## When not to use
+
+- For a single date, use `InputDatePicker` + `Calendar` (or a single-mode
+  date-picker composition).
+- A preset list ("Last 7 days", "This month", …) — not currently implemented
+  by any component in this repo; this component doesn't render presets.
+
+## Examples
+
+```tsx
+import { DateRangePicker } from '@acronis-platform/ui-react';
+
+// Controlled
+const [range, setRange] = React.useState<{ from?: Date; to?: Date }>({});
+<DateRangePicker
+  label="Period"
+  placeholder="Select a date range"
+  value={range}
+  onValueChange={setRange}
+/>;
+
+// Uncontrolled with a default
+<DateRangePicker
+  label="Period"
+  defaultValue={{ from: new Date(2026, 6, 1), to: new Date(2026, 6, 15) }}
+  onValueChange={(next) => console.log(next)}
+/>;
+```
+
+Localized, with the calendar constrained to selectable days — every string the
+popup renders on its own is a prop, and the calendar constraints are forwarded
+to the composed `CalendarPanel`:
+
+```tsx
+import { es } from 'react-day-picker/locale';
+
+<DateRangePicker
+  label="Período"
+  locale={es}
+  monthLabel="Mes"
+  yearLabel="Año"
+  cancelLabel="Cancelar"
+  applyLabel="Aplicar"
+  disabledDays={{ after: new Date() }}
+  max={31}
+  onValueChange={setRange}
+/>;
+```
+
+## Parts
+
+| Part       | Element                    | Notes                                      |
+| ---------- | -------------------------- | ------------------------------------------ |
+| `trigger`  | `InputDatePicker`          | Shows the applied range + calendar icon    |
+| `popup`    | Popover content            | Portaled panel                             |
+| `calendar` | dual-month `CalendarPanel` | `variant="range"`, own Cancel/Apply footer |
+| `cancel`   | `CalendarPanel`'s footer   | Reverts the draft, closes the popup        |
+| `apply`    | `CalendarPanel`'s footer   | Commits the draft, closes the popup        |
+
+Edits stay in a draft until **Apply**; **Cancel** or dismissing the popover reverts them.
+
+## Notes
+
+- **Calendar pass-throughs.** `disabledDays`, `min`, `max`, `showOutsideDays`,
+  `weekStartsOn`, `fromYear`, `toYear`, `locale`, `monthLabel`, `yearLabel`,
+  `formatMonthLabel`, `cancelLabel` and `applyLabel` are forwarded verbatim to
+  the popup's `CalendarPanel` — see its spec for their semantics and defaults.
+  `disabledDays` is the only rename (`CalendarPanel`'s `disabled`), since
+  `disabled` here disables the trigger.
+- **`locale` also reaches the trigger.** Unlike the other pass-throughs,
+  `locale` is also read by the trigger's own date formatter to translate the
+  month name — the day/year order stays fixed at `MMM d, yyyy` regardless of
+  `locale`; true locale-aware reordering isn't supported.
+- **No `dir` prop.** The ambient text direction is read from the document
+  (`useDocDir()`) and passed to `CalendarPanel`'s `dir`, which the day grid
+  needs directly for Arrow Left/Right roaming. Set `dir` on the document (or
+  an ancestor) as usual.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `value` | `{ from?: Date; to?: Date }` | — | no | The applied range (controlled). Omit for uncontrolled use with `default-value`. |
+| `default-value` | `{ from?: Date; to?: Date }` | — | no | The initial applied range (uncontrolled). |
+| `label` | `ReactNode` | — | no | Field label rendered above the trigger. |
+| `description` | `ReactNode` | — | no | Helper text below the trigger. Hidden while `error` is set. |
+| `error` | `ReactNode` | — | no | Error message below the trigger; switches it to the error treatment. |
+| `placeholder` | `ReactNode` | — | no | Hint shown in the trigger when no range is selected. |
+| `required` | `boolean` | `false` | no | Marks the trigger required (appends `*`). |
+| `disabled` | `boolean` | `false` | no | Disables the trigger and prevents opening the popover. |
+| `disabled-days` | `Matcher | Matcher[]` | `undefined` | no | Days that cannot be selected in the calendar, as a react-day-picker matcher (or array of them). Named `disabled-days` rather than `CalendarPanel`'s `disabled` because `disabled` here disables the trigger. |
+| `min` | `number` | `undefined` | no | Minimum number of nights between the range's start and end (`differenceInCalendarDays(to, from)`) — e.g. `min={7}` requires at least 8 selectable days. |
+| `max` | `number` | `undefined` | no | Maximum number of nights between the range's start and end (`differenceInCalendarDays(to, from)`) — e.g. `max={31}` admits up to 32 selectable days. |
+| `show-outside-days` | `boolean` | `true` | no | Render the leading/trailing days of the adjacent months to fill the first and last week rows. |
+| `week-starts-on` | `0 | 1 | 2 | 3 | 4 | 5 | 6` | `the `locale`'s week start, else 1` | no | First day of the week (0 = Sunday). Defaults to `locale`'s own week start, falling back to Monday when no `locale` is given. |
+| `from-year` | `number` | `the current year − 50` | no | First year offered by the year dropdown (inclusive) and the earliest month the grid can navigate to. |
+| `to-year` | `number` | `the current year + 50` | no | Last year offered by the year dropdown (inclusive) and the latest month the grid can navigate to. |
+| `locale` | `Locale` | `date-fns `enUS`` | no | Localizes the calendar's weekday names and its default day-cell/caption accessible labels, and translates the trigger's month name. Also supplies the fallback week start. The trigger's day/year order stays fixed (`MMM d, yyyy`) — only the month name translates, not the ordering. Does not translate `month-label`/`year-label`/`cancel-label`/ `apply-label`/`format-month-label` — those are separate properties. |
+| `month-label` | `string` | `'Month'` | no | Accessible name of the calendar's month dropdown, which has no visible label in the design — override it to localize. |
+| `year-label` | `string` | `'Year'` | no | Accessible name of the calendar's year dropdown, which has no visible label in the design — override it to localize. |
+| `format-month-label` | `(date: Date) => string` | ``locale`-aware date-fns `format(date, 'MMMM')`` | no | Formats a month's name for the month dropdown's items and value — the hook for localized or abbreviated month names. |
+| `cancel-label` | `string` | `'Cancel'` | no | Popup footer's "Cancel" button label. |
+| `apply-label` | `string` | `'Apply'` | no | Popup footer's "Apply" button label. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `value-change` | `{ from?: Date; to?: Date }` | Fired with the committed range when Apply is pressed (React: `onValueChange`). Not fired on Cancel or dismiss (the draft is reverted). Apply is never disabled, so this can fire with an empty (`{ from: undefined, to: undefined }`) or half-open (`{ from, to: undefined }`) range if Apply is pressed before a full range is picked. |
+
+## Behavior
+
+It mirrors the draft/commit/revert idiom of `FilterSearchFilters`; the popup's
+Cancel/Apply footer is `CalendarPanel`'s own.
+
+### Opening
+
+- **Given** an enabled trigger, **when** the user activates it, **then** the
+  popover opens and the applied range is snapshotted into the draft.
+- **Given** `disabled`, **when** the user activates the trigger, **then** nothing
+  happens (the popover does not open).
+
+### Editing the draft
+
+There are no editable start/end text fields — the draft is only ever changed
+by clicking days in the calendar (`CalendarPanel`'s `range` selection mode).
+
+- **When** the draft has no start, **then** clicking a day sets `from` to that
+  day; with no `min` set (the default), `to` is also set to that day (a
+  single-day draft) — `react-day-picker`'s `addToRange` only leaves `to`
+  open-ended (`undefined`) when `min` is greater than 0.
+- **When** the draft has a start but no end, **then** clicking a later day
+  completes the range (`to` = that day); clicking an earlier day moves the
+  start back instead (`from` = that day, `to` stays the previous start).
+- **When** the draft is a complete range, **then** clicking a day before the
+  start moves the start; clicking a day after the end, or between the two
+  ends, moves the end; clicking either existing end again collapses the draft
+  to that single day (`from` and `to` both become that day).
+- **When** the user clicks the sole day of a single-day draft (`from` and `to`
+  are the same day) a second time, **then** the whole draft clears to
+  `{ from: undefined, to: undefined }`. This is the only way the draft as a
+  whole clears from calendar interaction — there is no way to clear one end
+  independently of the other.
+
+### Committing vs. reverting
+
+- **When** the user presses **Apply**, **then** the draft is normalized (start
+  and end swapped if inverted) and `onValueChange` fires with the normalized
+  range; the applied range updates (uncontrolled) and the popover closes. Apply
+  is never disabled, so this also fires when the draft is empty or half-open
+  (e.g. the popup was opened and Apply pressed immediately, or only `from` was
+  ever clicked) — `onValueChange` can receive `{ from: undefined, to: undefined
+}` or `{ from, to: undefined }`.
+- **When** the user presses **Cancel**, **then** the draft is discarded,
+  `onValueChange` does **not** fire, and the popover closes.
+- **When** the user dismisses the popover (outside press / `Escape`), **then** the
+  draft is discarded, `onValueChange` does **not** fire, and the trigger keeps
+  showing the previously-applied range.
+
+### Controlled vs. uncontrolled
+
+- **Given** `value`, the applied range is owned by the parent; Apply fires
+  `onValueChange` and the parent decides whether to update `value`.
+- **Given** only `defaultValue` (or nothing), the component owns the applied range
+  internally and updates it on Apply.
+
+## Accessibility
+
+Accessibility is inherited from the composed primitives: the `InputDatePicker`
+trigger, the Base UI `Popover`, and `CalendarPanel`.
+
+## Trigger
+
+- The trigger is a `<button>` with `aria-haspopup="dialog"`; `aria-expanded`
+  tracks the open state. A `label` is associated via `htmlFor`/`id`, `required`
+  sets `aria-required`, and `error` sets `aria-invalid` and links the message via
+  `aria-describedby`.
+
+## Popover
+
+- Opening moves focus into the popover; `Escape` and an outside press close it and
+  return focus to the trigger. The popover is a non-modal Base UI `Popover`
+  (no `modal` prop is passed), so focus is **not** trapped — Tab can move focus
+  outside the popover while it remains open.
+
+## Calendar & footer
+
+- The grid follows the ARIA grid pattern with full keyboard support (arrow keys,
+  `Home`/`End`, `PageUp`/`PageDown`, `Enter`/`Space`) — see the `CalendarPanel` spec.
+- The footer's "Cancel" and "Apply" buttons are `CalendarPanel`'s own — ordinary
+  labelled buttons.
+- The month and year dropdowns have no visible label, so their accessible names
+  come from `monthLabel` / `yearLabel` (defaulting to "Month" / "Year"); the
+  footer buttons' names come from `cancelLabel` / `applyLabel`. All four —
+  plus `locale` for weekday names and the day cells' own labels, and
+  `formatMonthLabel` for the month names — are props, so a non-English UI has no
+  untranslatable text in the popup.
+- Arrow Left/Right day-grid roaming follows the ambient text direction: it is read
+  from the document (`useDocDir()`) and forwarded to `CalendarPanel`'s `dir`,
+  which `react-day-picker` needs directly (it does not inherit direction via
+  CSS).
+
+## Contrast
+
+- The trigger uses the `--ui-input-date-picker-*` tier (idle / hover / active /
+  error / disabled) so every state is within the palette's contrast budget; the
+  popup content contrast is owned by the composed `CalendarPanel`.

package/dist/llms/description-list.md

@@ -0,0 +1,131 @@
+# DescriptionList
+
+> A key/value data list — rows of label → value, where the value can be plain text, a status (leading icon + value + a muted description), or action links. Composable, semantic `<dl>`. NOT backed by a shared design-system design: it is the pattern extracted from the "Service status" list in the product-specific Cyber-Compliance Figma file (hc8FRfvlHBqZwNYUsD0DaX), not from the shared ui-react file, so the `figma.node` below is a product mapping rather than a design-system source of truth. Whether to formalize this as a generic kit component is still an open decision.
+
+**Status:** ready · **Category:** data-display · **Since:** v0.43.0
+
+## Import
+
+```tsx
+import { DescriptionList, DescriptionListItem, DescriptionListLabel, DescriptionListValue, DescriptionListValueDescription, DescriptionListActions } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<DescriptionList>
+  <DescriptionListItem>
+    <DescriptionListLabel>Backup</DescriptionListLabel>
+    <DescriptionListValue>
+      <CircleCheckIcon className="text-[var(--ui-text-on-status-success)]" />
+      <div>
+        Success
+        <DescriptionListValueDescription>
+          150GB of data backed up successfully
+        </DescriptionListValueDescription>
+      </div>
+    </DescriptionListValue>
+  </DescriptionListItem>
+</DescriptionList>
+```
+
+A key/value data list — rows of `label → value`, where the value can be plain
+text, a status (icon + value + muted description), or action links.
+
+> Built from the Cyber-Compliance "Service status" design
+> ([node 3001-20448](https://www.figma.com/design/hc8FRfvlHBqZwNYUsD0DaX/Cyber-Compliance?node-id=3001-20448)).
+> Composes the shared semantic tokens — no `--ui-description-list-*` tier.
+
+## When to use
+
+- Showing the properties / status of an entity (in a Sheet detail panel, a card,
+  a dashboard widget).
+- Replacing an ad-hoc `<dl>` grid — e.g. the `SheetDetails` / `sheet-detail-panel`
+  property list.
+
+## When not to use
+
+- Tabular data with many rows/columns — use `Table` / `DataTable`.
+- A single stat — use `CardFilter` or plain text.
+
+## Parts
+
+| Part                              | Element | Purpose                                    |
+| --------------------------------- | ------- | ------------------------------------------ |
+| `DescriptionList`                 | dl      | The list container.                        |
+| `DescriptionListItem`             | div     | A row (label + value), full-bleed divider. |
+| `DescriptionListLabel`            | dt      | The key (left column).                     |
+| `DescriptionListValue`            | dd      | The value (right column); icon + content.  |
+| `DescriptionListValueDescription` | p       | Muted secondary line under the value.      |
+| `DescriptionListActions`          | div     | A row of action links within a value.      |
+
+## Example
+
+```tsx
+<DescriptionList>
+  <DescriptionListItem>
+    <DescriptionListLabel>Backup</DescriptionListLabel>
+    <DescriptionListValue>
+      <CircleCheckIcon className="text-[var(--ui-text-on-status-success)]" />
+      <div>
+        Success
+        <DescriptionListValueDescription>
+          150GB of data backed up successfully
+        </DescriptionListValueDescription>
+      </div>
+    </DescriptionListValue>
+  </DescriptionListItem>
+</DescriptionList>
+```
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | DescriptionListItem rows, each a DescriptionListLabel (<dt>) and a DescriptionListValue (<dd>). The value composes an optional status icon, text, a DescriptionListValueDescription, and a DescriptionListActions row. |
+
+## Behavior
+
+DescriptionList is presentational: it has no internal state. The value cell
+adapts to whatever is composed into it.
+
+```gherkin
+Scenario: Plain key/value
+  Given a DescriptionListItem with a label and a text value
+  Then the row shows the label (left) and value (right), divided from the row above
+```
+
+```gherkin
+Scenario: Status value
+  Given a value with a leading status icon, a value, and a value-description
+  Then the icon (status color) sits before the value, with the muted description below
+```
+
+```gherkin
+Scenario: Action value
+  Given a value containing a DescriptionListActions row of links
+  Then the action links render in a wrapped row (e.g. "Action to fix" / "View alert")
+```
+
+```gherkin
+Scenario: Full-bleed dividers
+  Given items inside a padded card
+  Then each row's top divider spans the full width while the content stays inset
+```
+
+## Accessibility
+
+- Uses semantic `<dl>` / `<dt>` / `<dd>` (each item wraps the pair in a `<div>`,
+  which HTML5 permits inside `<dl>`), so assistive tech reads label/value
+  associations natively.
+- Status is conveyed by an icon **and** text — never color alone. Keep the
+  meaningful value/description as text; the icon is decorative reinforcement.
+- Action links are real `Link`s (anchors/buttons) with accessible names; place
+  them inside the relevant row's value so their context is clear.
+
+## Contrast
+
+Label and value use `--ui-text-on-surface-primary`; the value-description uses
+`--ui-text-on-surface-secondary`; dividers use `--ui-border-on-surface-border` —
+all meeting contrast in light and dark over the surface. Status icon colors come
+from `--ui-text-on-status-*` (caller-applied) and meet non-text contrast.

package/dist/llms/dialog-footer-carousel.md

@@ -0,0 +1,147 @@
+# DialogFooterCarousel
+
+> A bottom action bar for a multi-step (carousel) dialog: a `Back` button (hidden on the first slide), a dot slide indicator, and a `Next`/ call-to-action button. The `variant` (start / middle / end) tracks the active slide's position — see `DialogWelcome`, which owns the actual Embla carousel engine and drives this component's props.
+
+**Status:** draft · **Category:** layout · **Since:** v0.58.0
+
+## Import
+
+```tsx
+import { DialogFooterCarousel } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<DialogFooterCarousel
+  variant="middle"
+  slideCount={3}
+  selectedIndex={1}
+  onSelectIndex={setSelectedIndex}
+  onBack={() => embla.scrollPrev()}
+  onNext={() => embla.scrollNext()}
+/>
+```
+
+A bottom action bar for a multi-step (carousel) dialog: a `Back` button, a
+dot slide indicator, and a `Next`/call-to-action button. Built from scratch
+alongside `DialogWelcome`; does not reuse any existing carousel
+implementation in this repo.
+
+## When to use
+
+- The footer of a multi-step onboarding/welcome dialog driven by a real
+  carousel engine (pair it with `DialogWelcome`, which owns the Embla
+  instance and threads this component's props).
+
+## When not to use
+
+- A dialog's ordinary action row (Cancel/Save) — use `DialogFooterDefault`.
+- A standalone content carousel with no dialog chrome — this component is
+  footer-shaped only.
+
+## Parts
+
+| Part          | Description                                                           |
+| ------------- | --------------------------------------------------------------------- |
+| boxLeft       | `Back` button. Hidden on the first slide (`variant="start"`).         |
+| listIndicator | One dot per slide; clicking a dot jumps to that slide.                |
+| boxRight      | `Next` (first/middle slide) or the call-to-action label (last slide). |
+
+## Example
+
+```tsx
+import { DialogFooterCarousel } from '@acronis-platform/ui-react';
+
+<DialogFooterCarousel
+  variant="middle"
+  slideCount={3}
+  selectedIndex={1}
+  onSelectIndex={setSelectedIndex}
+  onBack={() => embla.scrollPrev()}
+  onNext={() => embla.scrollNext()}
+/>;
+```
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `variant` | `'start' | 'middle' | 'end'` | `'start'` | no | Which slide position this renders for. |
+| `slideCount` | `number` | `1` | no | Total number of slides, used to render the dot indicator. |
+| `selectedIndex` | `number` | `0` | no | The currently active slide index (0-based). |
+| `backLabel` | `string` | `'Back'` | no | `Back` button label. |
+| `nextLabel` | `string` | `'Next'` | no | `Next` button label (`variant="start" | "middle"`). |
+| `primaryLabel` | `string` | `'Call to action'` | no | Call-to-action button label (`variant="end"`). |
+| `goToSlideLabel` | `(index: number, count: number) => string` | — | no | Builds each dot's accessible name from its 0-based index and the slide count. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `select-index` | `number` | Fired when a dot is activated, with its slide index (React `onSelectIndex`). |
+| `back` | `undefined` | Fired when `Back` is activated (React `onBack`). |
+| `next` | `undefined` | Fired when `Next` is activated (React `onNext`). |
+| `primary-action` | `undefined` | Fired when the call-to-action button is activated (React `onPrimaryAction`). |
+
+## Behavior
+
+DialogFooterCarousel is a pure function of its props — no internal state.
+The carousel engine (which slide is active, how to move between slides) lives
+in the caller — typically `DialogWelcome`'s Embla instance — which threads
+`slideCount`/`selectedIndex` in and receives `onSelectIndex`/`onBack`/`onNext`/
+`onPrimaryAction` back out.
+
+```gherkin
+Scenario: First slide (variant="start")
+  Given a DialogFooterCarousel with variant="start"
+  Then `Back` is not rendered
+  And `Next` is rendered in boxRight
+  And the dot indicator marks the first dot active
+```
+
+```gherkin
+Scenario: A middle slide (variant="middle")
+  Given a DialogFooterCarousel with variant="middle"
+  Then `Back` is rendered in boxLeft
+  And `Next` is rendered in boxRight
+```
+
+```gherkin
+Scenario: The last slide (variant="end")
+  Given a DialogFooterCarousel with variant="end"
+  Then `Back` is rendered in boxLeft
+  And the call-to-action label (default "Call to action") replaces `Next` in boxRight
+```
+
+```gherkin
+Scenario: Jumping to an arbitrary slide
+  Given a DialogFooterCarousel with slideCount=3
+  When a dot other than the active one is activated
+  Then onSelectIndex fires with that dot's 0-based index
+  And the caller is responsible for actually moving the carousel and passing
+    back an updated `variant`/`selectedIndex`
+```
+
+## Accessibility
+
+- `Back`, `Next`, and the call-to-action control render as real `Button`
+  elements — native focus, keyboard activation (Enter/Space), and the
+  Button's own accessible name (its label) come for free.
+- Each dot in the indicator is a real `<button>` with an explicit
+  `aria-label` (default `"Go to slide N of M"`, overridable via
+  `goToSlideLabel`) — dots are never bare, unlabeled `<div>`s. The active
+  dot carries `aria-current="true"`.
+- DialogFooterCarousel is a plain layout container — no landmark role of its
+  own. It's meant to live inside a dialog (e.g. `DialogWelcome`), which owns
+  the `role="dialog"` / focus-trap semantics.
+- Focus order follows DOM order: `Back` (when present) → dots → `Next`/
+  call-to-action.
+
+## Contrast
+
+The active dot uses `--ui-glyph-on-surface-primary`; inactive dots use
+`--ui-glyph-on-surface-disabled`. Both are guaranteed to meet contrast against
+the footer's own background in both light and dark (shared semantic
+glyph/surface pairing) — the same tokens `Breadcrumb`'s separator icon and
+`Switch`'s track use for the equivalent idle/disabled distinction.