@acronis-platform/ui-react 2.0.0 → 4.0.0

package/dist/llms/sidebar-secondary.md

@@ -0,0 +1,417 @@
+# SidebarSecondary
+
+> The contextual second-level navigation panel that sits beside the primary rail. A set of composable parts (header, content, sections with optional labels, menu, fixed and expandable menu items, level-2 sub-items, extras) that reflows between an expanded (256px) panel and a collapsed (48px) rail. In collapsed mode the section list is replaced by a vertical breadcrumb (parent → separator → current page). Expandable rows disclose a level-2 child list via Base UI Collapsible.
+
+**Status:** ready · **Category:** navigation · **Since:** v0.7.0
+
+## Import
+
+```tsx
+import { SidebarSecondary, SidebarSecondaryHeader, SidebarSecondaryContent, SidebarSecondaryFooter, SidebarSecondarySection, SidebarSecondarySectionLabel, SidebarSecondaryMenu, SidebarSecondaryMenuItem, SidebarSecondaryMenuItemExtras, SidebarSecondaryCollapseTrigger } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<SidebarSecondary expanded={expanded} onExpandedChange={setExpanded}>
+  <SidebarSecondaryHeader label="Protection" />
+  <SidebarSecondaryContent>
+    <SidebarSecondarySection>
+      <SidebarSecondarySectionLabel>Overview</SidebarSecondarySectionLabel>
+      <SidebarSecondaryMenu>
+        <SidebarSecondaryMenuItem render={<Link to="/dashboard" />} selected>
+          Dashboard
+        </SidebarSecondaryMenuItem>
+        <SidebarSecondaryMenuItem render={<Link to="/policies" />}>
+          Policies
+        </SidebarSecondaryMenuItem>
+      </SidebarSecondaryMenu>
+    </SidebarSecondarySection>
+  </SidebarSecondaryContent>
+</SidebarSecondary>
+```
+
+The contextual, second-level navigation panel that sits beside the primary rail
+(SidebarPrimary). It lists the destinations within the currently selected
+top-level area, supports an expandable disclosure level, and collapses to a
+breadcrumb rail.
+
+## When to Use
+
+- Second-level navigation within a top-level area selected in SidebarPrimary.
+- Grouped, labelled sections of links, some with a Level-2 child list.
+- A panel that collapses to a compact location breadcrumb to reclaim space.
+
+## When NOT to Use
+
+- **App-wide, top-level navigation** — use SidebarPrimary.
+- **A popover menu of actions** — use a Menu/Dropdown.
+- **In-page section links / table of contents** — use anchors.
+- **Deep (3+ level) trees** — this component models one disclosure level only.
+
+## Parts
+
+| Part                                  | Element                              | Role                                                                                   |
+| ------------------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------- |
+| `SidebarSecondary`                    | `<nav>`                              | Navigation landmark; owns the expanded state                                           |
+| `SidebarSecondaryHeader`              | `<div><h2>`                          | Section title row                                                                      |
+| `SidebarSecondaryContent`             | `<div>`                              | Scrollable section list (expanded only)                                                |
+| `SidebarSecondaryCollapsedBreadcrumb` | `<div>`                              | Rail-mode location indicator (collapsed only)                                          |
+| `SidebarSecondaryFooter`              | `<div>`                              | Footer menu with a top divider                                                         |
+| `SidebarSecondarySection`             | `<div>` / `Collapsible.Root`         | A group of rows; `expandable` makes it collapsible                                     |
+| `SidebarSecondarySectionLabel`        | `<div>` / `Collapsible.Trigger`      | Section caption; the chevron toggle when expandable (`actions` / `unreadRollup` slots) |
+| `SidebarSecondaryMenu`                | `<ul>`                               | List that owns the inter-item gap                                                      |
+| `SidebarSecondaryMenuItem`            | `<li><a>` (polymorphic via `render`) | Level-1 leaf row                                                                       |
+| `SidebarSecondaryMenuSub`             | `Collapsible.Root` `<li>`            | Expandable Level-1 row                                                                 |
+| `SidebarSecondaryMenuSubTrigger`      | `Collapsible.Trigger` `<button>`     | Disclosure parent row (rotating chevron)                                               |
+| `SidebarSecondaryMenuSubContent`      | `Collapsible.Panel` `<div><ul>`      | Level-2 child list                                                                     |
+| `SidebarSecondaryMenuSubItem`         | `<li><a>`                            | Level-2 indented leaf                                                                  |
+| `SidebarSecondaryMenuItemExtras`      | `<span>`                             | Trailing shortcut / external-link / tag                                                |
+| `SidebarSecondaryCollapseTrigger`     | `<li><button>`                       | Footer "Collapse menu" button; toggles `expanded`                                      |
+
+## Quick Examples
+
+### React
+
+```tsx
+import {
+  SidebarSecondary,
+  SidebarSecondaryHeader,
+  SidebarSecondaryContent,
+  SidebarSecondaryCollapsedBreadcrumb,
+  SidebarSecondarySection,
+  SidebarSecondarySectionLabel,
+  SidebarSecondaryMenu,
+  SidebarSecondaryMenuItem,
+  SidebarSecondaryMenuSub,
+  SidebarSecondaryMenuSubTrigger,
+  SidebarSecondaryMenuSubContent,
+  SidebarSecondaryMenuSubItem,
+} from '@acronis-platform/ui-react';
+import {
+  LayoutGridIcon,
+  BoxIcon,
+} from '@acronis-platform/icons-react/stroke-mono';
+
+function ProtectionNav() {
+  const [expanded, setExpanded] = useState(true);
+  return (
+    <SidebarSecondary expanded={expanded} onExpandedChange={setExpanded}>
+      <SidebarSecondaryHeader label="Protection" />
+      <SidebarSecondaryContent>
+        <SidebarSecondarySection>
+          <SidebarSecondarySectionLabel>Overview</SidebarSecondarySectionLabel>
+          <SidebarSecondaryMenu>
+            <SidebarSecondaryMenuItem
+              href="/dashboard"
+              icon={<LayoutGridIcon />}
+              selected
+            >
+              Dashboard
+            </SidebarSecondaryMenuItem>
+            <SidebarSecondaryMenuSub defaultOpen>
+              <SidebarSecondaryMenuSubTrigger icon={<BoxIcon />}>
+                Policies
+              </SidebarSecondaryMenuSubTrigger>
+              <SidebarSecondaryMenuSubContent>
+                <SidebarSecondaryMenuSubItem href="/policies/backup" selected>
+                  Backup
+                </SidebarSecondaryMenuSubItem>
+                <SidebarSecondaryMenuSubItem href="/policies/av">
+                  Antivirus
+                </SidebarSecondaryMenuSubItem>
+              </SidebarSecondaryMenuSubContent>
+            </SidebarSecondaryMenuSub>
+          </SidebarSecondaryMenu>
+        </SidebarSecondarySection>
+      </SidebarSecondaryContent>
+      <SidebarSecondaryCollapsedBreadcrumb
+        parentLabel="Protection"
+        currentLabel="Dashboard"
+      />
+    </SidebarSecondary>
+  );
+}
+```
+
+Render a row as a router link via the `render` prop:
+
+```tsx
+<SidebarSecondaryMenuItem render={<Link to="/dashboard" />}>
+  Dashboard
+</SidebarSecondaryMenuItem>
+```
+
+## Collapsed mode
+
+Author both the `SidebarSecondaryContent` (section list) and the
+`SidebarSecondaryCollapsedBreadcrumb`. Visibility is toggled by the panel's
+`expanded` state via CSS — both stay in the DOM, so the breadcrumb is
+SSR-present and no JS branch is needed.
+
+## Spec Files
+
+| File               | Contents                                                          |
+| ------------------ | ----------------------------------------------------------------- |
+| `index.yaml`       | Identity, status, category, dependencies, Figma link              |
+| `anatomy.yaml`     | Root, parts, layout, states                                       |
+| `api.yaml`         | Framework-agnostic contract + framework adapters                  |
+| `tokens.yaml`      | `--ui-sidebar-secondary-*` 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 menu-item / sub-item parts — replaces the rendered element with another component (e.g. a router `Link`, or an `<aside>` wrapper on the root) while merging props and classes. React-only. |
+| `expanded` | `boolean` | `undefined` | no | Controlled panel width state (on the root). `true` = full width (256px), `false` = collapsed rail (48px). Drives `data-state`. |
+| `defaultExpanded` | `boolean` | `true` | no | Uncontrolled initial expanded state (on the root). |
+| `label` | `ReactNode` | `undefined` | no | Heading text for the header part (or pass as children). |
+| `selected` | `boolean` | `false` | no | Marks a menu-item / sub-trigger / sub-item as the current route — applies the `selected` container variant and sets `aria-current="page"`. |
+| `icon` | `ReactNode` | `undefined` | no | Optional leading 16px icon for a Level-1 menu-item / sub-trigger. |
+| `href` | `string` | `undefined` | no | Target URL of a menu-item / sub-item link. |
+| `open` | `boolean` | `undefined` | no | Controlled disclosure state of an expandable row (menu-sub) or an expandable section. Driven by Base UI Collapsible; sets `aria-expanded` / `aria-controls`. |
+| `defaultOpen` | `boolean` | `false` | no | Uncontrolled initial disclosure state of an expandable row or expandable section. (Expandable sections default to open.) |
+| `expandable` | `boolean` | `false` | no | Makes a section a collapsible disclosure (section part): the section-label becomes a chevron toggle and the menu becomes its collapsible panel. Mirrors the Figma Section `expandable` variant. |
+| `actions` | `ReactNode` | `undefined` | no | Trailing header actions on the section-label (e.g. a ghost ButtonIcon), rendered outside the toggle so they stay independently operable. |
+| `unreadRollup` | `ReactNode` | `undefined` | no | A rollup badge (e.g. a Tag with an unread count) shown in an expandable section's header only while it is collapsed. |
+| `resizable` | `boolean` | `true` | no | Enable the draggable resize edge on the right border. When `true`, the sidebar can be resized between the expanded-width token and twice that value. |
+| `resizeAriaLabel` | `string` | `'Resize sidebar'` | no | Accessible label for the resize edge (`role="separator"`). Consumers should localize this string for i18n. |
+| `resizeTooltipExpanded` | `ReactNode` | `(English tooltip: Resize/Collapse/Reset)` | no | Tooltip content shown when the sidebar is expanded. Pass `null` to hide the tooltip entirely. Consumers should localize for i18n. |
+| `resizeTooltipCollapsed` | `ReactNode` | `(English tooltip: Resize/Expand)` | no | Tooltip content shown when the sidebar is collapsed. Pass `null` to hide the tooltip entirely. Consumers should localize for i18n. |
+| `expandTooltip` | `ReactNode` | `'Expand'` | no | Tooltip text shown on the collapse trigger when the sidebar is collapsed. Consumers should localize this string for i18n. |
+| `extras-variant` | `'tag' | 'externalLink' | 'shortcut' | 'tag-externalLink'` | — | yes | Which trailing affordance the extras part renders. React: the `variant` prop on `SidebarSecondaryMenuItemExtras`. (Named here without the bare `variant` key reserved for a root cva axis.) |
+| `shortcut` | `string` | `undefined` | no | Keyboard-shortcut text for the extras `shortcut` variant. |
+| `tag` | `ReactNode` | `undefined` | no | Tag content for the extras `tag` / `tag-externalLink` variants. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `expanded-change` | `boolean` | Fires when the panel expanded state changes. React: `onExpandedChange`. |
+| `open-change` | `boolean` | Fires when an expandable row's disclosure opens/closes (Base UI Collapsible). React: `onOpenChange` on the menu-sub part. |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | The composed panel. Author it from the parts: a header, a scrollable content region of sections (each with an optional label and a menu of fixed and expandable rows), and a footer. The collapsed-breadcrumb is rendered automatically by the root. |
+
+## Behavior
+
+### Structure
+
+#### Renders a navigation landmark
+
+**Given** a SidebarSecondary wrapping a header, content, and footer
+**When** the component renders
+**Then** the root is a `<nav>` with a distinguishing `aria-label`
+**And** the header renders an `<h2>` heading
+**And** each menu is a `<ul>` of `<li>` rows
+
+#### Sections divide the menu
+
+**Given** more than one SidebarSecondarySection
+**When** the panel renders
+**Then** the first section has no top divider
+**And** every following section carries a top border
+**And** a SidebarSecondarySectionLabel renders above its menu when provided
+
+---
+
+### Selection
+
+#### Marks the current route
+
+**Given** a SidebarSecondaryMenuItem (or sub-trigger / sub-item) with `selected`
+**When** the panel renders
+**Then** the row applies the `selected` **container** token
+**And** it carries `aria-current="page"`
+**And** its icon and label use the shared global state tokens (same as unselected)
+
+---
+
+### Expand / collapse (panel width)
+
+#### Defaults to expanded
+
+**Given** a SidebarSecondary with no `expanded` / `defaultExpanded`
+**When** it renders
+**Then** the root has `data-state="expanded"` (256px width)
+**And** the section list (content) is shown; the collapsed-breadcrumb is hidden
+
+#### Collapses to a breadcrumb rail
+
+**Given** `expanded={false}`
+**When** it renders
+**Then** the root has `data-state="collapsed"` (48px width)
+**And** the header is hidden
+**And** the content section list is hidden
+**And** the collapsed-breadcrumb is shown: parent → separator → current page
+**And** the breadcrumb labels render vertically (`writing-mode: vertical-rl`)
+**And** menu-item labels (when any rows remain) are kept in the DOM as `sr-only`
+
+> The content and the collapsed-breadcrumb are both authored and present in the
+> DOM; visibility is toggled purely by `data-[state]` selectors (SSR-safe, no JS
+> branch).
+
+---
+
+### Disclosure (expandable sections)
+
+#### Toggles a section's menu
+
+**Given** a `SidebarSecondarySection` with `expandable`
+**When** the user activates the section-label header
+**Then** `aria-expanded` flips and the section's menu collapses/expands
+**And** the header chevron rotates
+
+#### Opens initially / is controllable
+
+**Given** an expandable section with `defaultOpen`
+**When** it renders
+**Then** the disclosure is open initially
+**And** `open` / `onOpenChange` allow controlled use (Base UI Collapsible)
+**And** each expandable section has independent open state
+
+---
+
+### Extras
+
+#### Shortcut / external link
+
+**Given** a SidebarSecondaryMenuItemExtras with `variant="shortcut"` / `"externalLink"`
+**When** the item renders expanded
+**Then** the shortcut text / external-link icon appears trailing the label
+
+#### Hidden when collapsed
+
+**Given** any extras inside a menu item
+**When** the panel is collapsed
+**Then** the extras cluster is hidden
+
+### Expandable section
+
+#### Toggle a section
+
+**Given** a `SidebarSecondarySection` with `expandable`
+**When** the user activates its section-label header
+**Then** the section's menu collapses/expands and the header chevron rotates
+(`aria-expanded` flips); an uncontrolled section starts open
+
+#### Header actions stay operable
+
+**Given** an expandable section-label with an `actions` slot (e.g. a ButtonIcon)
+**When** the user activates the action
+**Then** the action fires and the section does **not** toggle (the action is a
+sibling of the toggle, never nested in it)
+
+#### Unread rollup while collapsed
+
+**Given** an expandable section-label with an `unreadRollup` badge
+**When** the section is collapsed
+**Then** the rollup badge shows in the header; it hides again when expanded
+
+#### Items inside expandable sections are indented
+
+**Given** a `SidebarSecondaryMenuItem` inside an expandable section
+**When** the section is open
+**Then** items are left-indented so their label aligns with the section header text
+
+## Accessibility
+
+A contextual list of navigation links with an optional disclosure level. It is a
+`navigation` landmark, **not** a `menu`/`menubar` widget — interaction is native
+tab order, not arrow-key roving.
+
+## ARIA Roles and Attributes
+
+### Root (`nav`)
+
+| Attribute    | Value                    | Reason                                           |
+| ------------ | ------------------------ | ------------------------------------------------ |
+| `<nav>`      | —                        | Exposes the panel as a navigation landmark       |
+| `aria-label` | contextual (overridable) | Distinguishes it from other `nav` landmarks      |
+| `data-state` | `expanded`/`collapsed`   | Reflects the width state; drives token switching |
+
+### Header
+
+The header renders an `<h2>` so the panel's section title is in the heading
+outline.
+
+### Menu / items
+
+- Each menu is a `<ul>` of `<li>` rows; leaves render a native `<a>` (or the
+  element supplied via `render`).
+- The selected row carries `aria-current="page"`.
+
+### Disclosure (expandable rows)
+
+Base UI `Collapsible` wires the disclosure semantics automatically — the trigger
+is a `<button>` with `aria-expanded` and `aria-controls`, and the panel gets a
+matching `id` and `hidden` state. This is the primary reason the expandable row
+uses the primitive.
+
+### Collapsed (breadcrumb rail)
+
+When collapsed, the section list is hidden and a vertical breadcrumb is shown
+(parent → separator → current page). The separator icon is decorative
+(`aria-hidden`). Any menu-item labels that remain are kept in the DOM as
+`sr-only`, never `display:none`.
+
+---
+
+## Keyboard Navigation
+
+| Key         | Element     | Action                          |
+| ----------- | ----------- | ------------------------------- |
+| Tab         | Row         | Moves focus to the next row     |
+| Shift+Tab   | Row         | Moves focus to the previous row |
+| Enter       | Link row    | Activates / navigates           |
+| Enter/Space | Sub-trigger | Toggles the disclosure          |
+
+No roving tabindex — this is a list of links plus disclosure buttons, not a
+`menu`/`menubar`.
+
+---
+
+## Focus
+
+A keyboard-focused row shows a visible focus ring using the shared
+`--ui-focus-brand` token (inset, so it stays inside the 48px collapsed rail).
+
+---
+
+## Screen Reader Requirements
+
+1. The navigation landmark is announced with its label.
+2. The header announces as a level-2 heading.
+3. Each row announces its label as a link; the selected row announces
+   `aria-current="page"`.
+4. Disclosure triggers announce expanded/collapsed state.
+5. Collapsed rows still announce their (sr-only) label.
+
+---
+
+## Color and Contrast
+
+| Element                        | Minimum Ratio | Standard               |
+| ------------------------------ | ------------- | ---------------------- |
+| Menu-item label vs container   | 4.5:1         | WCAG 1.4.3 (AA)        |
+| Menu-item icon vs container    | 3:1           | WCAG 1.4.11 (non-text) |
+| Selected container vs panel bg | 3:1           | WCAG 1.4.11            |
+| Breadcrumb separator icon      | 3:1           | WCAG 1.4.11 (non-text) |
+| Focus indicator                | 3:1           | WCAG 1.4.11            |
+
+---
+
+## Testing Checklist
+
+- [ ] `<nav>` root with a distinguishing `aria-label`; header is an `<h2>`
+- [ ] Menus are `<ul>` of `<li>` rows; rows are links
+- [ ] Selected row has `aria-current="page"`; others do not
+- [ ] `data-state` reflects expanded/collapsed; breadcrumb shows when collapsed
+- [ ] Disclosure trigger exposes `aria-expanded` / `aria-controls`; toggles on click + Enter/Space
+- [ ] Level-2 sub-items are indented and reachable via Tab when open
+- [ ] Collapsed rows keep an accessible name (sr-only label, not removed)

package/dist/llms/skeleton.md

@@ -0,0 +1,81 @@
+# Skeleton
+
+> A pulsing placeholder box for loading states. Shape and size come from the caller's className. Ported from the legacy shadcn-uikit `skeleton`.
+
+**Status:** draft · **Category:** feedback · **Since:** v0.48.0
+
+## Import
+
+```tsx
+import { Skeleton } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<Skeleton className="h-4 w-[250px]" />
+```
+
+A pulsing placeholder box for loading states. Shape and size come from the
+caller's `className`.
+
+> Design-pending v1, ported from the legacy shadcn-uikit `skeleton`.
+
+## When to use
+
+- Reserve layout space while content loads, reducing layout shift.
+
+## When not to use
+
+- Indeterminate work with no known shape — use `Loading`.
+- Determinate progress — use `Progress` / `ProgressCircle`.
+
+## Parts
+
+| Export     | Purpose                          |
+| ---------- | -------------------------------- |
+| `Skeleton` | The pulsing placeholder `<div>`. |
+
+## Example
+
+```tsx
+import { Skeleton } from '@acronis-platform/ui-react';
+
+<div className="flex items-center gap-4">
+  <Skeleton className="size-12 rounded-full" />
+  <div className="flex flex-col gap-2">
+    <Skeleton className="h-4 w-[250px]" />
+    <Skeleton className="h-4 w-[200px]" />
+  </div>
+</div>;
+```
+
+## Behavior
+
+```gherkin
+Scenario: Placeholder while loading
+  Given content is not ready
+  Then a Skeleton renders a pulsing box at the caller's size/shape
+  When the content arrives
+  Then the caller swaps the Skeleton for the real content
+```
+
+```gherkin
+Scenario: Shape from className
+  Given a Skeleton with className="size-12 rounded-full"
+  Then it renders a 48px circular placeholder
+```
+
+## Accessibility
+
+- A Skeleton is decorative — it conveys "loading" visually. It has no inherent
+  ARIA semantics; announce loading at the region level instead (e.g. an
+  `aria-busy="true"` container, or a visually-hidden "Loading…" message), so
+  screen-reader users are told content is pending rather than reading empty boxes.
+- Don't put meaningful text inside a Skeleton.
+
+## Contrast
+
+Skeleton is a non-informational placeholder, so it's exempt from text-contrast
+requirements; the fill (`--ui-background-surface-active`) is a visible-but-subtle
+gray against the page in both themes.

package/dist/llms/slider.md

@@ -0,0 +1,97 @@
+# Slider
+
+> A slider for choosing a number (or a range, with two thumbs) within a min/max by dragging. Built on Base UI's Slider. Ported from the legacy shadcn-uikit `slider`.
+
+**Status:** draft · **Category:** forms · **Since:** v0.50.0
+
+## Import
+
+```tsx
+import { Slider } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<Slider defaultValue={40} aria-label="Volume" />
+```
+
+A slider for choosing a number — or a range (two thumbs) — within a min/max by
+dragging. Built on Base UI's Slider.
+
+> Design-pending v1, ported from the legacy shadcn-uikit `slider`.
+
+## When to use
+
+- Picking an approximate value across a continuous range (volume, opacity, price).
+
+## When not to use
+
+- Precise numeric entry — use a `NumberField` / `InputText`.
+- A small set of discrete choices — use `RadioGroup` or `ToggleGroup`.
+
+## Parts
+
+`Slider` is a single component (the track / indicator / thumb are rendered
+internally). Pass an array value for a range.
+
+## Example
+
+```tsx
+import { Slider } from '@acronis-platform/ui-react';
+
+<Slider defaultValue={40} aria-label="Volume" />
+<Slider defaultValue={[20, 80]} aria-label="Price range" />
+```
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `value` | `number | number[]` | — | no | The value(s) (controlled). An array renders a range (one thumb each). |
+| `defaultValue` | `number | number[]` | `0` | no | The initial value(s) (uncontrolled). |
+| `min` | `number` | `0` | no | Minimum value. |
+| `max` | `number` | `100` | no | Maximum value. |
+| `step` | `number` | `1` | no | Step increment. |
+| `disabled` | `boolean` | `false` | no | Disables the slider. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `onValueChange` | `(value: number | number[], eventDetails) => void` | Fired as the value changes while dragging. |
+
+## Behavior
+
+```gherkin
+Scenario: Drag to change the value
+  Given a Slider with a value
+  When the user drags the thumb (or uses arrow keys)
+  Then the value updates and onValueChange fires, clamped to min/max and snapped to step
+```
+
+```gherkin
+Scenario: Range
+  Given a Slider with an array value [low, high]
+  Then two thumbs render and each is dragged independently (they cannot cross)
+```
+
+```gherkin
+Scenario: Disabled
+  Given disabled is set
+  Then the thumb cannot be focused or dragged
+```
+
+## Accessibility
+
+- Built on Base UI's Slider: each thumb is keyboard-operable (←/→/↑/↓, Home/End,
+  PageUp/PageDown) and exposes `aria-valuenow` / min / max so assistive tech reads
+  the current value.
+- Give the slider an accessible name — `aria-label` on `Slider`, or pair it with a
+  `Field` / `FieldLabel`. For a range, label each end if they have distinct meaning.
+
+## Contrast
+
+The filled indicator (`--ui-background-brand-secondary`) against the rail
+(`--ui-border-on-surface-border`) and the thumb border are distinguishable in light
+and dark; the focus ring uses `--ui-focus-primary`.