@acronis-platform/ui-react 3.0.0 → 4.0.0

package/dist/llms/resizable.md

@@ -0,0 +1,195 @@
+# Resizable
+
+> A group of panels separated by draggable handles that let the user resize adjacent regions along one axis. Composable parts (panel group, panel, handle); the handle is a thin divider with an optional grab-bar grip and resizes its neighbouring panels on drag or arrow keys.
+
+**Status:** ready · **Category:** layout · **Since:** v0.23.0
+
+## Import
+
+```tsx
+import { ResizablePanelGroup, ResizablePanel, ResizableHandle } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<ResizablePanelGroup orientation="horizontal">
+  <ResizablePanel defaultSize={50}>One</ResizablePanel>
+  <ResizableHandle />
+  <ResizablePanel defaultSize={50}>Two</ResizablePanel>
+</ResizablePanelGroup>
+```
+
+A group of panels separated by draggable handles, letting users resize adjacent
+regions along one axis. Composable from a panel group, panels, and handles — the
+React adapter wraps [`react-resizable-panels`](https://github.com/bvaughn/react-resizable-panels).
+
+## When to use
+
+- Split layouts the user should be able to re-proportion: a sidebar + content, a
+  list + detail (master/detail), an editor + preview.
+- Any two-or-more-pane surface where a fixed split would be too rigid.
+
+## When not to use
+
+- Fixed layout chrome that shouldn't move — use a plain sidebar/grid.
+- Reordering or moving items — that's drag-and-drop, not resizing.
+- A single scrollable region — resizing needs at least two panels.
+
+## Parts
+
+| Part                  | Role                                                         |
+| --------------------- | ------------------------------------------------------------ |
+| `ResizablePanelGroup` | Container; sets the axis via `orientation` and tracks sizes. |
+| `ResizablePanel`      | A resizable region (`defaultSize` / `minSize` / `maxSize`).  |
+| `ResizableHandle`     | The draggable separator (cursor + border change on hover).   |
+
+## Examples
+
+```tsx
+import {
+  ResizablePanelGroup,
+  ResizablePanel,
+  ResizableHandle,
+} from '@acronis-platform/ui-react';
+
+// Horizontal split
+<ResizablePanelGroup orientation="horizontal" className="h-64 rounded border">
+  <ResizablePanel defaultSize={30} minSize={20}>
+    Sidebar
+  </ResizablePanel>
+  <ResizableHandle />
+  <ResizablePanel defaultSize={70}>Content</ResizablePanel>
+</ResizablePanelGroup>;
+
+// Vertical split (panels stacked)
+<ResizablePanelGroup orientation="vertical" className="h-96">
+  <ResizablePanel defaultSize={60}>Editor</ResizablePanel>
+  <ResizableHandle />
+  <ResizablePanel defaultSize={40}>Preview</ResizablePanel>
+</ResizablePanelGroup>;
+```
+
+> The group needs a bounded height (or width, when vertical) from its container —
+> set one on the group or its parent, as in the `h-64` / `h-96` above.
+
+## Theming
+
+Colors, sizes, and the cursor come from the `--ui-resizable-*` token tier in
+`@acronis-platform/tokens-pd` (generated from `@acronis-platform/design-tokens`)
+and resolve per brand/theme — see `tokens.yaml`. Don't hard-code values.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `orientation` | `'horizontal' | 'vertical'` | `horizontal` | no | Resize axis of the group (panel-group part). `horizontal` arranges panels in a row with vertical handles; `vertical` stacks them with horizontal handles. |
+| `defaultSize` | `number` | `undefined` | no | Initial size of a panel as a percentage of the group (panel part). Panels without one share the remaining space. |
+| `minSize` | `number` | `undefined` | no | Minimum size of a panel, in percent of the group (panel part). |
+| `maxSize` | `number` | `undefined` | no | Maximum size of a panel, in percent of the group (panel part). |
+| `collapsible` | `boolean` | `false` | no | Whether the panel can collapse below its `minSize` to a collapsed size (panel part). |
+| `disableResize` | `boolean` | `false` | no | Disable resizing through the handle or panel (`disabled` on the React `ResizableHandle` / `ResizablePanel`). Named `disableResize` here so it is not confused with a root-level disabled state — resizing is a per-part capability, the group is never globally "disabled". |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `resize` | `undefined` | Fired as a panel's size changes during a drag (panel part). The React adapter exposes this as the panel's `onResize` callback. |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | The composed group. Author it from the parts: a panel group wrapping panels, with a handle between each adjacent pair. |
+
+## Behavior
+
+Given/When/Then scenarios for the panel group, its panels, and the drag handle.
+
+### Dragging a handle resizes its neighbours
+
+- **Given** a horizontal panel group with two panels split 50/50 and a handle between them,
+- **When** the user drags the handle to the right,
+- **Then** the left panel grows and the right panel shrinks by the same amount,
+  staying within each panel's `minSize` / `maxSize`.
+
+### Sizes are clamped to min/max
+
+- **Given** a panel with `minSize={20}`,
+- **When** the user drags the handle past the point where that panel would fall below 20%,
+- **Then** the panel stops at 20% and the handle does not move further in that direction.
+
+### Keyboard resizing
+
+- **Given** keyboard focus on a handle,
+- **When** the user presses the Arrow keys along the resize axis (Left/Right for a
+  horizontal group, Up/Down for a vertical group),
+- **Then** the adjacent panels resize by a step, and **Home** / **End** jump to the
+  handle's min / max extent.
+
+### Orientation flips the axis
+
+- **Given** a group with `orientation="vertical"`,
+- **When** it renders,
+- **Then** the panels stack in a column, the handle becomes a horizontal divider
+  (`aria-orientation="horizontal"`), and the cursor over it is `ns-resize`.
+
+### Disabled handles don't resize
+
+- **Given** a handle (or its panels) is `disabled`,
+- **When** the user drags or arrow-keys it,
+- **Then** the panels do not resize through that handle.
+
+### Collapsible panels
+
+- **Given** a `collapsible` panel with a `minSize`,
+- **When** the user drags below that `minSize`,
+- **Then** the panel collapses to its collapsed size, and dragging back out (or
+  calling the panel's `expand()` method) restores it.
+
+## Accessibility
+
+## Roles
+
+- The **handle** is a `separator` (`role="separator"`) — a focusable, operable
+  window splitter, not a decorative one. It carries `aria-orientation`
+  (`vertical` for a horizontal group's vertical divider, `horizontal` for a
+  vertical group's horizontal divider).
+- The **panel group** is a generic `group` container; **panels** are generic
+  regions. Give a panel a meaningful label (`aria-label` / `aria-labelledby`) when
+  its content isn't self-describing.
+
+## Keyboard
+
+| Key                    | Action                                                        |
+| ---------------------- | ------------------------------------------------------------- |
+| `Tab` / `Shift+Tab`    | Move focus to / from the handle.                              |
+| `Arrow` along the axis | Resize the adjacent panels by a step (Left/Right or Up/Down). |
+| `Home` / `End`         | Resize to the handle's minimum / maximum extent.              |
+| `Enter`                | Toggle a collapsible panel between collapsed and expanded.    |
+
+The handle is reachable and fully operable by keyboard — resizing never requires a
+pointer.
+
+## Focus
+
+- The handle shows a visible focus ring on `:focus-visible` (3px
+  `--ui-focus-primary`), distinct from hover, so keyboard users can see which
+  handle is active.
+- Focus order follows the DOM: panel content, then the handle, then the next
+  panel.
+
+## Screen readers
+
+- As a `separator` with `aria-orientation`, the handle is announced as a
+  resizable splitter. `aria-valuenow` / `aria-valuemin` / `aria-valuemax` are
+  managed by the underlying panel library to convey the current split.
+- The handle has no decorative children — its visual affordance is the cursor
+  change and the border color shift on hover/active.
+
+## Contrast
+
+- The divider line uses `--ui-border-on-surface-border` (idle) and
+  `--ui-resizable-border-color-hover` / `-active`, which resolve per brand/theme;
+  they must keep a visible contrast against the adjacent panel surfaces in both
+  light and dark schemes.

package/dist/llms/sankey-chart.md

@@ -0,0 +1,208 @@
+# SankeyChart
+
+> A typed Sankey flow-diagram composition over the shared `Chart` primitives. Renders a graph of `nodes` + `links` where each link's width is proportional to its flow value, inside a `ChartContainer`, with token-themed node bars and link ribbons plus a tooltip. No axes or grid, and no variant axes; an optional count/% legend (`showLegend`) renders below the chart, and geometry (`nodePadding` / `nodeWidth` / `linkCurvature`) is plain props. Themed through custom node/link renderers (recharts' defaults paint one flat grey and have no token hooks). Built on recharts' `Sankey` primitive (no apps/demo playground existed).
+
+**Status:** draft · **Category:** data-display · **Since:** v0.60.0
+
+## Import
+
+```tsx
+import { SankeyChart } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<SankeyChart
+  config={config}
+  data={{ nodes, links }}
+  className="h-[360px] w-[620px]"
+/>
+```
+
+A typed Sankey flow diagram built on the shared `Chart` primitives. Give it a
+graph (`data.nodes` + `data.links`) and a per-node `config`; it renders a themed
+recharts `Sankey` — node bars colored per name, link ribbons whose width is
+proportional to the flow value and tinted by their target node — so you don't
+hand-compose recharts children.
+
+Node colors come from the `palette` prop — a dataviz palette resolving to the
+`--ui-dataviz-*` tokens, `categorical` by default — not from `config`. Link
+ribbons tint from their target node unless a link sets its own `color`.
+
+> **Design-pending v1.** Built on recharts' `Sankey` primitive (no apps/demo
+> playground existed). The chrome is reconciled with Figma later; Code Connect is
+> deferred.
+
+## When to use
+
+- Showing how a total **flows/breaks down** across stages where the width of each
+  flow matters (tenants → certification status, traffic → outcomes, budget → spend).
+- A part-to-whole across two or more levels in one picture.
+
+## When not to use
+
+- Precise value comparison — ribbon width is hard to judge; a bar chart reads better.
+- A single-level part-to-whole — a pie/donut or a `CategoryBar` is clearer.
+- Very dense graphs (many nodes/links) — ribbons overlap and labels collide.
+
+## Variants
+
+None. SankeyChart has no CVA variant axes — everything is plain props: geometry
+(`nodePadding` / `nodeWidth` / `linkCurvature`), `sort` (auto-order vs the given
+node order), `showLabels` / `showLegend`, and a per-link `color` override
+(rendered full-opacity; the default ribbon is the target color at 35%).
+
+## Example
+
+```tsx
+import { SankeyChart } from '@acronis-platform/ui-react';
+import type { ChartConfig } from '@acronis-platform/ui-react';
+
+const data = {
+  nodes: [{ name: 'all' }, { name: 'certified' }, { name: 'expired' }],
+  links: [
+    { source: 0, target: 1, value: 209 },
+    { source: 0, target: 2, value: 31 },
+  ],
+};
+
+const config = {
+  all: {
+    label: 'All tenants',
+    color: 'var(--ui-background-status-strong-info)',
+  },
+  certified: {
+    label: 'Certified',
+    color: 'var(--ui-background-status-strong-info)',
+  },
+  expired: {
+    label: 'Expired',
+    color: 'var(--ui-background-status-strong-danger)',
+  },
+} satisfies ChartConfig;
+
+<SankeyChart config={config} data={data} className="h-[360px] w-[620px]" />;
+```
+
+`showLegend` renders a built-in legend below the chart — a color dot + label per
+node plus each node's value and its share of the largest node (the count + %
+shown in the "Certification compliance" card). Pair it with `showLabels={false}`
+to move naming off the chart. Give a link an explicit `color` to override its
+default target tint (rendered full-opacity to match its node bar).
+
+Node `name`s are the color keys, so they must be unique and CSS-safe;
+`config[name].label` carries the human-readable text.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `data` | `{ nodes: ReadonlyArray<{ name: string }>; links: ReadonlyArray<{ source: number; target: number; value: number; color?: string }> }` | — | yes | The graph. `nodes` carry a CSS-safe `name` (the color/config key); `links` reference nodes by their index in `nodes` and carry the flow `value` that sizes the ribbon, plus an optional `color` (rendered at full opacity to match its node; omit for the target node's color at 35%). |
+| `config` | `ChartConfig` | — | yes | Nodes take their colour from the container's `palette`; each entry, keyed by the node's `name`, maps that node to a `label` and an optional `tone`. Resolved into the `--color-<name>` custom properties the node bars fill from (and the link ribbons tint from). |
+| `nodePadding` | `number` | `24` | no | Vertical gap between nodes in the same column. |
+| `nodeWidth` | `number` | `12` | no | Thickness of each node bar. |
+| `linkCurvature` | `number` | `0.5` | no | Curviness of the link ribbons (0 = straight, 1 = fully curved). |
+| `sort` | `boolean` | `false` | no | Sort nodes vertically to minimize link crossings (recharts' relaxation). Defaults to false — nodes render in the given order per column, which keeps curated flows tidy; set true to auto-order. |
+| `showLabels` | `boolean` | `true` | no | Render each node's `config` label beside its bar. |
+| `showLegend` | `boolean` | `false` | no | Render a legend below the chart — a color dot + label per node, with its computed value (incoming flow) and share of the largest node. |
+| `showTooltip` | `boolean` | `true` | no | Render the hover tooltip. |
+| `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. |
+
+## Behavior
+
+`SankeyChart` is a typed [recharts](https://recharts.org) composition over the
+shared `Chart` primitives. It renders a flow diagram from a `nodes` + `links`
+graph inside a `ChartContainer`.
+
+```gherkin
+Scenario: Render nodes and links from data and config
+  Given a graph with nodes (each a CSS-safe name) and links (source/target indices + value)
+  And a config mapping each node name to a label and color
+  Then one bar renders per node, filled from its --color-<name> custom property
+  And one ribbon renders per link, its width proportional to the link value
+```
+
+```gherkin
+Scenario: Link ribbon color
+  Given a link with no explicit color
+  Then its ribbon is stroked in the target node's color at 35% opacity
+  Given a link with an explicit color
+  Then its ribbon is stroked in that color at full opacity (matching its node bar)
+```
+
+```gherkin
+Scenario: Node labels
+  Given showLabels is true
+  Then each node shows its config label — to the right for nodes with outgoing
+    links, to the left for terminal (sink) nodes
+  And when showLabels is false no node labels render (e.g. an external legend names them)
+```
+
+```gherkin
+Scenario: Legend
+  Given showLegend is true
+  Then a legend renders below the chart with a color dot + label per node
+  And each node's value (incoming flow, or outgoing for a source) plus its share
+    of the largest node as a percentage
+```
+
+```gherkin
+Scenario: Node order
+  Given sort is false (the default)
+  Then nodes render in the order given by data.nodes within each column
+  Given sort is true
+  Then recharts reorders nodes vertically to minimize link crossings
+```
+
+```gherkin
+Scenario: Geometry
+  Given nodePadding, nodeWidth, and linkCurvature
+  Then nodes are spaced/sized accordingly and ribbons curve by that amount
+```
+
+```gherkin
+Scenario: Tooltip on hover
+  Given showTooltip is true
+  When the user hovers a node or link
+  Then a card shows a color dot matching the ribbon (its link color + opacity),
+    the source → target labels, and the value
+```
+
+```gherkin
+Scenario: Minimal graph
+  Given a two-node, single-link graph
+  Then the chart renders one ribbon and does not throw
+```
+
+## Accessibility
+
+- **recharts gives a Sankey no accessibility layer.** Unlike the cartesian charts,
+  recharts' `Sankey` (v3.8) implements no `accessibilityLayer`: it renders no
+  `role`, no `tabIndex`, and no generated description, so the plot is **not
+  keyboard-focusable** and its hover tooltip is pointer-only. Treat the chart as
+  an image and carry the numbers in accessible content next to it.
+- A Sankey is inherently visual (ribbon width is a weak quantitative encoding).
+  **Pair it with a text alternative** — a caption, a summary, or an adjacent
+  legend/table carrying the same numbers (as the reference "Certification
+  compliance" usage does) — and give the chart an accessible name (`aria-label` /
+  `aria-labelledby` referencing a visible heading). The wrapper forwards native
+  `div` attributes, so `aria-*` pass through.
+- Do **not** rely on color alone to distinguish nodes/flows. Keep `showLabels` on
+  (or supply an external legend) so each node is named, and keep `showTooltip` on
+  so values are recoverable on hover.
+- Node labels use the `--ui-text-on-surface-primary` token (fill-foreground), so
+  they read on the themed surface in both modes. Node/link colors come from
+  `config` and are the caller's responsibility — keep adjacent nodes
+  distinguishable and flows legible at the low ribbon opacity (matched data-viz
+  colors are a design-pending item for the `--ui-chart-*` palette).
+- Watch recharts issue [#4809](https://github.com/recharts/recharts/issues/4809)
+  on the a11y layer — if `Sankey` ever gains one, this component should adopt it
+  instead of relying purely on the caller's text alternative.
+
+## Contrast
+
+Tooltip chrome and node labels meet contrast in both themes via the semantic
+tokens. Node bar fills and link ribbon tints come from `config` and are the
+caller's responsibility — pick node colors that stay distinguishable from each
+other and legible as ~35%-opacity ribbons.

package/dist/llms/scatter-chart.md

@@ -0,0 +1,239 @@
+# ScatterChart
+
+> A typed scatter-chart composition over the shared `Chart` primitives. Plots each `series[]` entry's points on numeric `xKey` / `yKey` axes inside a `ChartContainer`, with tooltip and legend chrome. Optionally maps a `zKey` to point size (a bubble chart). Scatter has no variant axes — its expressiveness comes from the data mapping, not a visual mode. Ported from the apps/demo `ScatterChartPlayground`.
+
+**Status:** draft · **Category:** data-display · **Since:** v0.58.0
+
+## Import
+
+```tsx
+import { ScatterChart } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<ScatterChart
+  config={config}
+  series={series}
+  xKey="hours"
+  yKey="score"
+  zKey="weight"
+  className="h-[360px] w-[520px]"
+/>
+```
+
+A typed scatter-chart built on the shared `Chart` primitives. Give it a `series`
+list (each `{ key, data }`), a per-series `config`, and the numeric axis fields
+(`xKey` / `yKey`); it renders a themed recharts `ScatterChart` — tooltip, legend,
+axes, and grid included — so you don't hand-compose recharts children. Add a
+`zKey` to size points by a third field (a bubble chart).
+
+Series colors come from the `palette` prop — a dataviz palette resolving to the
+`--ui-dataviz-*` tokens, `categorical` by default — not from `config`.
+
+> **Design-pending v1.** Ported from the apps/demo `ScatterChartPlayground`. The
+> chrome is reconciled with Figma later; Code Connect is deferred.
+
+## When to use
+
+- Showing the relationship/correlation between two numeric variables.
+- Revealing clusters or outliers across groups (one `series` entry per group).
+- Adding a third dimension via point size (`zKey` → bubble chart).
+
+## When not to use
+
+- A trend over an ordered/continuous dimension — use a line or area chart.
+- Comparing a quantity across discrete categories — use a bar chart.
+- Part-to-whole — use a pie/donut chart.
+
+## Variants
+
+None. ScatterChart has no CVA variant axes — its shape is fixed and its
+expressiveness comes from the data mapping (`xKey` / `yKey` / `zKey` and the
+number of `series`). Marker `shape` and bubble sizing are plain props.
+
+## Example
+
+```tsx
+import { ScatterChart } from '@acronis-platform/ui-react';
+import type { ChartConfig } from '@acronis-platform/ui-react';
+
+const series = [
+  {
+    key: 'classA',
+    data: [
+      { hours: 2, score: 55 },
+      { hours: 6, score: 78 },
+      { hours: 8, score: 92 },
+    ],
+  },
+  {
+    key: 'classB',
+    data: [
+      { hours: 1, score: 70 },
+      { hours: 5, score: 82 },
+      { hours: 9, score: 95 },
+    ],
+  },
+];
+
+const config = {
+  classA: { label: 'Class A', color: 'var(--ui-background-brand-secondary)' },
+  classB: {
+    label: 'Class B',
+    color: 'var(--ui-background-status-strong-danger)',
+  },
+} satisfies ChartConfig;
+
+<ScatterChart
+  config={config}
+  series={series}
+  xKey="hours"
+  yKey="score"
+  className="h-[360px] w-[520px]"
+/>;
+```
+
+Series colors reference existing semantic `--ui-*` tokens. `--ui-background-status-strong-*`
+is chromatic in every brand; `--ui-background-brand-secondary` is brand-dependent
+(blue in `default`, neutral in some white-label brands), so it is not color-stable
+across brands until the real data-viz palette lands.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `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. |
+| `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. |
+| `yAxisLabel` | `string` | — | no | Title rendered beside the vertical (Y) axis (rotated). |
+| `xUnit` | `string` | — | no | Unit suffix appended to X-axis tick values (recharts `unit`). |
+| `yUnit` | `string` | — | no | Unit suffix appended to Y-axis tick values (recharts `unit`). |
+| `zKey` | `string` | — | no | Optional numeric field mapped to point size (a bubble chart), via recharts `ZAxis`. |
+| `zRange` | `[number, number]` | `[60, 400]` | no | Point-size range `[min, max]` the `zKey` maps into. Ignored when `zKey` is unset (points use recharts' default size). |
+| `shape` | `'circle' | 'cross' | 'diamond' | 'square' | 'star' | 'triangle' | 'wye'` | `'circle'` | no | Marker shape for every point. |
+| `showGrid` | `boolean` | `true` | no | Render the CartesianGrid. |
+| `showTooltip` | `boolean` | `true` | no | Render the hover tooltip. |
+| `showLegend` | `boolean` | `true` | no | Render the legend. |
+| `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. |
+| `showXAxis` | `boolean` | `true` | no | Render the X axis (its ticks and title). Set false to hide it. |
+| `showYAxis` | `boolean` | `true` | no | Render the Y axis (its ticks and title). Set false to hide it. |
+| `xTickFormatter` | `(value: number | string, index?: number) => string` | — | no | Format each X-axis tick value. Unlike the `unit` suffix (append-only), a formatter transforms the value — abbreviate, prefix a symbol, or map to a label. Use formatCompactNumber / formatPercent / createTickFormatter from the shared Chart primitives, or any function. |
+| `yTickFormatter` | `(value: number | string, index?: number) => string` | — | no | Format each Y-axis tick value (see xTickFormatter). |
+| `xAxisAngle` | `number` | — | no | Rotate the X-axis tick labels by this many degrees (a negative angle tilts them up toward the right); the tick anchor + axis height adjust. |
+| `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. |
+| `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. |
+| `animationDuration` | `number` | — | no | Animation duration in ms. |
+| `animationBegin` | `number` | — | no | Delay before the animation starts, in ms. |
+| `animationEasing` | `'ease' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'linear'` | — | no | Easing curve. |
+
+## Behavior
+
+`ScatterChart` is a typed [recharts](https://recharts.org) composition over the
+shared `Chart` primitives. It plots each `series[]` entry's points on numeric
+`xKey` / `yKey` axes inside a `ChartContainer`, optionally sizing points by a
+`zKey` (bubble chart).
+
+```gherkin
+Scenario: Render points from series and config
+  Given a series list, each { key, data }, and a config mapping each key to a label and color
+  Then one <Scatter> renders per series
+  And each series' points fill from its injected --color-<key> custom property
+```
+
+```gherkin
+Scenario: Single (ungrouped) scatter
+  Given series has one entry
+  Then a single set of points renders against the x/y axes
+```
+
+```gherkin
+Scenario: Grouped scatter
+  Given series has two or more entries
+  Then each renders as its own colored set of points
+  And the legend distinguishes them by color + label
+```
+
+```gherkin
+Scenario: Bubble sizing
+  Given a zKey is supplied
+  Then a ZAxis maps that field to point size across zRange
+  But when zKey is omitted every point uses a fixed size
+```
+
+```gherkin
+Scenario: Marker shape
+  Given shape is one of circle / cross / diamond / square / star / triangle / wye
+  Then every point renders with that marker glyph
+```
+
+```gherkin
+Scenario: Tooltip on hover
+  Given showTooltip is true
+  When the user hovers a point
+  Then a card shows that point's axis values
+```
+
+```gherkin
+Scenario: Legend
+  Given showLegend is true
+  Then a swatch + label renders for each series
+```
+
+```gherkin
+Scenario: Empty series
+  Given series is an empty array
+  Then the chart renders its axes and grid with no points and does not throw
+```
+
+```gherkin
+Scenario: Entrance animation is opt-in
+  Given animate is unset
+  Then the series render at their final geometry with no entrance animation
+  And the committed visual baselines are unaffected
+```
+
+```gherkin
+Scenario: Reduced motion
+  Given animate is true
+  And a user with prefers-reduced-motion
+  Then the entrance animation does not play and the series render at their final geometry
+  And the same applies when rendering on the server
+```
+
+## Accessibility
+
+- recharts' `accessibilityLayer` is **on by default** (recharts v3), giving the
+  chart keyboard focus and an accessible description of the plotted points.
+- A scatter chart is inherently visual. **Pair it with a text alternative** — a
+  caption, a summary sentence, or an adjacent data table carrying the same
+  numbers — and give the chart an accessible name (`aria-label` /
+  `aria-labelledby` referencing a visible heading) when it is meaningful on its
+  own. The wrapper forwards native `div` attributes, so `aria-*` pass through.
+- Do **not** rely on color alone to distinguish series. Keep `showLegend` (or the
+  tooltip) visible so each color is paired with a text label; the `shape` marker
+  can add a second, non-color channel when several series overlap.
+- In a bubble chart (`zKey`), size encodes a value — call it out in the caption,
+  since point area is hard to read precisely and impossible for a screen reader
+  to infer.
+- The chrome (tooltip, legend, axis ticks, grid) resolves to semantic `--ui-*`
+  tokens that meet contrast in light and dark. **Series colors are
+  caller-supplied** via `config` — pick values that meet 3:1 against the surface
+  and are distinguishable for color-vision deficiencies. The borrowed semantic
+  tokens are a design-pending stopgap until the `--ui-chart-*` palette lands.
+- Watch recharts issue [#4809](https://github.com/recharts/recharts/issues/4809)
+  on the a11y layer for heavily-customized charts.
+
+## Contrast
+
+Chart chrome meets contrast in both themes via the semantic tokens. Point fills
+come from `config` and are the caller's responsibility — keep overlapping points
+distinguishable from each other, not just against the surface.