@acronis-platform/ui-react 4.0.0 → 5.0.0

package/dist/llms/funnel-chart.md

@@ -1,6 +1,6 @@
 # FunnelChart
 
-> A typed funnel-chart composition over the shared `Chart` primitives. Plots a single series of stages (rows) as stacked, narrowing segments inside a `ChartContainer`, with a tooltip and on-chart stage labels (no legend — the inline labels name every stage). One variant axis: `lastShape` (the funnel narrows to a `triangle` point or ends `rectangle` flat). Ported from the apps/demo `FunnelChartPlayground`.
+> A typed funnel-chart composition over the shared `Chart` primitives. The root is a row: a 120×120 square plot, a 16px gutter, then a stage-list legend taking every remaining pixel — the same composition `PieChart` and `RadialBarChart` use. The plot stacks one series of stages (`data` rows) as narrowing, 2px-gapped, 2px-rounded segments inside a `ChartContainer`, with a tooltip and optional on-plot labels. One variant axis: `lastShape` (the funnel narrows to a `triangle` point or ends `rectangle` flat). Stages are painted from the sequential blue ramp by default, because a funnel's stages are an ordered series rather than unrelated categories. Card-less by design: Figma's card, header and metric row are `ChartWidget`'s.
 
 **Status:** draft · **Category:** data-display · **Since:** v0.58.0
 
@@ -19,23 +19,78 @@ import { FunnelChart } from '@acronis-platform/ui-react'
   dataKey="value"
   nameKey="stage"
   lastShape="triangle"
-  className="h-[380px] w-[460px]"
 />
 ```
 
 A typed funnel-chart built on the shared `Chart` primitives. Give it `data`, a
 per-stage `config`, the value field (`dataKey`), and the label field (`nameKey`);
-it renders a themed recharts `FunnelChart` — on-chart stage labels and a tooltip
-included — so you don't hand-compose recharts children. (There's no legend: the
-inline labels already name every stage.)
-
-Stage colors come from the `palette` prop — a dataviz palette resolving to the
-`--ui-dataviz-*` tokens — not from `config`. Stages are an ordered progression,
-so `{ type: 'sequential', ramp }` usually reads better than the default
-`categorical`.
-
-> **Design-pending v1.** Ported from the apps/demo `FunnelChartPlayground`. The
-> chrome is reconciled with Figma later; Code Connect is deferred.
+it renders a themed recharts funnel with a tooltip, plus the two-column stage
+list beside it — so you don't hand-compose recharts children.
+
+## Layout
+
+The root is a **row**: a 120×120 square plot, a 16px gutter, then the legend
+column taking every remaining pixel. That is the same composition `PieChart` and
+`RadialBarChart` use, and the legend is a **sibling of the plot** rendered
+outside the SVG — never a recharts legend, and never a row below the funnel.
+
+The component declares **no width and no height of its own**. It fills the width
+its parent gives it and the legend column absorbs the surplus; the 120px figure
+is the plot square Figma specifies, not a widget width. With `showLegend={false}`
+the row centres its lone plot.
+
+> The card, header and metric row Figma draws around the funnel belong to
+> [`ChartWidget`](../chart-widget/README.md). `FunnelChart` is card-less by
+> design.
+
+## Colour
+
+Stage colours come from the `palette` prop — a dataviz palette resolving to the
+`--ui-dataviz-*` tokens — not from `config`, which supplies each stage's label.
+The default is `{ type: 'sequential', ramp: 'blue' }`, exported as
+`FUNNEL_CHART_DEFAULT_PALETTE`. Every other chart takes the shared **categorical**
+default; a funnel differs on purpose, because its stages are an ordered series
+rather than unrelated categories, which is exactly what a ramp reads as.
+
+`stageSettings[name].color` is the per-stage escape hatch, and applies to the
+segment and its legend marker alike.
+
+### Known deviation from Figma
+
+Figma paints the four stages with sequential blue stops **2 / 4 / 6 / 8**, while
+the shared palette resolver walks the ramp in order and assigns the **consecutive**
+stops 1 / 2 / 3 / 4. The funnel is therefore paler than the mockup. This is not a
+funnel-local fix: how N series spread across a ramp's stops is the shared
+resolver's decision, applied identically to every ramp-painted chart, so it is
+left as a known deviation pending a decision there.
+
+## Geometry
+
+- **2px of surface between stages.** n stages produce exactly n-1 gaps; the
+  topmost stage stays flush with the top of the plot area.
+- **2px rounded corners** on every stage, the triangle's apex included.
+- **Plot-area inset** when nothing sits beside the funnel: 4 top, 8 right, 4
+  bottom, 8 left. Whichever side a label list sits on widens.
+- `lastShape="triangle"` (the default) narrows the final stage to a point;
+  `"rectangle"` keeps a flat lower edge.
+- `reversed` flips the stack so the funnel widens downward — the gap-free stage
+  becomes the last row.
+
+The gap and the radius are drawn by the component's own shape renderer, because
+recharts' `Funnel`/`Trapezoid` support neither.
+
+## Legend
+
+One two-column row per visible stage: the round marker and the `config` label on
+the inline start, the stage's `dataKey` value — formatted by
+`legendValueFormatter` when given — on the inline end. Both columns use
+`--ui-text-on-surface-primary`, the value in semibold; Figma deliberately differs
+from the donut and radial list legends here, which colour their values with the
+link token.
+
+Markers carry each stage's **resolved palette token** rather than a
+`--color-<name>` custom property: those are scoped to the chart container, and the
+legend sits outside it.
 
 ## When to use
 
@@ -52,9 +107,9 @@ so `{ type: 'sequential', ramp }` usually reads better than the default
 
 ## Variants
 
-| Axis        | Values                   | Effect                                         |
-| ----------- | ------------------------ | ---------------------------------------------- |
-| `lastShape` | `triangle` · `rectangle` | Final segment narrows to a point vs ends flat. |
+| Axis        | Values                   | Effect                                       |
+| ----------- | ------------------------ | -------------------------------------------- |
+| `lastShape` | `triangle` · `rectangle` | Final stage narrows to a point vs ends flat. |
 
 ## Example
 
@@ -70,47 +125,33 @@ const data = [
 ];
 
 const config = {
-  Visits: { label: 'Visits', color: 'var(--ui-background-brand-secondary)' },
-  Signups: {
-    label: 'Signups',
-    color: 'var(--ui-background-status-strong-success)',
-  },
-  Trials: {
-    label: 'Trials',
-    color: 'var(--ui-background-status-strong-warning)',
-  },
-  Purchases: {
-    label: 'Purchases',
-    color: 'var(--ui-background-status-strong-danger)',
-  },
+  Visits: { label: 'Visits' },
+  Signups: { label: 'Signups' },
+  Trials: { label: 'Trials' },
+  Purchases: { label: 'Purchases' },
 } satisfies ChartConfig;
 
-<FunnelChart
-  config={config}
-  data={data}
-  dataKey="value"
-  nameKey="stage"
-  className="h-[380px] w-[460px]"
-/>;
+<FunnelChart config={config} data={data} dataKey="value" nameKey="stage" />;
 ```
 
-Stage colors reference existing semantic `--ui-*` tokens, keyed by each stage's
-`nameKey` value. `--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.
+The `config` keys are each stage's `nameKey` value. No colour is declared there —
+the stages take the sequential blue ramp; pass `palette` to change it.
+
+On-plot labels are **off** by default (`showLabels`), because the legend already
+names every stage. Turn them on when a funnel is shown without its legend.
 
 ## Props
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
-| `lastShape` | `'triangle' | 'rectangle'` | `'triangle'` | no | How the funnel ends. `triangle` narrows the final segment to a point; `rectangle` ends it flat (a stack of trapezoids). |
+| `lastShape` | `'triangle' | 'rectangle'` | `'triangle'` | no | How the funnel ends. `triangle` narrows the final stage to a point; `rectangle` keeps a flat lower edge (a stack of trapezoids). |
 | `data` | `ReadonlyArray<Record<string, string | number>>` | — | yes | Row-per-stage data — each row holds a `nameKey` label and a `dataKey` numeric value. |
-| `config` | `ChartConfig` | — | yes | Stages take their colour from the container's `palette`; each entry, keyed by the stage's `nameKey` value, maps that stage to a `label` and an optional `tone`. Resolved into the `--color-<name>` custom properties the segments fill from. |
-| `dataKey` | `string` | — | yes | The numeric field that sizes each stage. |
-| `nameKey` | `string` | — | yes | The label field that names each stage (drives the tooltip, on-chart labels, and the `--color-<name>` lookup). Values should be unique per chart — stages sharing a name share one config/color entry. |
-| `reversed` | `boolean` | `false` | no | Flip the funnel so it widens toward the bottom instead of narrowing. |
-| `showLabels` | `boolean` | `true` | no | Render a label for each stage — see labelFormat and labelPosition. |
+| `config` | `ChartConfig` | — | yes | Stages take their colour from `palette`; each entry, keyed by the stage's `nameKey` value, maps that stage to a `label` and an optional `tone`. The labels are what the legend and the tooltip read. Resolved into the `--color-<name>` custom properties the segments fill from. |
+| `dataKey` | `string` | — | yes | The numeric field that sizes each stage — and the value each legend row shows on its inline end. |
+| `nameKey` | `string` | — | yes | The label field that names each stage (drives the legend, the tooltip, the on-plot labels, and the `--color-<name>` lookup). Values should be unique per chart — stages sharing a name share one config/color entry and one legend row. |
+| `palette` | `ChartPalette` | `{ type: 'sequential', ramp: 'blue' }` | no | The dataviz palette the stages are painted from — the only source of a stage's colour, bar a per-stage `stageSettings.color`. Unlike every other chart, which takes the shared categorical default, a funnel defaults to the sequential blue ramp: its stages are an ordered series, which is what a ramp is for. Exported as FUNNEL_CHART_DEFAULT_PALETTE. |
+| `reversed` | `boolean` | `false` | no | Flip the stack so the funnel widens toward the bottom instead of narrowing. The gap-free stage — the one flush with the top of the plot area — becomes the last row rather than the first. |
+| `showLabels` | `boolean` | `false` | no | Render a label for each stage — see labelFormat and labelPosition. Off by default: the design's funnel carries no on-plot labels, because the legend beside it already names every stage. |
 | `labelFormat` | `'name' | 'value' | 'percent' | 'name-value' | 'name-percent' | 'value-percent'` | `'name'` | no | What each stage's label says. A percentage is the stage's share of the widest stage — its conversion from the top of the funnel, not a share of the sum, because a funnel's stages are nested subsets rather than parts of a whole. The value is formatted by labelFormatter and the share by percentFormatter. A composite format (a pair) narrows the funnel to leave itself room, unless funnelWidth says otherwise. |
 | `labelPosition` | `'right' | 'left' | 'inside'` | `'right'` | no | Where each stage's label sits. `right`/`left` place it beside the segment on the chart surface; `inside` centres it on the segment, which switches the label to the on-fill color so it keeps contrast over a saturated fill. `inside` only works while every stage is wide enough to hold the text — a funnel narrows, so its last stages often are not; keep the text short there (`percent`) or leave the labels beside the funnel. |
 | `showValueLabels` | `boolean` | `false` | no | Render a second label carrying the stage's value, so the name and the number can sit on opposite sides of the funnel. |
@@ -118,16 +159,14 @@ real data-viz palette lands.
 | `labelFill` | `string` | — | no | Color for both label lists, overriding the contrast-matched default. Pass a --ui-* token; only needed when the default doesn't work on the surface. |
 | `labelFormatter` | `(value: number | string, index?: number) => string` | — | no | Format the numeric part of a label. |
 | `percentFormatter` | `(value: number | string, index?: number) => string` | — | no | Format the conversion share behind the percent formats. Receives the share as a fraction (0.52); defaults to a one-decimal bare percentage ("52.0%"). Replace it for a locale that doesn't write a bare percent sign. |
-| `showLegend` | `boolean` | `false` | no | Render the legend — one entry per visible stage. Off by default because a funnel labels its stages on the chart. |
-| `legendPos` | `'top' | 'bottom'` | `'bottom'` | no | Which edge the legend sits on. |
-| `colorMode` | `'palette' | 'gradient'` | `'palette'` | no | How the stages are colored. `palette` gives each stage its own config color; `gradient` ramps one hue from the widest stage down to the narrowest, mixing it toward the surface so every segment stays opaque. |
-| `gradientColor` | `string` | — | no | The hue gradient mode ramps. Defaults to the first visible stage's own color — including a stageSettings color set on it, since that is what the stage actually paints with. Ignored when colorMode is palette. |
-| `stageSettings` | `Record<string, { color?: string; hidden?: boolean }>` | — | no | Per-stage overrides keyed by the stage's nameKey value. `color` wins over both config and colorMode; `hidden` drops the stage from the funnel, its labels, the legend, and the conversion percentages. |
+| `showLegend` | `boolean` | `true` | no | Render the stage list beside the plot — one two-column row per visible stage, a sibling of the plot rather than a renderer legend. On by default, because it is where the design's funnel names its stages. With it off the row centres its lone plot. |
+| `legendValueFormatter` | `(value: string | number) => string` | — | no | Format the value in each legend row — the stage's dataKey number. Omit to stringify the raw value. |
+| `stageSettings` | `Record<string, { color?: string; hidden?: boolean }>` | — | no | Per-stage overrides keyed by the stage's nameKey value. `color` replaces that stage's palette stop, in the funnel and in its legend marker; `hidden` drops the stage from the funnel, its labels, the legend, and the conversion percentages. |
 | `showActiveShape` | `boolean` | `false` | no | Outline the hovered segment, rather than changing its fill, so it keeps the color that ties it to its legend entry and label. |
-| `stroke` | `string` | — | no | Segment border color — reference an existing --ui-* token. Defaults to the border token when strokeWidth is set on its own, because the renderer's own default is a hardcoded white the container neutralizes. |
+| `stroke` | `string` | — | no | Segment border color — reference an existing --ui-* token. Defaults to the border token when strokeWidth is set on its own, because the renderer's own default there is a hardcoded white the container neutralizes. |
 | `strokeWidth` | `number` | — | no | Segment border width, in px. Implies a default stroke when given alone. |
 | `funnelWidth` | `number | string` | — | no | Funnel width — px, or a percentage of the plot area ('70%'). Defaults to the full plot area, except that a composite labelFormat beside the funnel narrows it: the renderer word-wraps a label against the gap between its segment and the plot-area edge, so narrowing the funnel is what creates label room. A margin cannot — it moves that edge inward with the funnel. |
-| `margin` | `{ top?: number; right?: number; bottom?: number; left?: number }` | — | no | Plot-area margin, in px, merged over the defaults per side so passing one side keeps the others. It reserves the side a label list sits on so unwrappable text isn't clipped at the SVG edge — see funnelWidth for the label's wrap room. |
+| `margin` | `{ top?: number; right?: number; bottom?: number; left?: number }` | `{ top: 4, right: 8, bottom: 4, left: 8 }` | no | Plot-area inset, in px, merged over the defaults per side so passing one side keeps the others. The default is the design's own tight inset — the room the rounded corners and the apex need — and applies whenever nothing sits beside the funnel. As soon as a label list does, the side it sits on widens so unwrappable text isn't clipped at the SVG edge; see funnelWidth for the label's wrap room. |
 | `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. |
 | `animate` | `boolean` | `false` | no | Enable entrance animation. Off by default so output/baselines are unchanged. |
@@ -138,39 +177,133 @@ real data-viz palette lands.
 ## Behavior
 
 `FunnelChart` is a typed [recharts](https://recharts.org) composition over the
-shared `Chart` primitives. It plots a single series of stages (`data` rows) as
-stacked, narrowing segments inside a `ChartContainer`.
+shared `Chart` primitives. It lays out a square plot and a stage-list legend in a
+row: the plot stacks one series of stages (`data` rows) as narrowing segments
+inside a `ChartContainer`, and the legend beside it names them.
 
 ```gherkin
 Scenario: Render stages from data and config
-  Given data rows and a config mapping each stage name to a label and color
+  Given data rows and a config mapping each stage name to a label
   And dataKey "value" and nameKey "stage"
   Then one segment renders per row, sized by its dataKey value
-  And each segment fills from its injected --color-<name> custom property
+  And each segment is painted from its palette stop
+```
+
+### Layout
+
+```gherkin
+Scenario: The plot and the legend sit side by side
+  Given a FunnelChart with its default chrome
+  Then the root is a row holding a 120×120 square plot, a 16px gutter, and the
+    legend column
+  And the legend column takes every pixel the plot does not
+```
+
+```gherkin
+Scenario: The component has no size of its own
+  Given a parent wider than the plot
+  And no label list sits beside the funnel
+  Then the component fills that width and the legend column absorbs the surplus
+  And the plot stays a 120×120 square rather than stretching into a tall wedge
+```
+
+```gherkin
+Scenario: The plot grows when labels sit beside the funnel
+  Given showLabels is true and labelPosition is "right" or "left"
+    Or showValueLabels is true and valuePosition is "right" or "left"
+  Then the plot-frame switches to h-[120px] flex-1 and grows with available width
+  Because the label margins would otherwise consume the entire 120px fixed width
+```
+
+```gherkin
+Scenario: The lone plot centres
+  Given showLegend is false
+  Then the plot is the row's only child and is centred in it
+```
+
+```gherkin
+Scenario: No card of its own
+  Given a FunnelChart rendered directly
+  Then it draws no card, header or metric row — those belong to ChartWidget
+```
+
+### Geometry
+
+```gherkin
+Scenario: Surface shows between the stages
+  Given a funnel of n stages
+  Then 2px of surface separates each stage from the one above it, n-1 times over
+  And the topmost stage stays flush with the top of the plot area
+```
+
+```gherkin
+Scenario: Every stage is rounded
+  Given any funnel
+  Then each stage's corners are rounded by 2px, the triangle's apex included
+```
+
+```gherkin
+Scenario: The gap and the radius are the component's own drawing
+  Given the renderer's funnel shape supports neither a gap nor a radius
+  Then the component draws each stage itself, so both survive on hover too
+```
+
+```gherkin
+Scenario: Plot-area inset with nothing beside the funnel
+  Given no label list sits beside the funnel
+  Then the plot area is inset by 4 top, 8 right, 4 bottom and 8 left — the room
+    the rounded corners and the apex need, and nothing more
 ```
 
 ```gherkin
 Scenario: Triangle last shape (default)
   Given lastShape is "triangle"
-  Then the final segment narrows to a point
+  Then the final stage narrows to a point
 ```
 
 ```gherkin
 Scenario: Rectangle last shape
   Given lastShape is "rectangle"
-  Then the final segment ends flat (a stack of trapezoids)
+  Then the final stage keeps a flat lower edge (a stack of trapezoids)
 ```
 
 ```gherkin
 Scenario: Reversed
   Given reversed is true
   Then the funnel widens toward the bottom instead of narrowing
+  And the gap-free stage is the last row rather than the first
 ```
 
+### Colour
+
 ```gherkin
-Scenario: Stage labels
-  Given showLabels is true
-  Then each stage's name renders beside its segment
+Scenario: The default palette is a ramp, not a categorical set
+  Given no palette is given
+  Then the stages are painted from the sequential blue ramp, because a funnel's
+    stages are an ordered series
+  And every other chart type still defaults to the shared categorical palette
+```
+
+```gherkin
+Scenario: Palette is the only source of a stage's colour
+  Given a palette and a config
+  Then each stage takes a palette stop; config supplies its label, not its colour
+```
+
+```gherkin
+Scenario: Per-stage colour override
+  Given a stageSettings entry keyed by a stage's nameKey value carries a color
+  Then that stage paints with it in the funnel and in its legend marker,
+    whatever the palette says
+```
+
+### Labels
+
+```gherkin
+Scenario: On-plot labels are off by default
+  Given showLabels is unset
+  Then no stage labels render on the plot, because the legend already names them
+  And showLabels renders them
 ```
 
 ```gherkin
@@ -227,53 +360,74 @@ Scenario: A composite label gets room by narrowing the funnel
   And a caller-supplied funnelWidth replaces the reserve
 ```
 
+```gherkin
+Scenario: A label list widens the inset on its own side
+  Given a label list sits beside the funnel
+  Then the plot area's inset on that side widens, so text that cannot wrap is not
+    clipped at the SVG edge
+```
+
 ```gherkin
 Scenario: A partial margin keeps the other sides
   Given a margin that sets only one side
   Then the remaining sides keep their default insets rather than collapsing to zero
 ```
 
+### Legend
+
 ```gherkin
-Scenario: Legend is opt-in
+Scenario: The legend is visible by default
   Given showLegend is unset
-  Then no legend renders
+  Then the stage list renders beside the plot
+  And showLegend=false hides it
+```
+
+```gherkin
+Scenario: The legend is a sibling of the plot, not a chart legend
+  Given showLegend is true
+  Then the list is ordinary HTML outside the plot's SVG, never a renderer legend
+    and never a row below the funnel
 ```
 
 ```gherkin
 Scenario: Legend entries come from the visible stages
   Given showLegend is true
-  Then one entry renders per distinct visible stage name, labelled and colored
-    from config
-  And two stages sharing a name share the single entry they share a color with
-  And it sits on the edge given by legendPos (bottom by default)
+  Then one two-column row renders per distinct visible stage name
+  And the inline start holds the stage's round marker and its config label
+  And the inline end holds the stage's dataKey value, formatted by
+    legendValueFormatter when one is given
+  And two stages sharing a name share the single row they share a colour with
 ```
 
 ```gherkin
-Scenario: Gradient color mode
-  Given colorMode is "gradient"
-  Then every stage fills from one hue — gradientColor, or the first visible stage's
-    own color, including a stageSettings color set on it
-  And the hue is mixed further toward the surface at each stage down the funnel
+Scenario: Legend text colour
+  Given a legend row
+  Then both its label and its value use the primary on-surface text token, the
+    value in semibold — not the link colour the donut and radial legends give
+    their values
 ```
 
 ```gherkin
-Scenario: Per-stage color override
-  Given a stageSettings entry keyed by a stage's nameKey value carries a color
-  Then that stage fills with it, whatever config and colorMode say
+Scenario: Legend markers resolve their own colour
+  Given the legend sits outside the chart container
+  Then each marker carries its stage's resolved palette token, because the
+    container-scoped --color-<name> custom properties do not reach outside it
 ```
 
 ```gherkin
 Scenario: Hidden stage
   Given a stageSettings entry hides its stage
-  Then the stage has no segment, no label and no legend entry
+  Then the stage has no segment, no label and no legend row
   And the remaining conversions are measured over the visible stages only
 ```
 
+### Interaction
+
 ```gherkin
 Scenario: Active segment
   Given showActiveShape is true
   When the user hovers a stage
-  Then that segment is outlined and keeps its fill
+  Then that segment is outlined and keeps its fill, gap and rounded corners
 ```
 
 ```gherkin
@@ -306,28 +460,42 @@ Scenario: Reduced motion
 
 ## Accessibility
 
-- recharts' `accessibilityLayer` is **on by default** (recharts v3), giving the
-  chart keyboard focus and an accessible description of the plotted stages.
-- A funnel chart is inherently visual. **Pair it with a text alternative** — a
-  caption, a summary sentence, or an adjacent data table carrying the same
-  numbers (including the drop-off between stages, which the funnel only implies) —
-  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 stages. Keep `showLabels` (or the
-  tooltip) visible so each color is paired with a text label — the on-chart labels
-  are the funnel's naming channel (there is no legend).
-- The tooltip chrome resolves to semantic `--ui-*` tokens, and on-chart labels use
-  the foreground text token — both meet contrast in light and dark.
-  **Stage 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.
+- **No name of its own.** `FunnelChart` sets no `role` and no `aria-*`, and it
+  passes nothing down to the plot, so the `<title>`/`<desc>` pair the renderer
+  emits stays empty. Put the name on the root, which spreads the props you give
+  it: `aria-label` or `aria-labelledby` referencing a visible heading. Choose the
+  role deliberately — `role="img"` names the chart but makes its subtree
+  presentational, so a `<figure>` with a `<figcaption>` is often the better fit.
+- recharts' `accessibilityLayer` is **on by default** (recharts v3) and is not
+  switched off here, so the plot is a tab stop carrying `role="application"`.
+  Until the chart is named, that focus stop announces neither a name nor any
+  data. Watch recharts issue
+  [#4809](https://github.com/recharts/recharts/issues/4809) on the a11y layer for
+  heavily-customized charts.
+- **A name is not a text alternative.** A funnel encodes numbers as geometry, so
+  the numbers themselves have to be reachable as text — a caption, a summary
+  sentence, or an adjacent table carrying the same values (including the
+  drop-off between stages, which the funnel only implies).
+- **The legend is the reliable text.** It is on by default and is ordinary HTML
+  laid out beside the plot, so it reads in the accessibility tree: one row per
+  stage, the marker and label on the inline start, the value on the inline end.
+  The on-plot labels (`showLabels`, off by default) and value labels
+  (`showValueLabels`) are real `<text>` rather than pixels, but they sit inside
+  the SVG with no structural role, and a stage's name and its value are two
+  separate lists on opposite sides with nothing tying them together.
+- Do **not** rely on colour alone to distinguish stages. Keep the legend, the
+  on-plot labels, or the tooltip visible so every colour is paired with a text
+  label. A sequential ramp — the funnel's default palette — makes this stricter
+  than a categorical one: adjacent stops are neighbouring shades of one hue, not
+  distinct colours.
 
 ## Contrast
 
-Chart chrome and the on-chart stage labels meet contrast in both themes via the
-semantic tokens. Segment fills come from `config` and are the caller's
-responsibility — keep adjacent segments distinguishable from each other.
+Chart chrome, the legend and the on-plot labels resolve to semantic `--ui-*`
+tokens and meet contrast in light and dark: a label beside the funnel uses the
+primary on-surface token, a label on a segment switches to the on-fill token
+(white in both themes) so it survives a saturated stage fill. Stage fills come
+from the `--ui-dataviz-*` palettes rather than from caller-supplied colours, so
+their contrast against the surface is the design data's responsibility — but
+picking a ramp still trades stage-to-stage distinguishability for its ordered
+reading, so keep the stage count low.