@acronis-platform/ui-react 4.1.0 → 5.1.0

package/dist/llms/input-select.md

@@ -45,7 +45,10 @@ The next-gen select **field**: a label (with an optional required marker), a tri
 box showing the value / placeholder and a chevron, an optional description or error,
 and a floating dropdown with an in-dropdown search, sections, single- or
 multiple-selectable items, and loading / empty / error status. It composes Base UI
-`Select` and the `--ui-input-select-*` token tier.
+`Select` and the `--ui-input-select-*` token tier. The dropdown's placement is
+controllable (`side` / `align` / offsets / collision avoidance, or an explicit
+`anchor` element to position against instead of the trigger), and
+`is-popover-styled` swaps its chrome to the popover look — see `behavior.md`.
 
 > `Select` is an alias of this family (re-pointed off the deleted `--ui-form-*` tier).
 > Prefer importing `InputSelect*` directly in new code.
@@ -151,6 +154,14 @@ use it inside a custom tree/item renderer to filter items the flat
 | `name` | `string` | — | no | Form field name submitted with the form (via a hidden input). |
 | `placeholder` | `string` | — | no | Hint shown by the value part when nothing is selected. |
 | `items` | `Record<string, string>` | — | no | Map of value → label for every selectable option, so the value part can render a selected option's label while the popup is closed without inspecting the rendered items. |
+| `side` | `'top' | 'bottom' | 'left' | 'right' | 'inline-start' | 'inline-end'` | `'bottom'` | no | On the content — which side of the trigger the popup renders on. |
+| `align` | `'start' | 'center' | 'end'` | `'start'` | no | On the content — alignment along the chosen side. |
+| `side-offset` | `number` | `4` | no | On the content — distance in px from the trigger. |
+| `align-offset` | `number` | `0` | no | On the content — offset in px along the alignment axis (perpendicular to `side`), to nudge the popup along the trigger's edge without changing its alignment. |
+| `collision-avoidance` | `{ side?: 'flip' | 'shift' | 'none'; align?: 'flip' | 'shift' | 'none'; fallbackAxisSide?: 'start' | 'end' | 'none' }` | `the platform default (flip/shift)` | no | On the content — collision-avoidance strategy. Pass `{ side: 'none', fallbackAxisSide: 'none' }` alongside an explicit `side`/`align` to lock the popup to that placement with no auto-flip fallback. |
+| `anchor` | `Element | VirtualElement | RefObject<Element | null> | (() => Element | VirtualElement | null) | null` | `the trigger element` | no | On the content — element (or ref/getter) the popup positions itself against, overriding the default of anchoring to the trigger. Use when the visible trigger isn't the element tracked internally — e.g. an external button drives a hidden trigger, and the popup should align with the button instead. |
+| `portal-container` | `Element | ShadowRoot | null | RefObject<Element | ShadowRoot | null>` | `nearest PortalContainerProvider, or document.body` | no | On the content — container to portal the dropdown into. Pass an element to scope the portal (e.g. a shadow root, so the popup inherits styles defined there). |
+| `is-popover-styled` | `boolean` | `false` | no | On the content — render the dropdown chrome like `PopoverContent` (fade/zoom/slide animation, no shadow) instead of the default static-shadow dropdown chrome. |
 
 ## Events
 
@@ -229,6 +240,112 @@ border.
 **Then** it shows the matching icon and message (and, for `error`, an optional retry
 action).
 
+### Popup placement and chrome
+
+**Given** no positioning props on the content
+**When** the popup opens
+**Then** it is placed against the **trigger**, below it and aligned to its start
+edge, and the platform's own collision handling may flip or shift it to keep it in
+view. `side` / `align` / `side-offset` / `align-offset` / `collision-avoidance`
+each override one part of that; passing `collision-avoidance` with no fallbacks
+alongside an explicit `side` pins the popup to that placement even when it
+overflows.
+
+**Given** an `anchor` on the content
+**When** the popup opens
+**Then** it positions itself against **that** element instead of the trigger,
+decoupling where the popup appears from where the trigger sits in layout. This is
+for the case where the element the user actually operates is not the trigger — an
+external button drives the open state and the trigger stays mounted but visually
+hidden — so the popup should align with the button, not with the hidden trigger's
+position in flow. The trigger still owns the combobox semantics either way (see
+`accessibility.md`).
+
+**Given** an external button that drives a controlled `open` and is the popup's
+`anchor`
+**When** the user presses that button while the popup is open
+**Then** the platform reports the press as an **outside press** close before the
+button's own activation handler runs, so the consumer must cancel that specific
+close (`open-change` with `reason = outside-press` and the event target inside
+the button → `cancel()`) for the button to act as a toggle; otherwise the
+activation handler reopens the popup and it can never be dismissed from the
+button. A press outside both the button and the popup still closes it.
+
+**Given** an external button that drives a controlled `open`, with the real
+trigger kept mounted but visually hidden (screen-reader-only, not removed)
+**When** the popup closes via Escape or by selecting an item
+**Then** at the moment the close is reported focus is **still inside the popup
+that is about to unmount**, and the platform can move it to **its own trigger** —
+which is invisible — only **afterwards**, asynchronously. Neither path reports
+the close with focus already on the trigger. So the consumer must (a) mark the
+trigger `tab-index = -1` so it is never reached by Tab, and (b) reclaim focus for
+their visible external control themselves once the close is committed,
+**re-asserted once the platform's own focus-restore attempts have settled**. On
+Escape, a gate that recognizes "focus is still inside the closing popup" matches
+at the moment of the synchronous reclaim and moves focus to the external control
+before the platform's own move happens, so nothing overwrites it afterwards; the
+deferred re-assertion then finds the external control already focused and is a
+no-op. On item selection, the same synchronous reclaim also lands, but the
+platform's async move to the hidden trigger can still happen afterwards and pull
+focus back onto it — so the deferred re-assertion is load-bearing on this path,
+not a no-op, and reclaims focus a second time once that move has settled. Doing
+only one of (a)/(b) is a WCAG 2.4.7 failure: `tab-index = -1` does not block the
+platform's programmatic focus call, and the manual reclaim alone leaves an
+invisible control in the tab order. The reclaim belongs after the state commit
+in the same `open-change` handler, so a close the consumer cancels (see below)
+does not move focus.
+
+**Given** the same visually hidden trigger
+**When** the popup closes because of an outside press onto **nothing focusable**
+(a blank area of the page)
+**Then** the platform performs **no** focus restore at all — focus is simply lost
+to the document body. The consumer's own reclaim is the only thing that recovers
+it, so it must cover this case too, not just the trigger-focused one.
+
+**Given** the same visually hidden trigger
+**When** the popup closes because of an outside press onto **another focusable
+element** (an input elsewhere on the page)
+**Then** focus must end up on **that** element, not on the external button — the
+user deliberately focused it and pulling focus back is a bug. The platform
+reports this close **once** (reason = outside press), while focus is still inside
+the popup, so a gate keyed on "focus is unclaimed" (still inside the closing
+popup, on the hidden trigger, or on the document body) **does** match on that
+single report and does issue its focus call. The correct end state comes from the
+platform's own native focus move to the pressed element happening **after** that
+synchronous call and overriding it — not from the gate recognizing and skipping
+this case. What the gate does guarantee is that the **deferred** re-assertion
+cannot undo that: by the time it runs the pressed element holds focus, which is
+not an unclaimed state, so it is a no-op. An unconditional focus return on close
+is therefore still wrong — it would fire again after the platform's move and
+steal focus back.
+
+**Given** a cancelled close (the consumer called `cancel()` on `open-change`)
+**When** the popup therefore stays open
+**Then** the in-dropdown search query is **preserved** — a cancelled close does
+not silently clear what the user typed. (A consumer that leaves the close
+un-cancelled but simply doesn't act on it still gets the query reset; cancelling
+is what marks the close as not taking effect.)
+
+**Given** an external button that drives a controlled `open` and closes the
+popup directly (its own handler sets `open = false`, so the platform never
+reports the transition through `open-change`)
+**When** the popup is reopened
+**Then** the in-dropdown search query is **empty** — the reset follows the
+`open` prop's `true → false` transition as well as `open-change`, so a
+button-driven close cannot carry a stale query into the next open.
+
+**Given** `is-popover-styled`
+**When** the popup opens
+**Then** its container chrome is drawn from the **popover** tokens rather than the
+dropdown ones (fill / border / corner radius), the dropdown's static shadow is
+dropped, and open/close is animated (fade + zoom, sliding in from the resolved
+`side`) instead of appearing instantly. Reach for it when the dropdown is acting
+as a floating menu that should read in the same visual language as `Popover` —
+a tenant/entity picker opened from a page control, not a plain form field's
+option list. It changes only the container chrome and the enter/exit transition:
+the popup still sizes to the anchor width, keeps the dropdown's vertical padding,
+and every row inside (search, sections, items, status) is unchanged.
+
 ### Interaction
 
 **Given** the trigger
@@ -264,6 +381,63 @@ action).
   Arrow-key roaming inside the listbox skips it entirely — it cannot be
   reached with the keyboard once the popup is open, only by pointer. It
   remains a normal native tab stop outside that roving focus order.
+- **Decoupled anchor:** `anchor` moves only where the popup is _drawn_ — the
+  combobox semantics (`aria-expanded`, `aria-controls`, the accessible name) and
+  the focus return on close stay on the **trigger**, and cannot be relocated. So
+  if the visible control is a separate element (an external button opening a
+  visually hidden trigger), that button needs its own accessible name (visible
+  text or `aria-label`) and, because it is the control the user actually
+  operates, its own `aria-expanded` bound to the same controlled `open` state
+  that drives the popup. `aria-controls` on the button is optional and only
+  wirable by giving `InputSelectContent` an explicit `id` and referencing it
+  while the popup is open. Keep the trigger reachable — do not `display: none`
+  it, or closing returns focus to nothing. Prefer opening from the real trigger
+  whenever the design allows it.
+- **Visually hidden trigger — focus is the consumer's job (2.4.7):** leaving the
+  trigger merely `sr-only`-reachable is **not** sufficient. It is still
+  focusable while invisible, and on the close paths where the platform restores
+  focus to it (Escape, selecting an item) keyboard focus lands on a control the
+  user cannot see — a WCAG 2.4.7 Focus Visible failure. On other close paths
+  (an outside press onto nothing focusable) the platform does not restore focus
+  at all and it is simply lost to the document body — also a failure. The
+  required pattern is **both** of:
+  1. `tabIndex={-1}` on the **trigger** (`InputSelectTrigger`) — not on the
+     `InputSelectField` wrapper, which is a plain non-focusable element — so the
+     invisible trigger is out of the natural Tab sequence;
+  2. a **conditional** focus return to the consumer's own visible control on
+     close (`onOpenChange` → after committing the new state, `if (!nextOpen)`
+     reclaim focus for the external button). Two properties of the platform make
+     this non-trivial. First, **the platform's own focus restore may still be
+     pending when the close is reported** — on the Escape and item-selection
+     paths focus is still inside the popup that is about to unmount at handler
+     time, and the move to the (invisible) trigger can land afterwards. On
+     Escape a synchronous reclaim already lands on the visible control before
+     that move happens, so nothing overwrites it; on item selection the
+     platform's move can still land on the hidden trigger after a synchronous
+     reclaim, so the reclaim must be re-asserted once that settles. Second,
+     **on some close reasons the platform's restore does not happen at all** —
+     an outside press onto nothing focusable leaves focus on the document
+     body. So the focus return must be **re-asserted once the platform's own
+     focus-restore attempts have settled**, not only synchronously during the
+     handler — even where the synchronous call already suffices, the deferred
+     re-assertion is a harmless no-op.
+     Crucially, the reclaim must **never override an element the user has
+     legitimately focused since** — an outside press onto another focusable
+     control is that user's choice of focus, and an unconditional refocus steals
+     it. Gate the reclaim on focus being _unclaimed_: still inside the closing
+     popup, on the hidden trigger, or lost to the document body. Anything else
+     is left alone.
+     `tabIndex={-1}` alone does not stop the platform's programmatic `.focus()`
+     call, and the reclaim alone leaves the invisible trigger in the Tab order —
+     each fixes one half. The reclaim must sit after the state commit, so the
+     cancelled `outside-press` branch (which returns early) does not move focus
+     for a close that never happened.
+- **External-button toggle:** an external button must also cancel the
+  `outside-press` close that its own pointerdown triggers (`onOpenChange` →
+  `eventDetails.reason === 'outside-press'` and the event target inside the
+  button → `eventDetails.cancel()`), otherwise the popup cannot be dismissed
+  from the button at all — a keyboard/AT user who activates the button a second
+  time gets a popup that reopens instead of closing. Escape still closes it.
 - **Selection indicator:** single-select shows a trailing check on the selected item;
   multiple-select shows a leading checkbox per item (not focusable — the row is the
   control).

package/dist/llms/line-chart.md

@@ -108,12 +108,13 @@ across brands until the real data-viz palette lands.
 | `yAxisLabel` | `string` | — | no | Title rendered beside the vertical (Y) axis (rotated). |
 | `yUnit` | `string` | — | no | Unit suffix appended to Y-axis tick values (recharts `unit`); the X axis is categorical. |
 | `strokeWidth` | `number` | `2` | no | Stroke width of each line. |
-| `showDots` | `boolean` | `true` | no | Render a dot at each data point. |
+| `showDots` | `boolean` | `false` | no | Render a dot at each data point. |
 | `dotSize` | `number` | `3` | no | Radius of each point's dot, in px. Its hover dot is 2px larger. |
 | `showActiveDot` | `boolean` | — | no | Enlarge the hovered point's dot. Defaults to following `showDots`, so set it explicitly for a hover-only line (dots off, active dot on) or a static-only line (dots on, active dot off). |
 | `lineSettings` | `Record<string, { color?: string; strokeWidth?: number; dashed?: boolean; curveType?: CurveType; showDots?: boolean; dotSize?: number; showLabel?: boolean; labelPosition?: LabelPosition }>` | — | no | Per-series style override keyed by `dataKeys` entry — anything unset falls back to the chart-wide prop, so an entry states only what differs. A series listed in `comparisonKeys` keeps its dashed, dimmed, dot-less treatment: `color` / `strokeWidth` / `curveType` still apply to it, but `showDots` / `dotSize` do not. |
 | `referenceLine` | `Line | Line[]  where Line = { value?: number; average?: boolean | string; label?: string; labelPosition?: 'top' | 'insideTopLeft' | 'insideTopRight' | 'insideBottomLeft' | 'insideBottomRight' }` | — | no | One or more dashed reference/average lines on the value axis. Pass a single object or an array. Per line, a fixed `value` wins; otherwise the mean of one series (`average: '<key>'`) or of every plotted series (`average: true`, which includes any `comparisonKeys` overlay). An optional `label` captions each, at the rule's top right unless `labelPosition` moves it away from a series it would sit on. The same config shape as `BarChart` / `AreaChart`. |
 | `connectNulls` | `boolean` | `false` | no | Bridge `null` gaps in the data instead of breaking the line. |
+| `projectionStart` | `string | number` | — | no | The category value (matching an `xKey` entry) at which the projection zone starts. Ticks from this point onward render in the disabled text color. The actual series are clipped to the left of the boundary; a dashed, dot-less projection continuation renders on the right. Comparison series (`comparisonKeys`) are excluded from the projection split and render unclipped across the full width. |
 | `showGrid` | `boolean` | `true` | no | Render the CartesianGrid. |
 | `showTooltip` | `boolean` | `true` | no | Render the hover tooltip. |
 | `showLegend` | `boolean` | `true` | no | Render the legend. |

package/dist/llms/metric.md

@@ -57,7 +57,7 @@ GROSS MARGIN                 [Last 30 days]   ← label + caption
 ## Composition
 
 Metric is a Card. Put the trend in the `trend` slot (a `TrendIndicator`), a
-timeframe in `caption` (a `Tag`), and drop a chart / `Meter` breakdown /
+timeframe in `caption` (a `Tag`), and drop a chart / labelled-bar breakdown /
 `Separator` / insight line into `children`:
 
 ```tsx
@@ -76,11 +76,16 @@ timeframe in `caption` (a `Tag`), and drop a chart / `Meter` breakdown /
     />
   }
 >
-  <Meter
-    label="Healthy"
-    value={46}
+  <BarChart
+    orientation="horizontal"
+    items={[
+      {
+        label: 'Healthy',
+        value: 46,
+        color: 'var(--ui-background-status-strong-success)',
+      },
+    ]}
     max={54}
-    color="var(--ui-background-status-strong-success)"
   />
   <Separator className="my-3" />
   <p>+3 customers predicted at-risk within 30 days.</p>

package/dist/llms/radar-chart.md

@@ -98,8 +98,8 @@ across brands until the real data-viz palette lands.
 | `seriesSettings` | `Record<string, RadarChartSeriesSettings>` | — | no | Per-series style overrides keyed by a `dataKeys` entry — `color`, `stroke`, `fillOpacity`, `strokeWidth`, `dot`, `dotRadius`, `activeDot`. Unplotted keys are ignored. An overridden `color` — or `stroke`, which the renderer reads first — carries into that series' legend swatch and tooltip dot. |
 | `fillOpacity` | `number` | `0.3` | no | Fill opacity of each radar area. |
 | `strokeWidth` | `number` | `2` | no | Stroke width of each radar outline. |
-| `showDots` | `boolean` | `false` | no | Render a dot at each axis point. |
-| `dotRadius` | `number` | `3` | no | Radius of the per-point dots when `showDots` is on. |
+| `showDots` | `boolean` | `true` | no | Render a dot at each axis point. Visible by default to match the Figma chart. |
+| `dotRadius` | `number` | `2` | no | Radius of the per-point dots when `showDots` is on. |
 | `activeDot` | `boolean` | `true` | no | Enlarge the hovered point's dot. On by default; `false` for a chart that should not react to the pointer. |
 | `showGrid` | `boolean` | `true` | no | Render the polar grid (the web). |
 | `radialLines` | `boolean` | `true` | no | Draw the grid's spokes (the radial lines out to each category). Off leaves only the concentric rings. |
@@ -117,15 +117,14 @@ across brands until the real data-viz palette lands.
 | `radiusAxisTickCount` | `number` | `5` | no | Desired number of ticks on the value scale (a hint, not exact). Also sets how many rings the grid draws, whether or not the scale is shown. |
 | `radiusAxisReversed` | `boolean` | `false` | no | Invert the value scale (maximum at the centre) for a metric where less is better. |
 | `cx` | `number | string` | `'50%'` | no | Horizontal centre of the web, in px or a percentage of the width. |
-| `cy` | `number | string` | `'50%'` | no | Vertical centre of the web, in px or a percentage of the height. |
+| `cy` | `number | string` | `the middle of the plot band` | no | Vertical centre of the web, in px or a percentage of the height. Defaults to the middle of the plot band — 50% of what the legend leaves, not of the whole box — because the underlying chart centres a polar plot on the whole surface and takes no account of the legend band beneath it. |
 | `startAngle` | `number` | `90` | no | Angle the first category sits at, in degrees. |
 | `endAngle` | `number` | `-270` | no | Angle the sweep ends at, in degrees — a full clockwise turn from `startAngle` by default. |
 | `innerRadius` | `number | string` | `0` | no | Radius of the hole at the centre, in px or a percentage of the available radius. Lifts the grid and the areas off the centre. |
-| `outerRadius` | `number | string` | `'80%'` | no | Outer radius of the web, in px or a percentage of the available radius. |
+| `outerRadius` | `number | string` | `78` | no | Outer radius of the web, in px or a percentage of the available radius. Defaults to 78px to match the Figma geometry; the legend and labels do not change the radius. |
 | `margin` | `{ top?: number; right?: number; bottom?: number; left?: number }` | — | no | Plot-area margin, in px. Passing the object replaces all four sides; a side left out is `0`, not the default `5`, so name every side. |
 | `showTooltip` | `boolean` | `true` | no | Render the hover tooltip. |
 | `showLegend` | `boolean` | `true` | no | Render the legend. |
-| `legendPosition` | `'top' | 'bottom'` | `'bottom'` | no | Which side of the chart the legend sits on. |
 | `tooltipContent` | `ReactElement | ((props) => ReactNode)` | — | no | Replace the default tooltip. Pass a configured ChartTooltipContent (from this library) — e.g. with a formatter / labelFormatter — to customize the tooltip content without composing recharts. Ignored when showTooltip is false. |
 | `animate` | `boolean` | `false` | no | Enable entrance animation. Off by default so output/baselines are unchanged. |
 | `animationDuration` | `number` | — | no | Animation duration in ms. |
@@ -231,6 +230,17 @@ Scenario: Geometry
   Then the web, its axes, and the areas are all laid out to match
 ```
 
+```gherkin
+Scenario: The box holds the category labels
+  Given a fixed outerRadius
+  Then the chart reserves a plot band tall enough for the outer category labels
+    — the outer radius, the tick size, and half a line of tick text on each side
+  And showLabels, which widens the tick gap, widens that band with it
+  And the web is centred on the plot band rather than on the whole box, so the
+    bottom label clears the legend and the top one clears the upper edge
+  And a caller-supplied height or cy wins over both
+```
+
 ```gherkin
 Scenario: Tooltip on hover
   Given showTooltip is true

package/dist/llms/scatter-chart.md

@@ -106,6 +106,7 @@ across brands until the real data-viz palette lands.
 |------|------|---------|----------|-------------|
 | `series` | `ScatterSeries[]` | — | yes | One `<Scatter>` per entry, each `{ key, data }` with its own point array. `key` matches a `config` entry and drives its `--color-<key>` fill. A single entry gives an ungrouped scatter. |
 | `config` | `ChartConfig` | — | yes | Series take their colour from the container's `palette`; each entry, keyed by a `series[].key`, maps that series to a `label` and an optional `tone`. Resolved into the `--color-<key>` custom properties the points fill from. |
+| `palette` | `ChartPalette` | `{ type: 'diverging', pair: 'teal-violet' }` | no | The dataviz palette this chart's series are painted from. Defaults to diverging teal-violet, matching the Figma reference design. |
 | `xKey` | `string` | — | yes | Numeric field for the horizontal axis. |
 | `yKey` | `string` | — | yes | Numeric field for the vertical axis. |
 | `xAxisLabel` | `string` | — | no | Title rendered beneath the horizontal (X) axis. |
@@ -127,7 +128,7 @@ across brands until the real data-viz palette lands.
 | `xAxisInterval` | `number | 'preserveStart' | 'preserveEnd' | 'preserveStartEnd' | 'equidistantPreserveStart'` | — | no | X-axis tick density — a recharts placement strategy, or a fixed number of ticks to skip between two rendered ones (recharts interval: 0 shows every tick, 1 every other one, 2 every third). |
 | `yAxisTickCount` | `number` | — | no | Desired number of ticks on the value axis (recharts tickCount; a hint, not exact). Applies to whichever axis holds the values — Y for most charts, X for BarChart with orientation="horizontal". |
 | `yAxisDomain` | `'auto' | 'dataMin-dataMax' | 'zero'` | — | no | Value-axis domain preset — auto (fit the data at both ends; the axis need not include 0), zero (anchor the axis at 0, which is also recharts' behaviour when the prop is omitted), or dataMin-dataMax (tight to the data, no padding). Applies to whichever axis holds the values — Y for most charts, X for BarChart with orientation="horizontal". |
-| `gridDashed` | `boolean` | — | no | Draw grid lines dashed instead of solid. |
+| `gridDashed` | `boolean` | `true` | no | Draw grid lines dashed instead of solid. |
 | `gridHorizontal` | `boolean` | — | no | Show horizontal grid lines (defaults to the chart's own default when unset). |
 | `gridVertical` | `boolean` | — | no | Show vertical grid lines (defaults to the chart's own default when unset). |
 | `animate` | `boolean` | `false` | no | Enable entrance animation. Off by default so output/baselines are unchanged. |

package/dist/llms/separator.md

@@ -2,7 +2,7 @@
 
 > A thin rule that visually and semantically divides content. Built on the Base UI Separator primitive (sets the `separator` role + aria-orientation). Ported from the legacy shadcn-uikit `Separator`; uses the shared divider token.
 
-**Status:** draft · **Category:** layout · **Since:** v0.15.0
+**Status:** ready · **Category:** layout · **Since:** v0.15.0
 
 ## Import
 
@@ -15,14 +15,15 @@ import { Separator } from '@acronis-platform/ui-react'
 ```tsx
 <Separator className="my-4" />
 <Separator orientation="vertical" />
+<Separator size="S2" />
 ```
 
 A thin rule that divides content, horizontally or vertically.
 
-> **Status: draft (design-pending v1).** Ported from the legacy
-> `@acronis-platform/shadcn-uikit` `Separator`; uses the shared `bg-border`
-> divider token (no `--ui-separator-*` tier). Reconcile with
-> `/figma-component Separator <url> --update` once a mockup lands.
+> Ported from the legacy `@acronis-platform/shadcn-uikit` `Separator`; matched
+> to Figma's `DividerHorizontal` component set (node 788:15147). Uses the
+> shared `--ui-border-on-surface-divider` token directly (no `--ui-separator-*`
+> tier).
 
 ## When to use
 
@@ -46,6 +47,9 @@ import { Separator } from '@acronis-platform/ui-react';
   <Separator orientation="vertical" />
   <span>Recovery</span>
 </div>
+
+{/* size (S1/S2/S3, Figma default S1) applies built-in surrounding spacing */}
+<Separator size="S2" />
 ```
 
 ## Props
@@ -53,11 +57,12 @@ import { Separator } from '@acronis-platform/ui-react';
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
 | `orientation` | `'horizontal' | 'vertical'` | `'horizontal'` | no | Direction of the rule; sets aria-orientation and swaps the 1px dimension. |
+| `size` | `'S1' | 'S2' | 'S3'` | `'S1'` | no | Surrounding spacing baked into the rule (Figma variant `Size`). `S1` (default) has none; `S2`/`S3` apply `--ui-gap-4`/`--ui-gap-8` as margin on the axis perpendicular to the line. |
 
 ## Behavior
 
-Separator is a static divider. It has no props beyond `orientation`, no state,
-and no interaction.
+Separator is a static divider. It has no state and no interaction; its only
+props are `orientation` and `size`.
 
 ```gherkin
 Scenario: Horizontal rule (default)
@@ -72,6 +77,20 @@ Scenario: Vertical rule
   And it needs a sized (height-bearing) flex/inline context to be visible
 ```
 
+```gherkin
+Scenario: Default size has no built-in spacing
+  Given a Separator with no size
+  Then it renders with size="S1" and applies no surrounding margin
+```
+
+```gherkin
+Scenario: S2/S3 apply built-in surrounding spacing
+  Given a Separator with size="S2" or size="S3"
+  Then it applies --ui-gap-4 or --ui-gap-8 as margin on the axis
+    perpendicular to the rule (vertical margin for horizontal, horizontal
+    margin for vertical)
+```
+
 ## Accessibility
 
 - Renders `role="separator"` (Base UI), with `aria-orientation` reflecting the
@@ -83,5 +102,5 @@ Scenario: Vertical rule
 
 ## Contrast
 
-The line uses `--ui-border-on-surface-border`, which meets non-text contrast
+The line uses `--ui-border-on-surface-divider`, which meets non-text contrast
 against the page surface in light and dark themes.