@acronis-platform/ui-react 2.0.0 → 4.0.0

package/dist/llms/chart.md

@@ -0,0 +1,182 @@
+# Chart
+
+> A theming layer over recharts — a `ChartContainer` that supplies series colors and recharts class overrides, plus tooltip and legend chrome (`ChartTooltipContent`, `ChartLegendContent`). The chart type (bar / line / area / pie / …) is composed from recharts primitives by the caller. Ported from the legacy shadcn-uikit `chart`.
+
+**Status:** draft · **Category:** data-display · **Since:** v0.47.0
+
+## Import
+
+```tsx
+import { ChartContainer, ChartTooltip, ChartTooltipContent, ChartLegend, ChartLegendContent } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<ChartContainer config={config} className="h-[300px] w-[500px]">
+  <BarChart data={data}>
+    <ChartTooltip content={<ChartTooltipContent />} />
+    <Bar dataKey="desktop" fill="var(--color-desktop)" />
+  </BarChart>
+</ChartContainer>
+```
+
+A theming layer over [recharts](https://recharts.org). `ChartContainer` resolves
+each series' color from a **dataviz palette** and themes recharts' internals with
+the semantic token vocabulary; `ChartTooltipContent` and `ChartLegendContent` give
+the tooltip and legend the library's look. The chart type itself (bar / line /
+area / pie / …) is composed by the caller from recharts primitives.
+
+Series colors are never hand-written. `config` names the series, the `palette`
+prop says which palette they are painted from, and `ChartContainer` resolves each
+one into a `--color-<key>` custom property the recharts marks reference. Every
+palette resolves to `--ui-dataviz-*` tokens on the semantic tier.
+
+## When to use
+
+- Visualizing quantitative data — trends, comparisons, distributions.
+- You want recharts' flexibility but the Acronis tooltip/legend/axis styling.
+
+## When not to use
+
+- A single metric or KPI — use a `Tag`, `Badge`, or plain text.
+- Tabular detail — use `Table` / `DataTable`.
+- Progress toward a goal — use `Progress` or `ProgressCircle`.
+
+## Parts
+
+| Export                | Purpose                                                                                                      |
+| --------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `ChartContainer`      | The wrapper. Takes `config` + `palette` + the recharts plot as children; resolves and injects series colors. |
+| `ChartTooltip`        | Re-export of recharts' `Tooltip`. Pass `ChartTooltipContent` as its `content`.                               |
+| `ChartTooltipContent` | Themed tooltip body — label + per-series indicator/value.                                                    |
+| `ChartLegend`         | Re-export of recharts' `Legend`. Pass `ChartLegendContent` as its `content`.                                 |
+| `ChartLegendContent`  | Themed legend body — swatch + label per series.                                                              |
+| `ChartStyle`          | Injects the `--color-<key>` custom properties (used internally by `ChartContainer`).                         |
+
+`ChartConfig` is the per-series map of `label` / `icon` / `tone`. It carries no
+color: `tone` only re-points a series **within** the palette — `{ slot: n }` for
+another categorical hue, `{ status: '…' }` under the `status` palette, or
+`{ sameAs: 'key' }` to share another series' color.
+
+## Example
+
+```tsx
+import {
+  ChartContainer,
+  ChartTooltip,
+  ChartTooltipContent,
+  ChartLegend,
+  ChartLegendContent,
+  type ChartConfig,
+} from '@acronis-platform/ui-react';
+import { Bar, BarChart, CartesianGrid, XAxis } from 'recharts';
+
+// No colors here — the default `categorical` palette paints the series in the
+// order they are declared.
+const config = {
+  desktop: { label: 'Desktop' },
+  mobile: { label: 'Mobile' },
+} satisfies ChartConfig;
+
+<ChartContainer config={config} className="h-[300px] w-[500px]">
+  <BarChart data={data}>
+    <CartesianGrid vertical={false} />
+    <XAxis dataKey="month" tickLine={false} axisLine={false} />
+    <ChartTooltip content={<ChartTooltipContent />} />
+    <ChartLegend content={<ChartLegendContent />} />
+    <Bar dataKey="desktop" fill="var(--color-desktop)" radius={4} />
+    <Bar dataKey="mobile" fill="var(--color-mobile)" radius={4} />
+  </BarChart>
+</ChartContainer>;
+```
+
+`recharts` is a peer-resolved dependency of `@acronis-platform/ui-react`; import
+the chart primitives (`BarChart`, `Bar`, …) directly from `recharts`.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `config` | `ChartConfig` | — | yes | Per-series map of label / icon / tone. ChartContainer resolves each entry's colour out of `palette` and emits it as a `--color-<key>` custom property. Declare exactly the series the chart plots: a stop is assigned by an entry's position here, so an entry for a series that isn't drawn still consumes a colour and shifts the ones that follow. |
+| `palette` | `ChartPalette` | `{ type: 'categorical' }` | no | The dataviz palette the series are painted from — `categorical` (16 hues), `sequential` (a `ramp` of 8 stops), `diverging` (a `pair` of 6), or `status` (6 semantic tones). Series walk it in its defined order. There is no free-form colour and no "no palette" state, so a chart cannot paint a hue outside the design system. |
+| `active` | `boolean` | — | no | Whether the tooltip is showing (set by recharts on hover/focus). Drives ChartTooltipContent rendering. |
+| `hideLabel` | `boolean` | `false` | no | Hide the tooltip's heading label. |
+| `hideIndicator` | `boolean` | `false` | no | Hide the per-series color dot in the tooltip. |
+| `hideIcon` | `boolean` | `false` | no | Hide the per-series icon in the legend (use the color swatch). |
+| `nameKey` | `string` | — | no | Config key to resolve each series' label from the payload. |
+| `labelKey` | `string` | — | no | Config key to resolve the tooltip's heading label. |
+
+## Behavior
+
+Chart is a theming layer over [recharts](https://recharts.org). `ChartContainer`
+provides the series `config` (via context) and a sized, responsive box; the
+caller composes the actual plot from recharts primitives (`BarChart`, `LineChart`,
+`AreaChart`, `PieChart`, …). `ChartTooltipContent` and `ChartLegendContent` are
+passed to recharts' `Tooltip` / `Legend` through their `content` prop.
+
+```gherkin
+Scenario: Render a chart
+  Given a config and a recharts plot as children
+  Then the plot renders inside a responsive, aspect-video container
+  And recharts' grid, axis, and cursor pick up the semantic theme tokens
+```
+
+```gherkin
+Scenario: Series colors from palette
+  Given a config entry { desktop: { label: 'Desktop' } } and palette={ type: 'categorical' }
+  Then a `--color-desktop` custom property is injected scoped to this chart
+  And the value is the first stop of the categorical palette
+  And series referencing fill="var(--color-desktop)" paint with that color
+```
+
+```gherkin
+Scenario: Series tone override
+  Given a config entry with { failed: { tone: { status: 'danger' } } } and palette={ type: 'status' }
+  Then the `--color-failed` custom property resolves to the danger status token
+```
+
+```gherkin
+Scenario: Tooltip on hover
+  Given a ChartTooltip with content={<ChartTooltipContent />}
+  When the user hovers a data point
+  Then a card shows the point's label and one row per series
+  And each row has a color indicator (dot by default; line or dashed via `indicator`)
+```
+
+```gherkin
+Scenario: Legend
+  Given a ChartLegend with content={<ChartLegendContent />}
+  Then a swatch + label renders for each configured series
+  And a series icon replaces the swatch unless hideIcon is set
+```
+
+```gherkin
+Scenario: Default palette
+  Given a ChartContainer with no explicit palette prop
+  Then the categorical palette is used
+  And each series takes the next categorical stop in config-declaration order
+```
+
+## Accessibility
+
+- Charts are inherently visual. recharts renders an SVG surface; on its own a
+  chart conveys little to assistive tech, so **pair every chart with a text
+  alternative** — a caption, a summary sentence, or an adjacent data table that
+  carries the same numbers.
+- Give the `ChartContainer` an accessible name when the chart is meaningful on its
+  own (`aria-label` / `aria-labelledby` referencing a visible heading).
+- Do **not** rely on color alone to distinguish series. The legend pairs each
+  color swatch with a text label, and the tooltip shows series names next to
+  values — keep both visible (don't `hideLabel` + `hideIndicator` together).
+- The tooltip surface uses `--ui-background-surface-primary` with
+  `--ui-text-on-surface-primary` values and `--ui-text-on-surface-secondary`
+  labels; axis ticks use the muted token. These meet contrast in light and dark.
+  Series colors are caller-supplied — pick values that meet 3:1 against the
+  surface and are distinguishable for color-vision deficiencies.
+
+## Contrast
+
+The chart chrome (tooltip, legend, axis labels, grid) resolves to semantic
+`--ui-*` tokens that meet contrast in both themes. Series fills/strokes come from
+`config` and are the caller's responsibility.

package/dist/llms/checkbox.md

@@ -0,0 +1,257 @@
+# Checkbox
+
+> A control that lets users select or deselect an option. Supports checked, unchecked, and indeterminate states; used individually for a binary choice or in groups where any number of options may be selected.
+
+**Status:** ready · **Category:** forms · **Since:** v0.7.0
+
+## Import
+
+```tsx
+import { Checkbox } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+{/* Box only — name it with aria-label */}
+<Checkbox
+  aria-label="Accept terms"
+  checked={accepted}
+  onCheckedChange={setAccepted}
+/>
+
+{/* With label + description (the whole row toggles) */}
+<Checkbox
+  label="Email notifications"
+  description="Get notified when someone mentions you."
+  checked={accepted}
+  onCheckedChange={setAccepted}
+/>
+
+{/* Indeterminate (e.g. a partially-selected parent) */}
+<Checkbox aria-label="Select all" indeterminate />
+```
+
+A control that lets users select or deselect an option. Use it for a single
+binary choice (on/off) or in a group where users may select any number of
+options — including none. Supports an **indeterminate** state for a parent that
+summarizes a partially-selected group.
+
+## When to Use
+
+- A single on/off choice (e.g. "I accept the terms").
+- A list of non-exclusive options where any combination may be selected.
+- A "select all" parent that reflects a partial selection (indeterminate).
+
+## When NOT to Use
+
+- **Mutually exclusive** choices — use a radio group.
+- **On/off that applies immediately** (a setting toggle) — use a Switch.
+- **A single action** — use a Button.
+
+## Quick Examples
+
+### React
+
+```tsx
+import { Checkbox } from '@acronis-platform/ui-react';
+
+function Terms() {
+  const [accepted, setAccepted] = useState(false);
+  return (
+    <Checkbox
+      label="I accept the terms"
+      description="You agree to the privacy policy."
+      checked={accepted}
+      onCheckedChange={setAccepted}
+    />
+  );
+}
+```
+
+Pass `label` (and optional `description`) to compose the full field — the whole
+row becomes clickable and the box is wired to the text for accessibility. Omit
+them for a bare box, and name it with `aria-label`:
+
+```tsx
+<Checkbox aria-label="Select all" indeterminate />
+```
+
+## States
+
+| State         | How                           | Visual                             |
+| ------------- | ----------------------------- | ---------------------------------- |
+| Unchecked     | default                       | Idle border, no glyph              |
+| Checked       | `checked` / `default-checked` | Active fill + check glyph          |
+| Indeterminate | `indeterminate`               | Active fill + minus glyph, `mixed` |
+| Disabled      | `disabled`                    | Disabled tokens; not interactive   |
+
+## Spec Files
+
+| File               | Contents                                                          |
+| ------------------ | ----------------------------------------------------------------- |
+| `index.yaml`       | Identity, status, category, dependencies, Figma link              |
+| `anatomy.yaml`     | Root, container/content/label/description/indicator parts, states |
+| `api.yaml`         | Framework-agnostic contract + framework adapters                  |
+| `tokens.yaml`      | `--ui-checkbox-*` token references                                |
+| `behavior.md`      | Given/When/Then behavior scenarios                                |
+| `accessibility.md` | ARIA roles, keyboard map, screen-reader and contrast requirements |
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `checked` | `boolean` | — | no | Controlled checked state. Pair with the change event. |
+| `default-checked` | `boolean` | `false` | no | Initial checked state when uncontrolled. |
+| `indeterminate` | `boolean` | `false` | no | Renders the mixed/indeterminate state (minus glyph, aria-checked="mixed"). Independent of `checked` — set by the consumer, not toggled by clicking. |
+| `disabled` | `boolean` | `false` | no | Disables interaction; applies the disabled form tokens. |
+| `required` | `boolean` | `false` | no | Marks the control as required in a form. |
+| `name` | `string` | — | no | Form field name submitted with the form. |
+| `value` | `string` | — | no | Form field value when checked. |
+| `label` | `ReactNode` | — | no | Optional label rendered beside the box. When provided, the whole row becomes a clickable `<label>` and the box is named via aria-labelledby. |
+| `description` | `ReactNode` | — | no | Optional secondary description rendered under the label, associated with the box via aria-describedby. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `checked-change` | `boolean` | Fired when the checked state changes (React: `onCheckedChange`). Payload is the new checked value. |
+
+## Behavior
+
+### Rendering
+
+#### Renders unchecked by default
+
+**Given** a Checkbox with no `checked` / `default-checked`
+**When** it renders
+**Then** it exposes `role="checkbox"` with `aria-checked="false"`
+**And** no glyph is shown
+
+#### Reflects a controlled checked prop
+
+**Given** a Checkbox with `checked`
+**When** it renders
+**Then** `aria-checked="true"` and the check glyph is shown
+
+#### Renders the indeterminate state
+
+**Given** a Checkbox with `indeterminate`
+**When** it renders
+**Then** `aria-checked="mixed"` and the minus glyph is shown
+
+---
+
+### Interaction
+
+#### Toggles on click (uncontrolled)
+
+**Given** an uncontrolled Checkbox
+**When** the user clicks it (or presses Space while focused)
+**Then** the checked state flips
+**And** `checked-change` fires with the new value
+
+#### Controlled mode defers to the consumer
+
+**Given** a Checkbox with a controlled `checked` value
+**When** the user clicks it
+**Then** `checked-change` fires with the requested value
+**And** the visual state changes only when the consumer updates `checked`
+
+#### Disabled blocks interaction
+
+**Given** a Checkbox with `disabled`
+**When** the user clicks it
+**Then** the state does not change
+**And** `checked-change` does not fire
+**And** the disabled form tokens are applied
+
+---
+
+### States
+
+#### Hover
+
+**Given** an enabled Checkbox
+**When** the pointer hovers it
+**Then** the border uses `--ui-checkbox-unchecked-box-border-color-hover`
+
+#### Focus
+
+**Given** a Checkbox
+**When** it receives keyboard focus
+**Then** a 3px focus ring (`--ui-focus-primary`) is shown
+
+#### Checked / indeterminate fill
+
+**Given** a checked or indeterminate Checkbox
+**When** it renders
+**Then** the box fills with `--ui-checkbox-checked-box-color-idle` and the border with
+`--ui-checkbox-checked-box-border-color-idle`
+
+---
+
+### Edge Cases
+
+#### Indeterminate is independent of checked
+
+**Given** a Checkbox with both `indeterminate` and `checked`
+**When** it renders
+**Then** `aria-checked="mixed"` wins (the minus glyph is shown)
+
+#### Form submission
+
+**Given** a Checkbox with `name` and `value` inside a form
+**When** the form is submitted while checked
+**Then** the field is included with its value
+
+## Accessibility
+
+Implements the [WAI-ARIA Checkbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/)
+via Base UI's Checkbox primitive.
+
+## ARIA Roles and Attributes
+
+| Attribute       | Value                        | Reason                                       |
+| --------------- | ---------------------------- | -------------------------------------------- |
+| `role`          | `"checkbox"`                 | Identifies the control                       |
+| `aria-checked`  | `"true" / "false" / "mixed"` | Reflects checked / unchecked / indeterminate |
+| `aria-disabled` | present when disabled        | Conveyed via the disabled state              |
+
+The control must have an **accessible name** — provide a visible `<label>`
+associated with it, or an `aria-label` / `aria-labelledby` when used standalone.
+
+## Keyboard Navigation
+
+| Key   | Action                        |
+| ----- | ----------------------------- |
+| Tab   | Moves focus to / from the box |
+| Space | Toggles checked / unchecked   |
+
+The box is focusable in its enabled state and removed from the tab order when
+disabled.
+
+## Screen Reader Requirements
+
+1. Announced as a checkbox with its accessible name.
+2. Announces "checked", "not checked", or "mixed" from `aria-checked`.
+3. The glyph (check / minus) is decorative — it carries no separate semantics.
+
+## Color and Contrast
+
+| Element                  | Minimum Ratio | Standard               |
+| ------------------------ | ------------- | ---------------------- |
+| Box border vs background | 3:1           | WCAG 1.4.11 (non-text) |
+| Glyph vs active fill     | 3:1           | WCAG 1.4.11 (non-text) |
+| Focus indicator          | 3:1           | WCAG 1.4.11            |
+
+State is not conveyed by color alone — the check / minus glyph and
+`aria-checked` distinguish checked, indeterminate, and unchecked.
+
+## Testing Checklist
+
+- [ ] `role="checkbox"` with `aria-checked` reflecting true / false / mixed
+- [ ] Has an accessible name (label / `aria-label`)
+- [ ] Space toggles; Tab reaches it; disabled removes it from the tab order
+- [ ] Focus ring meets 3:1; border and glyph meet 3:1
+- [ ] `checked-change` does not fire while disabled

package/dist/llms/chip.md

@@ -0,0 +1,195 @@
+# Chip
+
+> A compact, interactive label for a selection, a removable token, or an inline action. The `removable` variant carries a trailing × button; `selectable` is a toggle that shows an active style when selected; `operational` is a plain action chip with a strong-link label. All three accept an optional leading icon.
+
+**Status:** ready · **Category:** data-display · **Since:** v0.36.0
+
+## Import
+
+```tsx
+import { Chip } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<Chip onRemove={() => remove(id)}>Filter</Chip>
+<Chip variant="selectable" selected={on} onClick={toggle}>Option</Chip>
+<Chip variant="selectable" icon={<CircleInfoIcon />}>With icon</Chip>
+<Chip variant="operational" onClick={addFilter}>Add filter</Chip>
+```
+
+A compact, interactive label — a removable token, a selectable toggle, or an
+operational action.
+
+## When to use
+
+- **Removable:** represent a dismissible selection — applied filters, recipients,
+  uploaded files, entered tags. The × lets the user drop one.
+- **Selectable:** offer a small, toggleable choice — filter/quick-pick chips,
+  multi-select option pills.
+- **Operational:** offer a small inline action that sits in a row of chips —
+  "Add filter", "Clear all", "Show 3 more". Its strong-link label marks it as
+  the actionable one among neighbouring chips.
+
+## When not to use
+
+- For a **static**, non-interactive status/category label, use
+  [`Tag`](../tag/README.md) instead — Chip implies an action (remove or toggle).
+- For a primary action, use `Button`. For a binary setting, use `Switch` or
+  `Checkbox`.
+
+## Parts
+
+| Part     | Element  | Notes                                                                                  |
+| -------- | -------- | -------------------------------------------------------------------------------------- |
+| `root`   | `div`    | The pill. `selectable` becomes a `role="button"` toggle, `operational` a plain button. |
+| `icon`   | `svg`    | Optional leading icon (16px), tinted by the icon token.                                |
+| `label`  | text     | Children; truncates with an ellipsis. Semibold + blue for `operational`.               |
+| `remove` | `button` | Trailing × (`removable` only); emits `remove` / `onRemove`.                            |
+
+## Examples
+
+```tsx
+import { Chip } from '@acronis-platform/ui-react';
+import { CircleInfoIcon } from '@acronis-platform/icons-react/stroke-mono';
+
+// Removable filter token
+<Chip onRemove={() => removeFilter(id)}>Status: Active</Chip>
+
+// Selectable (controlled) toggle
+<Chip variant="selectable" selected={on} onClick={() => setOn(!on)}>
+  Only my devices
+</Chip>
+
+// With a leading icon
+<Chip variant="selectable" icon={<CircleInfoIcon />}>Info</Chip>
+
+// Operational — an inline action among the chips
+<Chip variant="operational" onClick={addFilter}>Add filter</Chip>
+```
+
+## Notes
+
+- Selection and removal are **controlled** — Chip renders the visual state and
+  emits intent; the consumer owns the data.
+- Theming is driven entirely by the `--ui-chip-*` token tier; the focus ring
+  reuses `--ui-focus-primary`.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `variant` | `'removable' | 'selectable' | 'operational'` | `removable` | no | `removable` renders a trailing × button; `selectable` is a toggle (`role="button"` + `aria-pressed`) that applies the active style when `selected`; `operational` is a plain action chip (`role="button"`, no ×, no pressed state) whose label uses the strong-link style. All three share the `--ui-chip-*` box/border tokens and carry a per-variant label color. |
+| `selected` | `boolean` | `false` | no | `selectable` only — applies the selected (active) styling and sets `aria-pressed`. |
+| `icon` | `ReactNode` | — | no | Optional leading icon, rendered at 16px before the label. |
+| `removeLabel` | `string` | `Remove` | no | Accessible label for the remove (×) button. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `remove` | `none` | `removable` only — emitted when the trailing × button is activated (React: `onRemove`). |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | The chip label (children). Truncates when it overflows. |
+
+## Behavior
+
+### Removable
+
+- **Given** a `removable` chip
+  **When** it renders
+  **Then** it shows the label and a trailing × button.
+
+- **Given** a `removable` chip
+  **When** the user activates the × button (click, Enter, or Space)
+  **Then** the `remove` event fires (React: `onRemove`). The chip does **not**
+  remove itself — the consumer owns the list and decides what to drop.
+
+- **Given** a `removable` chip
+  **When** the user hovers or presses the chip
+  **Then** the container shows the hover / active fill + border.
+
+### Selectable
+
+- **Given** a `selectable` chip
+  **When** it renders
+  **Then** it is exposed as a toggle button (`role="button"`,
+  `aria-pressed` reflecting `selected`) with an optional leading icon and no ×.
+
+- **Given** a `selectable` chip
+  **When** the user activates it (click, Enter, or Space)
+  **Then** its `onClick` fires. Selection is **controlled**: the consumer flips
+  `selected`, which applies the active fill + border.
+
+- **Given** a `selectable` chip with `selected`
+  **When** it renders
+  **Then** the container uses the active fill + border and `aria-pressed="true"`.
+
+### Operational
+
+- **Given** an `operational` chip
+  **When** it renders
+  **Then** it is exposed as a button (`role="button"`) with an optional leading
+  icon, no ×, and a label in the strong-link style (semibold,
+  `--ui-chip-operational-label-color`).
+
+- **Given** an `operational` chip
+  **When** the user activates it (click, Enter, or Space)
+  **Then** its `onClick` fires. It has no selected state — unlike `selectable`
+  it does not report `aria-pressed`, because it triggers an operation rather
+  than toggling one.
+
+- **Given** an `operational` chip
+  **When** the user hovers or presses the chip
+  **Then** the container shows the hover / active fill + border, the same as
+  `removable`.
+
+### Content
+
+- **Given** a label longer than the chip's width
+  **When** it renders
+  **Then** the label truncates with an ellipsis; the chip keeps its min-width.
+
+## Accessibility
+
+## Roles
+
+- **Removable:** the chip container is presentational; the **× is a real
+  `<button>`** with an accessible name (`removeLabel`, default "Remove"). Give
+  it a contextual name when there are several chips (e.g. "Remove Backup").
+- **Selectable:** the chip container is a toggle — `role="button"` with
+  `aria-pressed` reflecting `selected`.
+- **Operational:** the chip container is a plain button — `role="button"` with
+  **no** `aria-pressed`, since it triggers an operation rather than toggling a
+  state. Announcing it as pressable-but-never-pressed would be a lie.
+
+## Keyboard
+
+- **Removable:** Tab focuses the × button; Enter / Space activate it (native
+  `<button>`).
+- **Selectable / operational:** Tab focuses the chip; Enter / Space activate it
+  (the component mirrors native button activation for the `div[role=button]`).
+
+## Focus
+
+- A visible 3px `--ui-focus-primary` ring marks focus — on the × button for
+  `removable` (via `focus-within` on the container) and on the chip itself for
+  `selectable` / `operational` (`focus-visible`). Focus is never suppressed
+  without a replacement indicator.
+
+## Screen readers
+
+- Selectable chips announce their pressed/unpressed state via `aria-pressed`;
+  operational chips announce as an ordinary button.
+- The remove button announces its label; pair it with the chip's text in the
+  accessible name when ambiguity is possible.
+
+## Contrast
+
+- Label, border, and icon colors come from `--ui-chip-*` tokens that meet the
+  contrast bar per theme; do not override them with ad-hoc colors.