@acronis-platform/ui-react 2.0.0 → 4.0.0

package/dist/llms/line-chart.md

@@ -0,0 +1,369 @@
+# LineChart
+
+> A typed line-chart composition over the shared `Chart` primitives. Takes `data` + `config` + a set of series `dataKeys` and renders a themed recharts `LineChart` inside a `ChartContainer`, with tooltip and legend chrome. Two variant axes: `curve` (linear / monotone / step interpolation) and `lineStyle` (solid / dashed stroke); single vs multi line is driven by the number of `dataKeys`. Ported from the apps/demo `ChartPlayground`.
+
+**Status:** draft · **Category:** data-display · **Since:** v0.58.0
+
+## Import
+
+```tsx
+import { LineChart } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<LineChart
+  config={config}
+  data={data}
+  dataKeys={['desktop', 'mobile']}
+  xKey="month"
+  curve="monotone"
+  lineStyle="solid"
+  className="h-[320px] w-[560px]"
+/>
+```
+
+A typed line-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 `LineChart` — 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 `ChartPlayground`. The chrome
+> is reconciled with Figma later; Code Connect is deferred.
+
+## When to use
+
+- Showing a trend over a continuous or ordered dimension (revenue by month,
+  latency over time).
+- Comparing the trends of a few series on shared axes.
+
+## When not to use
+
+- Comparing a quantity across discrete categories — use a bar chart.
+- Part-to-whole of a single total — consider a pie/donut chart.
+- A single metric or KPI — use a `Tag`, `Badge`, or plain text.
+- Tabular detail — use `Table` / `DataTable`.
+
+## Variants
+
+| Axis        | Values                         | Effect                                                       |
+| ----------- | ------------------------------ | ------------------------------------------------------------ |
+| `curve`     | `linear` · `monotone` · `step` | Straight, smoothed, or stepped interpolation between points. |
+| `lineStyle` | `solid` · `dashed`             | Solid or dashed stroke.                                      |
+
+Single vs multi line is not a variant — it follows from how many `dataKeys` you
+plot.
+
+## Example
+
+```tsx
+import { LineChart } 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;
+
+<LineChart
+  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 |
+|------|------|---------|----------|-------------|
+| `curve` | `'linear' | 'monotone' | 'natural' | 'basis' | 'step' | 'stepBefore' | 'stepAfter'` | `'monotone'` | no | How each line interpolates 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. |
+| `lineStyle` | `'solid' | 'dashed'` | `'solid'` | no | Stroke style of every line — solid or dashed. |
+| `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 line 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 lines stroke from. |
+| `dataKeys` | `string[]` | — | yes | Series to plot — one line per key. Each must exist in `config` and every data row. |
+| `xKey` | `string` | — | yes | The category dimension key shared across rows. |
+| `comparisonKeys` | `string[]` | — | no | Subset of `dataKeys` rendered as comparison/trend overlays (e.g. a previous quarter or year) — dashed, dimmed, and dot-less, keeping each series' own `config` color. |
+| `deltaBands` | `[string, string][]` | — | no | Pairs `[current, comparison]` to shade a delta band between — a dimmed area filling the gap between the two series at each point (the QoQ/YoY difference), tinted with the first key's `config` color. |
+| `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. |
+| `strokeWidth` | `number` | `2` | no | Stroke width of each line. |
+| `showDots` | `boolean` | `true` | 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. |
+| `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
+
+`LineChart` 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
+`LineChart` inside a `ChartContainer`.
+
+```gherkin
+Scenario: Render lines 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 <Line> renders per dataKey
+  And each line strokes from its injected --color-<key> custom property
+```
+
+```gherkin
+Scenario: Single line
+  Given dataKeys has one entry
+  Then a single line renders against the category and value axes
+```
+
+```gherkin
+Scenario: Multiple lines
+  Given dataKeys has two or more entries
+  Then one line renders per key on shared axes
+  And the legend distinguishes them by color + label
+```
+
+```gherkin
+Scenario: Curve interpolation (default monotone)
+  Given curve is one of linear, monotone, natural, basis, step, stepBefore, stepAfter
+  Then every line uses that recharts `type`
+  And "linear" draws straight segments, "monotone" smooths them without overshooting a point
+  And "natural" smooths further and may overshoot, while "basis" need not pass through the points
+  And "step" draws right angles at the midpoint, "stepBefore" at the leading point, "stepAfter" at the trailing one
+  And each type draws distinct geometry — an unrecognized value would silently fall back to straight segments
+```
+
+```gherkin
+Scenario: Dashed line style
+  Given lineStyle is "dashed"
+  Then every line strokes with a dashed pattern
+```
+
+```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
+  But when showDots is false neither the static dots nor the hover active dot render
+```
+
+```gherkin
+Scenario: Hover dot independent of the static dots
+  Given showActiveDot is set
+  Then it decides the hover dot on its own instead of following showDots
+  And showDots false with showActiveDot true gives a bare line that still emphasizes the hovered point
+  And showDots true with showActiveDot false gives static dots with no hover emphasis
+```
+
+```gherkin
+Scenario: Restyle one series
+  Given lineSettings maps "mobile" to { dashed: true, strokeWidth: 3, showDots: false }
+  Then only the "mobile" line is dashed, thicker, and dot-less
+  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: A comparison overlay keeps its treatment
+  Given a series is listed in comparisonKeys
+  And its lineSettings entry sets showDots true
+  Then the series still renders dot-less — the overlay treatment wins
+  But its color, strokeWidth and curveType overrides still apply
+```
+
+```gherkin
+Scenario: Per-series value labels
+  Given lineSettings 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 a comparisonKeys overlay counts as a plotted series in that mean
+  And null values are skipped rather than counted as zero
+  And when there is nothing numeric to average, no rule is drawn
+```
+
+```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 line breaks at the gap
+  But when connectNulls is true the line 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: Comparison / trend overlay
+  Given comparisonKeys lists a subset of dataKeys (e.g. ["lastYear"])
+  Then those series render dashed, dimmed, and without dots
+  And the remaining series render normally (current lineStyle / showDots)
+  And each series keeps its own config color
+```
+
+```gherkin
+Scenario: Delta band between two series
+  Given deltaBands lists a pair [current, comparison] (e.g. [["thisYear","lastYear"]])
+  Then a dimmed area shades the gap between the two series at each point
+  And the band is tinted with the current key's config color and sits behind the lines
+  And it follows the current key's curveType, so its edges match the line it shades
+  And points where either series is non-numeric are left un-banded
+  And the band is not surfaced as its own tooltip row or legend entry
+```
+
+```gherkin
+Scenario: Empty data
+  Given data is an empty array
+  Then the chart renders its axes and grid with no lines 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.
+- A line 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 `lineStyle`
+  (solid / dashed) and `curve` variants add a non-color channel between lines.
+- 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. Line strokes
+come from `config` and are the caller's responsibility.

package/dist/llms/link.md

@@ -0,0 +1,209 @@
+# Link
+
+> An inline text link (semibold) that underlines on hover, with an optional trailing external-link icon. Navigates to an href or composes a router link. Themed by the `--ui-link-*` token tier.
+
+**Status:** ready · **Category:** navigation · **Since:** v0.31.0
+
+## Import
+
+```tsx
+import { Link } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<Link href="/docs">Documentation</Link>
+
+{/* External */}
+<Link href="https://acronis.com" external target="_blank" rel="noreferrer">
+  Acronis
+</Link>
+
+{/* On a backdrop / dark brand surface */}
+<Link href="/docs" variant="inverse">Documentation</Link>
+
+{/* Polymorphic — render a router link */}
+<Link render={<RouterLink to="/settings" />}>Settings</Link>
+```
+
+An inline text link (semibold) that underlines on hover, with an optional trailing
+external-link icon. Navigates via `href` or composes a router link through `render`.
+Themed by the `--ui-link-*` token tier, which carries one token set per surface —
+`variant="normal"` (default) and `variant="inverse"` for links over a backdrop.
+
+## When to use
+
+- Inline navigation within prose or UI — to another page, a section, or an external
+  resource (`external`).
+- Over a scrim, dark brand banner, or other dark surface — with `variant="inverse"`.
+
+## When not to use
+
+- For a primary/secondary **action** (submit, open dialog) — use `Button` (its
+  borderless `ghost`/link-style variant reads like a link but is a real button).
+- For breadcrumb trails — use `Breadcrumb`.
+
+## Examples
+
+```tsx
+import { Link } from '@acronis-platform/ui-react';
+
+// Internal
+<Link href="/docs">Documentation</Link>;
+
+// External (trailing icon)
+<Link
+  href="https://acronis.com"
+  external
+  target="_blank"
+  rel="noopener noreferrer"
+>
+  Acronis
+</Link>;
+
+// Polymorphic — render a router link, keep the Link styling
+<Link render={<RouterLink to="/settings" />}>Settings</Link>;
+
+// On a backdrop / dark brand surface. Text-only and always enabled: both `external`
+// and `disabled` are ignored here.
+<Link href="/docs" variant="inverse">
+  Documentation
+</Link>;
+
+// Disabled (inert) — `variant="normal"` only; the prop is ignored on "inverse".
+<Link href="/docs" disabled>
+  Documentation
+</Link>;
+```
+
+## Parts
+
+| Part    | Element | Description                                                                    |
+| ------- | ------- | ------------------------------------------------------------------------------ |
+| `label` | text    | The link text (children).                                                      |
+| `icon`  | `<svg>` | Optional trailing external-link icon (`external`), on `variant="normal"` only. |
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `variant` | `'normal' | 'inverse'` | `'normal'` | no | Which surface the link sits on (Figma's `background` property). `normal` targets ordinary surfaces via the `--ui-link-normal-*` tokens; `inverse` targets a backdrop/scrim or other dark brand surface via `--ui-link-inverse-*`. `inverse` is text-only and always enabled: it supports neither the external icon (see `external`) nor the disabled state (see `disabled`), and both props are ignored there. |
+| `href` | `string` | — | no | Navigation target. Omitted when `disabled`. |
+| `external` | `boolean` | `false` | no | Append a trailing external-link icon (for links that leave the app). Ignored on `variant="inverse"`: the design carries the icon layer only on the `normal` surface, so no icon is rendered there. |
+| `disabled` | `boolean` | `false` | no | Render the link inert — disabled color, removed from the tab order (`tabindex=-1`), `aria-disabled`, and no navigation (href dropped). Ignored entirely on `variant="inverse"`: the design defines no disabled state on a backdrop, so the link renders exactly as an enabled one — still navigable, focusable and hoverable, with no `aria-disabled`. Omit the link when it must be inert on that surface. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `click` | `MouseEvent` | Native activation (click / Enter), forwarded to the anchor. |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | The link label. |
+
+## Behavior
+
+### Rendering
+
+**Given** an `href` and a label
+**When** the link renders
+**Then** it is an `<a role="link">` with the label in `--ui-link-normal-text-color-idle` (semibold,
+no underline).
+
+**Given** `external`
+**Then** a trailing external-link icon is appended (`--ui-link-normal-external-icon-color-*`).
+
+### Surface (`variant`)
+
+**Given** no `variant`
+**Then** the link uses the `normal` surface — the `--ui-link-normal-*` token set.
+
+**Given** `variant="inverse"`
+**When** the link renders on a backdrop/scrim or dark brand surface
+**Then** every state resolves its text color against
+`--ui-link-inverse-text-color-{idle,hover,active}` instead. Text decoration and the
+focus ring are shared with the `normal` surface (`--ui-link-global-text-decoration-*`,
+`--ui-focus-primary`).
+
+**Given** `variant="inverse"` **and** `external`
+**When** the link renders
+**Then** no external icon is appended — the design defines the icon layer only on the
+`normal` surface, so `external` is a no-op here (as it is on an inverse Figma
+instance). The link is text-only.
+
+### Interaction
+
+**Given** the link
+**When** the pointer hovers
+**Then** the text shifts to `--ui-link-normal-text-color-hover` and the
+`--ui-link-global-text-decoration-hover` underline appears (the icon shifts to its hover
+color).
+
+**Given** the link
+**When** it is pressed (`:active`)
+**Then** the text/icon shift to their `-active` color.
+
+**Given** the link
+**When** it receives keyboard focus
+**Then** a 3px `--ui-focus-primary` ring is shown.
+
+**Given** the link
+**When** activated (click / Enter)
+**Then** the native `click` fires and the browser navigates to `href`.
+
+### Disabled
+
+**Given** `disabled`
+**When** the link renders
+**Then** it uses `--ui-link-normal-text-color-disabled`, drops its `href`, sets
+`aria-disabled="true"` and `tabindex="-1"`, and does not navigate or underline.
+
+**Given** `disabled` **and** `variant="inverse"`
+**When** the link renders
+**Then** `disabled` has no effect whatsoever: the link keeps its `href`, sets no
+`aria-disabled`, stays in the tab order, and hovers, underlines and navigates exactly
+like an enabled one. The Figma set has only four enabled inverse variants and marks the
+fifth unsupported ("disable state not supported onBackdrop"), so the prop is discarded
+rather than applied without its color. A link that must be inert on a backdrop should be
+omitted from the UI instead.
+
+### Composition
+
+**Given** a `render` prop (e.g. a router link component)
+**When** the link renders
+**Then** it renders as that element with the Link's classes/props merged on (Base UI
+`useRender`), so client-side routing works while keeping the Link styling.
+
+## Accessibility
+
+- **Role:** a native `<a>` with an `href` exposes `role="link"` and is keyboard
+  focusable / activatable by default.
+- **Accessible name:** comes from the link text (the children). For icon-only or
+  ambiguous links, provide `aria-label`. The external icon is decorative and inherits
+  the text color.
+- **External links:** when `external`, also set `target="_blank"` +
+  `rel="noopener noreferrer"` as appropriate; consider announcing "opens in a new tab"
+  in the label or an `aria-label` for screen-reader users.
+- **Keyboard:** Tab focuses the link; Enter activates it (native anchor behavior).
+- **Focus visible:** keyboard focus paints a 3px `--ui-focus-primary` ring; `:focus`
+  is not suppressed without a visible alternative.
+- **Disabled:** `disabled` removes the link from the tab order (`tabindex="-1"`), sets
+  `aria-disabled="true"`, and drops the `href` so it is not navigable — state is not
+  conveyed by color alone (the control is inert). This applies to `variant="normal"`
+  only. On `variant="inverse"` the design defines no disabled state, so the prop is
+  ignored outright and the link stays fully interactive and exposed as an enabled link
+  to assistive tech. **Do not rely on `disabled` to make a link on a backdrop inert** —
+  omit the link, or render it on the `normal` surface, instead.
+- **Decoration:** underline is reserved for hover/affordance; the semibold weight +
+  link color distinguish the link at rest. Within body copy, prefer a persistent
+  underline for the clearest affordance.
+- **Contrast:** link / hover / active / disabled colors come from the design tokens,
+  authored to meet WCAG contrast against the surface. Each surface has its own set —
+  use `variant="inverse"` over a backdrop/scrim rather than leaving the `normal`
+  tokens to fail contrast there.
+- **WCAG:** 1.4.3 / 1.4.11 (contrast), 2.1.1 (keyboard), 2.4.4 (link purpose), 2.4.7
+  (focus visible), 4.1.2.