@acronis-platform/ui-react 2.0.0 → 4.0.0

package/dist/llms/area-chart.md

@@ -0,0 +1,355 @@
+# AreaChart
+
+> A typed area-chart composition over the shared `Chart` primitives. Takes `data` + `config` + a set of series `dataKeys` and renders a themed recharts `AreaChart` inside a `ChartContainer`, with tooltip and legend chrome. Two variant axes: `layout` (single / stacked areas) and `fill` (solid flat fill / vertical gradient); single vs multi area is driven by the number of `dataKeys`. Ported from the apps/demo `AreaChartPlayground`.
+
+**Status:** draft · **Category:** data-display · **Since:** v0.58.0
+
+## Import
+
+```tsx
+import { AreaChart } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<AreaChart
+  config={config}
+  data={data}
+  dataKeys={['desktop', 'mobile']}
+  xKey="month"
+  layout="single"
+  fill="gradient"
+  className="h-[320px] w-[560px]"
+/>
+```
+
+A typed area-chart built on the shared `Chart` primitives. Give it `data`, a
+per-series `config`, the series to plot (`dataKeys`), and the category key
+(`xKey`); it renders a themed recharts `AreaChart` — tooltip, legend, axes, and
+grid included — so you don't hand-compose recharts children.
+
+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 `AreaChartPlayground`. The
+> chrome is reconciled with Figma later; Code Connect is deferred.
+
+## When to use
+
+- Emphasizing the magnitude of a trend over a continuous or ordered dimension
+  (traffic over time, cumulative usage).
+- Showing part-to-whole composition over time — with `layout="stacked"`.
+
+## When not to use
+
+- Comparing exact values across a few series — a line chart reads more precisely
+  (overlapping fills obscure each other).
+- Comparing a quantity across discrete categories — use a bar chart.
+- A single metric or KPI — use a `Tag`, `Badge`, or plain text.
+- Tabular detail — use `Table` / `DataTable`.
+
+## Variants
+
+| Axis     | Values               | Effect                                                      |
+| -------- | -------------------- | ----------------------------------------------------------- |
+| `layout` | `single` · `stacked` | Overlapping independent areas vs summed on a shared stack.  |
+| `fill`   | `solid` · `gradient` | Flat translucent fill vs a vertical top-to-bottom gradient. |
+
+Single vs multi area is not a variant — it follows from how many `dataKeys` you
+plot.
+
+## Example
+
+```tsx
+import { AreaChart } from '@acronis-platform/ui-react';
+import type { ChartConfig } from '@acronis-platform/ui-react';
+
+const data = [
+  { month: 'Jan', desktop: 186, mobile: 80 },
+  { month: 'Feb', desktop: 305, mobile: 200 },
+  { month: 'Mar', desktop: 237, mobile: 120 },
+];
+
+const config = {
+  desktop: { label: 'Desktop', color: 'var(--ui-background-brand-secondary)' },
+  mobile: {
+    label: 'Mobile',
+    color: 'var(--ui-background-status-strong-danger)',
+  },
+} satisfies ChartConfig;
+
+<AreaChart
+  config={config}
+  data={data}
+  dataKeys={['desktop', 'mobile']}
+  xKey="month"
+  className="h-[320px] w-[560px]"
+/>;
+```
+
+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 |
+|------|------|---------|----------|-------------|
+| `layout` | `'single' | 'stacked'` | `'single'` | no | How multiple series are arranged. `single` = areas overlap independently; `stacked` = areas share a `stackId` and sum into one band. |
+| `fill` | `'solid' | 'gradient'` | `'gradient'` | no | How each area is filled. `solid` = a flat translucent fill (`fillOpacity`); `gradient` = a vertical top-opaque → bottom-transparent gradient. |
+| `data` | `ReadonlyArray<Record<string, string | number | null>>` | — | yes | Row-per-point data — each row holds `xKey` plus one numeric field per series. A `null` breaks the area at that point unless `connectNulls`. |
+| `config` | `ChartConfig` | — | yes | Series take their colour from the container's `palette`; each entry maps a data key to a `label` and an optional `tone`. Resolved into the `--color-<key>` custom properties the areas stroke and fill from. |
+| `dataKeys` | `string[]` | — | yes | Series to plot — one area per key. Each must exist in `config` and every data row. |
+| `xKey` | `string` | — | yes | The category dimension key shared across rows. |
+| `xAxisLabel` | `string` | — | no | Title rendered beneath the horizontal (X) axis. |
+| `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. |
+| `curve` | `'linear' | 'monotone' | 'natural' | 'basis' | 'step' | 'stepBefore' | 'stepAfter'` | `'monotone'` | no | Interpolation between points. `linear` = straight segments; `monotone` = a smoothed curve that never overshoots a point; `natural` = a natural cubic spline (smoother, may overshoot); `basis` = the smoothest option, and not required to pass through the points at all; `step` = right-angle segments changing at the midpoint, with `stepBefore` / `stepAfter` changing at the leading or trailing point instead. |
+| `strokeWidth` | `number` | `2` | no | Stroke width of each area's top border. |
+| `fillOpacity` | `number` | `0.4` | no | Flat-fill opacity — applies only when `fill="solid"`. |
+| `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 area (dots off, active dot on) or a static-only area (dots on, active dot off). |
+| `areaSettings` | `Record<string, { color?: string; strokeWidth?: number; dashed?: boolean; curveType?: CurveType; fillOpacity?: number; 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 (e.g. a faint dashed projection beside solid actuals). `color` also recolors that series' gradient stops; under `fill="gradient"` a `fillOpacity` scales the gradient's own alpha rather than replacing it. |
+| `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`). An optional `label` captions each, at the rule's top right unless `labelPosition` moves it away from a series it would sit on. On a stacked chart the value is read against the stack's axis, which measures stack totals — `average` still means the mean of the individual series' values, so pass an explicit `value` when the rule should compare against the stacked total. The same config shape as `BarChart` / `LineChart`. |
+| `connectNulls` | `boolean` | `false` | no | Bridge `null` gaps in the data instead of breaking the area. |
+| `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. |
+| `showLabels` | `boolean` | `false` | no | Render a value label on each data point/segment. |
+| `labelPosition` | `'top' | 'bottom' | 'left' | 'right' | 'center' | 'insideTop' | 'insideBottom' | 'insideLeft' | 'insideRight' | 'insideStart' | 'insideEnd'` | — | no | Where the value labels sit. |
+| `labelFormatter` | `(value) => string` | — | no | Format each label value (reuses the tick formatters). |
+| `showBrush` | `boolean` | `false` | no | Render a range brush beneath the chart — drag a handle (or the selected window) to zoom the series into a slice of the data. |
+| `brushHeight` | `number` | `28` | no | Height of the brush strip in px. A non-positive value falls back to the default rather than erasing the brush. |
+| `brushAriaLabel` | `string` | `'Chart range selector'` | no | Accessible name for the brush's two range handles, which are focusable `role="slider"` elements. Consumers localize by passing their own. |
+
+## Behavior
+
+`AreaChart` is a typed [recharts](https://recharts.org) composition over the
+shared `Chart` primitives. It takes `data`, a per-series `config`, the series to
+plot (`dataKeys`), and the category key (`xKey`), and renders a themed recharts
+`AreaChart` inside a `ChartContainer`.
+
+```gherkin
+Scenario: Render areas from data and config
+  Given data rows and a config mapping each series key to a label and color
+  And dataKeys ["desktop", "mobile"]
+  Then one <Area> renders per dataKey
+  And each area strokes and fills from its injected --color-<key> custom property
+```
+
+```gherkin
+Scenario: Single layout (default)
+  Given layout is "single" and two or more dataKeys
+  Then each area is plotted independently and they may overlap
+```
+
+```gherkin
+Scenario: Stacked layout
+  Given layout is "stacked" and two or more dataKeys
+  Then the areas share a stackId and sum into one band
+  And the value axis grows to the stacked total
+```
+
+```gherkin
+Scenario: Gradient fill (default)
+  Given fill is "gradient"
+  Then a vertical linear gradient (top-opaque to bottom-transparent) is defined per series
+  And each area fills from its gradient
+```
+
+```gherkin
+Scenario: Solid fill
+  Given fill is "solid"
+  Then no gradient defs are emitted
+  And each area fills flat at fillOpacity
+```
+
+```gherkin
+Scenario: Curve interpolation (default monotone)
+  Given curve is one of linear, monotone, natural, basis, step, stepBefore, stepAfter
+  Then every area's top edge uses that recharts `type`
+  And "natural" smooths further than "monotone" and may overshoot, while "basis" need not pass through the points
+  And "stepBefore" / "stepAfter" move the step to the leading or trailing point
+  And each type draws distinct geometry — an unrecognized value would silently fall back to straight segments
+```
+
+```gherkin
+Scenario: Dots
+  Given showDots is true
+  Then a dot renders at each data point with radius dotSize
+  And hovering a point enlarges its active dot by 2px
+  And showActiveDot decides the hover dot on its own when set, instead of following showDots
+```
+
+```gherkin
+Scenario: Restyle one series
+  Given areaSettings maps "mobile" to { dashed: true, fillOpacity: 0.1, showDots: false }
+  Then only the "mobile" area has a dashed top edge, a fainter fill, and no dots
+  And every other series renders from the chart-wide props
+  And an unset field in the entry falls back to the chart-wide prop
+```
+
+```gherkin
+Scenario: Recolor one series
+  Given areaSettings maps a series to a color
+  And fill is "gradient"
+  Then that series' gradient stops take the override color, not its config color
+  And the other series keep their config colors
+```
+
+```gherkin
+Scenario: Per-series value labels
+  Given areaSettings maps a series to { showLabel: false }
+  And showLabels is true
+  Then that series renders no value labels while the others do
+  And a { showLabel: true } entry labels only that series with showLabels unset
+```
+
+```gherkin
+Scenario: Reference line
+  Given referenceLine is { value: 250, label: "Target" }
+  Then a dashed rule draws across the value axis at 250, captioned "Target"
+  And it is drawn in the muted text token, over the series
+  And the axis domain extends to include it, so a target above the data maximum stays visible
+  And the caption sits at the rule's top right unless labelPosition moves it
+```
+
+```gherkin
+Scenario: Averaged reference line
+  Given referenceLine is { average: true } (or a single series key)
+  Then the rule draws at the mean of every plotted series' values (or that one series)
+  And null values are skipped rather than counted as zero
+  And when there is nothing numeric to average, no rule is drawn
+  But under layout="stacked" the axis measures stack totals while the mean is still per-series,
+    so an explicit value is the honest way to compare against the stacked total
+```
+
+```gherkin
+Scenario: Multiple reference lines
+  Given referenceLine is an array of configs (e.g. a fixed target and an average)
+  Then one dashed rule draws per config
+  And each is resolved independently (a config with nothing to draw is skipped)
+```
+
+```gherkin
+Scenario: Null gaps
+  Given a data row has a null value for a series
+  And connectNulls is false
+  Then that area breaks at the gap
+  But when connectNulls is true the area bridges the gap
+```
+
+```gherkin
+Scenario: Tooltip on hover
+  Given showTooltip is true
+  When the user hovers a point
+  Then a card shows the category label and one row per series (indicator + value)
+```
+
+```gherkin
+Scenario: Legend
+  Given showLegend is true
+  Then a swatch + label renders for each series in dataKeys
+```
+
+```gherkin
+Scenario: Empty data
+  Given data is an empty array
+  Then the chart renders its axes and grid with no areas 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
+```
+
+```gherkin
+Scenario: Range brush
+  Given showBrush is true
+  Then a brush strip renders beneath the plot with a handle at each end
+  And dragging a handle (or the selected window) zooms the series to that slice
+  And the category axis and tooltip follow the selected range
+  And the brush renders whether or not the category axis is shown
+  And unset renders no brush
+```
+
+```gherkin
+Scenario: Range brush keyboard and accessible name
+  Given showBrush is true
+  Then each of the two handles is reachable by Tab
+  And the focused handle moves one row per left/right arrow key press
+  And each handle exposes brushAriaLabel as its accessible name
+```
+
+## Accessibility
+
+- recharts' `accessibilityLayer` is **on by default** (recharts v3), giving the
+  chart keyboard focus and an accessible description of the plotted points.
+- The **range brush** (`showBrush`) is the only interactive control these charts
+  render. It adds two focusable `role="slider"` handles: Tab reaches each one and
+  the left/right arrow keys move the selection a row at a time, so the whole
+  feature is operable without a pointer.
+  - Both handles take their accessible name from `brushAriaLabel` (default
+    `'Chart range selector'`); pass your own to localize it. Never leave it to
+    recharts' fallback, which names the handles from a `name` field on the data
+    row and otherwise announces "Min value: undefined, Max value: undefined".
+  - The handles keep a visible focus indicator: the shared `ChartContainer`
+    suppresses outlines on recharts layers, so it re-enables one for
+    `.recharts-brush-traveller` specifically (an `outline`, since `box-shadow`
+    does not paint on SVG children).
+  - The two range captions only appear while a handle is hovered, dragged, or
+    focused — they are a supplement to the category axis, not a replacement for
+    it. Zooming changes which rows are plotted, so **pair the brush with a text
+    alternative that reflects the current range** rather than the full series.
+- An area 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. Overlapping
+  translucent fills can be hard to read — prefer `layout="stacked"` or a solid
+  `fill` when legibility matters, and keep enough opacity contrast between series.
+- 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. Area fills
+and strokes come from `config` and are the caller's responsibility — note that
+translucent fills (solid `fillOpacity`, gradient stops) lower the effective
+contrast against the surface.

package/dist/llms/avatar.md

@@ -0,0 +1,208 @@
+# Avatar
+
+> A user or entity avatar — a circular badge showing a profile image, initials, or an icon. Eight color schemes; stack several with AvatarGroup for an overlapping row.
+
+**Status:** ready · **Category:** data-display · **Since:** v0.22.0
+
+## Import
+
+```tsx
+import { Avatar, AvatarImage, AvatarFallback, AvatarGroup } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<Avatar color="teal">
+  <AvatarImage src="/me.png" alt="Sam N." />
+  <AvatarFallback>SN</AvatarFallback>
+</Avatar>
+
+<Avatar color="blue" label="SB" />
+<Avatar color="blue" variant="icon" icon={<UserIcon size={16} />} />
+
+<AvatarGroup>
+  <Avatar color="teal"><AvatarFallback>SN</AvatarFallback></Avatar>
+  <Avatar color="violet"><AvatarFallback>GA</AvatarFallback></Avatar>
+</AvatarGroup>
+```
+
+A circular badge for a user or entity — a profile image, initials, or an icon
+on a tinted background when no image is available. Eight color schemes. Stack
+several with `AvatarGroup` for an overlapping row (e.g. assignees on a ticket).
+
+## When to use
+
+- Represent a person/entity next to their name, in a row, table, or comment.
+- Show a set of participants compactly via an overlapping `AvatarGroup`.
+- Use `variant="icon"` for a non-personal entity (a team, a bot, a system
+  actor) where an icon reads better than initials.
+
+## When not to use
+
+- As a button/link target without a proper interactive wrapper (Avatar is
+  presentational — wrap it in a control that owns focus and an accessible name).
+- For non-identity imagery (logos, thumbnails, decorative icons) — use an
+  image or `Icon` directly.
+
+## Parts
+
+| Part     | Component        | Notes                                               |
+| -------- | ---------------- | --------------------------------------------------- |
+| root     | `Avatar`         | The circle; `color` tints the fallback.             |
+| image    | `AvatarImage`    | Optional; shown once it loads, else the fallback.   |
+| fallback | `AvatarFallback` | Initials shown when there's no image (or it fails). |
+| icon     | —                | Consumer-supplied icon, shown for `variant="icon"`. |
+| group    | `AvatarGroup`    | Optional overlapping row of avatars.                |
+
+## Examples
+
+```tsx
+// Image with initials fallback
+<Avatar color="teal">
+  <AvatarImage src="/me.png" alt="Sam Nguyen" />
+  <AvatarFallback>SN</AvatarFallback>
+</Avatar>
+
+// Initials only, via children
+<Avatar color="violet">
+  <AvatarFallback>GA</AvatarFallback>
+</Avatar>
+
+// Initials only, via the `label` convenience prop (equivalent to the above)
+<Avatar color="violet" label="GA" />
+
+// Icon avatar (no children composed)
+<Avatar color="gray" variant="icon" icon={<UserIcon size={16} />} />
+
+// Overlapping group with a label
+<div className="flex items-center gap-[var(--ui-avatar-global-container-gap)]">
+  <AvatarGroup>
+    <Avatar color="teal"><AvatarFallback>SN</AvatarFallback></Avatar>
+    <Avatar color="violet"><AvatarFallback>GA</AvatarFallback></Avatar>
+    <Avatar color="red"><AvatarFallback>SI</AvatarFallback></Avatar>
+  </AvatarGroup>
+  <span>On this ticket</span>
+</div>
+```
+
+## Color schemes
+
+`teal` (default), `violet`, `red`, `yellow`, `orange`, `blue`, `gray`, `green`.
+Each pairs a tinted background with a matching initials color from the
+`--ui-avatar-*` token tier.
+
+## Variants
+
+`text` (default) shows `label` (initials); `icon` shows a consumer-supplied
+`icon`. Both are ignored once `children` (`AvatarImage`/`AvatarFallback`) are
+composed directly — `variant`/`label`/`icon` only drive the no-children case.
+
+"No children" means the slot is left unset. Passing an explicit `null` child is
+a deliberate "render nothing" and yields an empty circle rather than the default
+`'SB'` label — that's how `Timeline` renders a blank marker.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `color` | `'teal' | 'violet' | 'red' | 'yellow' | 'orange' | 'blue' | 'gray' | 'green'` | `teal` | no | Color scheme for the fallback. Maps to `--ui-avatar-color-<scheme>` (background) and `--ui-avatar-label-color-<scheme>` (initials). Ignored once an image is shown. |
+| `variant` | `'text' | 'icon'` | `text` | no | Selects the auto-rendered fallback content when no `children` are composed: initials (`label`) or an `icon`. Ignored once `children` (e.g. `AvatarImage`/`AvatarFallback`) are composed directly — including an explicit `null`, which renders an empty circle. |
+| `label` | `string` | `SB` | no | Initials shown for the `text` variant when no `children` are composed. |
+| `icon` | `ReactNode` | — | no | Icon shown for the `icon` variant when no `children` are composed — typically a 16px icon from `@acronis-platform/icons-react`. |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | The avatar's children — an `AvatarImage` and/or an `AvatarFallback` (the initials). When the slot is left unset, `variant`/`label`/`icon` drive the content instead; an explicitly empty (`null`) slot renders an empty circle and does not fall back to them. |
+
+## Behavior
+
+### Image with a fallback
+
+- **Given** an `Avatar` with an `AvatarImage` (valid `src`) and an `AvatarFallback`
+  **When** the image is still loading
+  **Then** the fallback (initials) is shown until the image finishes loading,
+  then the image replaces it.
+
+- **Given** an `Avatar` whose image `src` fails to load
+  **When** the load errors
+  **Then** the fallback remains visible (the broken image is not shown).
+
+### Fallback only
+
+- **Given** an `Avatar` with only an `AvatarFallback` (no image)
+  **Then** the initials render on the `color` scheme's tinted background, using
+  that scheme's label color.
+
+### `variant` / `label` / `icon` (no children composed)
+
+- **Given** an `Avatar` with no `children`
+  **Then** `variant` (default `'text'`) selects the auto-rendered content:
+  `label` (default `'SB'`) for `'text'`, or `icon` for `'icon'`.
+
+- **Given** an `Avatar` with `children` composed (e.g. `AvatarImage`/
+  `AvatarFallback`)
+  **Then** `variant`/`label`/`icon` have no effect — `children` always takes
+  precedence.
+
+- **Given** an `Avatar` whose children slot is explicitly empty (`null`) — e.g.
+  `Timeline`'s marker with neither an `icon` nor `initials`
+  **Then** the circle renders empty. An explicit `null` is a deliberate "render
+  nothing", so it does **not** fall back to the default `label` (`'SB'`); only
+  an unset (`undefined`) slot does.
+
+### Color scheme
+
+- **Given** `color="violet"`
+  **Then** the background resolves to `--ui-avatar-color-violet` and the initials
+  to `--ui-avatar-label-color-violet`. The default scheme is `teal`.
+
+- **Given** an avatar showing an image
+  **Then** `color` has no visible effect (the image covers the circle).
+
+### Group overlap
+
+- **Given** an `AvatarGroup` wrapping several `Avatar`s
+  **Then** each avatar after the first is offset left by
+  `--ui-avatar-global-avatar-group-gap` (a negative value), so the avatars
+  overlap; each 2px ring (`--ui-avatar-global-avatar-border-color`, drawn outside
+  the 32px circle as a `box-shadow`) separates them, and later avatars paint above
+  earlier ones.
+
+## Accessibility
+
+## Role & semantics
+
+- The avatar root renders a `<span>` and is **presentational** — it conveys no
+  interactive semantics on its own.
+- When an `AvatarImage` is shown, provide a meaningful `alt` describing the
+  person/entity (e.g. `alt="Sam Nguyen"`). If the avatar is purely decorative
+  beside an already-labeled name, use `alt=""`.
+- The `AvatarFallback` initials are text and are read as-is. Initials alone are a
+  weak label — prefer an adjacent visible name, or set `alt` on the image, so the
+  entity is identifiable by more than two letters.
+- For `variant="icon"`, the icon alone conveys no name — always pair it with a
+  visible label in the surrounding context (the icon is presentational, not an
+  accessible name by itself).
+
+## Keyboard & focus
+
+- Avatar is not focusable or interactive by default. If you make an avatar
+  actionable (e.g. wrap it in a button or link, or pass `render`), the wrapping
+  control owns the role, focus ring, and keyboard behavior — give it an
+  accessible name.
+
+## Groups
+
+- An `AvatarGroup` is a layout container; it adds no semantics. If it represents
+  a meaningful set (e.g. "people on this ticket"), label the surrounding context
+  in text. A common pattern is a trailing `+N` count and a visible label next to
+  the group.
+
+## Contrast
+
+- Initials use the per-scheme `--ui-avatar-label-color-<scheme>` on the matching
+  `--ui-avatar-color-<scheme>` background; these pairs are defined in the design
+  tokens to meet contrast for short text. Do not override one without the other.