@antadesign/anta 0.3.19 → 0.3.21

package/docs/components/input-time.md

@@ -20,14 +20,14 @@ or uncontrolled (`defaultValue`), and submits under `name` via the native form A
 
 Focus a section and edit it with the keyboard: ↑/↓ to step (it
 wraps), PageUp/PageDown for a larger jump on minutes,
-or just type the digits. Home/End, selection, deletion, and
+or enter the digits. Home/End, selection, deletion, and
 paste behave as they do in a native text input. Typing
 `9` then `3` `0` lands `09:30` and moves across the sections on its own; an
 out-of-range digit (a `6` in the minutes) commits and advances immediately.
 Backspace on an empty section selects the previous one. The whole thing
 reads as one field while preserving native caret behavior. In a
 12-hour field, typing a 24-hour hour converts it and flips AM/PM — `18` becomes
-`6 PM` — so pasting a 24-hour time just works.
+`6 PM`, so pasted 24-hour times work.
 
 ```tsx
 <InputTime label="Start time" defaultValue="09:30" onValueChange={(_, { value }) => save(value)} />
@@ -69,7 +69,7 @@ range is clamped to the nearest bound as you step or leave the field, and flags
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `children?` | ReactNode | — | Extra content rendered under the field, above the hint (a no-box child like
- a `<Tooltip>` takes no space and just anchors to the field). |
+ a `<Tooltip>` takes no space and anchors to the field). |
 | `clearable?` | boolean | — | Show a clear button once the field has a value. |
 | `defaultValue?` | string | — | Initial value for the uncontrolled case (24-hour `"HH:mm"`). |
 | `dimActions?` | boolean | — | Dim the trailing adornments at rest; they brighten on hover / focus. |
@@ -101,12 +101,12 @@ range is clamped to the nearest bound as you step or leave the field, and flags
  others are advisory. Omit (or `neutral`) for a plain field. |
 | `statusIcon?` | (string & {}) \| false \| IconShape | — | Glyph before the `hint` when `status` is set (per-status default; pass a
  shape to override, or `false` to drop it). |
-| `tone?` | string | — | Custom accent colour — any literal CSS colour tints the resting + hover
+| `tone?` | string | — | Custom accent color — any literal CSS color tints the resting + hover
  border (focus ring stays `--focus-ring`); `status` overrides for validation. |
 | `trailing?` | ReactNode | — | Content pinned to the end of the field (after the clear button). |
 | `value?` | string | — | Controlled value — 24-hour `"HH:mm"`. Pair with `onValueChange`. |
 
-Use this when you are not using the React or Preact wrapper and a native HTML control does not fit: construct the equivalent Anta web component from the elements below.
+Use the web component directly when you are not using React or Preact and a native control does not fit.
 
 Slots supply the field label and leading icon.
 
@@ -165,9 +165,9 @@ tighter `1em` line:
 `}</style>
 ```
 
-For a one-off accent, `tone` takes **any literal CSS colour** (e.g. `#7c3aed`) and
+For a one-off accent, `tone` takes **any literal CSS color** (e.g. `#7c3aed`) and
 tints the resting + hover border — the focus ring stays the global ring. It's a
-colour, not a named tone; the named feedback tones live on `status`.
+color, not a named tone; the named feedback tones live on `status`.
 
 ```tsx
 <InputTime label="Accent" tone="#7c3aed" defaultValue="09:30" />

package/docs/components/input.md

@@ -24,7 +24,7 @@ Anta's text scale, so a field lines up with same-size `Text` / `Button`.
 | `medium` | 28px | 15 / 20 | 16px |
 | `large` | 32px | 17 / 22 | 18px |
 
-## Label & hint
+## Label and hint
 
 ```tsx
 <Input label="Display name" defaultValue="Ada Lovelace" />
@@ -75,8 +75,8 @@ recolors it.
 
 It reuses the tone palette but isn't `tone`: **`status` is a validation *state*** (it
 also carries the glyph and, for `critical`, validity), whereas `tone` — elsewhere in
-Anta — is decorative colour. On `Input` the named tones live on `status`; `tone` is
-reserved for a one-off custom border colour.
+Anta — is decorative color. On `Input` the named tones live on `status`; `tone` is
+reserved for a one-off custom border color.
 
 Only `status="critical"` carries validity — it sets `aria-invalid`, flips the
 `:state(invalid)` hook, and reports invalid to a surrounding `<form>` through
@@ -87,7 +87,7 @@ Each status has a default glyph (`critical` → `warning-diamond`, `warning` →
 `circle-small-solid`). Override it with **`statusIcon`** (any shape), or drop it
 with `statusIcon={false}`.
 
-## Leading, trailing & clear
+## Leading, trailing, and clear
 
 ```tsx
 {/* clearable — the clear button shows once there's a value */}
@@ -191,13 +191,13 @@ Autogrow uses CSS `field-sizing` where supported (Chromium, Safari ≥ 26.2) and
 built-in JS resize everywhere else (Firefox, older Safari), so it grows in every
 browser.
 
-## Controlled & uncontrolled
+## Controlled and uncontrolled
 
 ```tsx
-// Uncontrolled — the element owns the value
+// Uncontrolled: the element updates its value after input.
 <Input label="Name" defaultValue="Ada" onChange={(e) => log(e.target.value)} />
 
-// Controlled — you own the value
+// Controlled: application state supplies the value.
 const [v, setV] = useState('')
 <Input label="Name" value={v} onInput={(e) => setV(e.target.value)} />
 ```
@@ -251,7 +251,7 @@ Because `<a-input>` is form-associated, it submits with the surrounding
 needed. `required` participates in native validity, and `<Button type="reset">`
 restores the field to its `defaultValue` via `formResetCallback`.
 
-## Types & validation
+## Types and validation
 
 ```tsx
 <Input type="text"     label="Text" />
@@ -263,7 +263,7 @@ restores the field to its `defaultValue` via `formResetCallback`.
 ```
 
 `type` accepts `text` (default), `email`, `password`, `tel`, `url`, and
-`number` — each gets the right mobile keyboard, autofill behaviour, and native
+`number` — each gets the right mobile keyboard, autofill behavior, and native
 constraint validation. (`search` is omitted on purpose — see above.)
 `number` also takes `min` / `max` / `step`.
 
@@ -433,7 +433,7 @@ wraps to fewer columns as it narrows. Resize the preview to see it reflow.
  `username`, `current-password`, `new-password`, `one-time-code`, or `off`. |
 | `children?` | ReactNode | — | Extra content rendered directly under the field, above the hint/error (it
  pushes the message down). A no-box child like an Anta `<Tooltip>` takes no
- space and just anchors to the field — consistent with how tooltips attach
+ space and anchors to the field — consistent with how tooltips attach
  to any other element. Use the named `leading` / `trailing` props for
  in-field content. |
 | `clearable?` | boolean | — | Show a clear button as the first trailing item once the field has a
@@ -508,7 +508,7 @@ wraps to fewer columns as it narrows. Resize the preview to see it reflow.
  success → `circle-check`, info → `info`, brand → `circle-small-solid`); pass a
  shape to override, or `false` to drop it. `neutral` has no default glyph. |
 | `step?` | number \| string | — |  |
-| `tone?` | string | — | Custom accent colour — any literal CSS colour tints the resting + hover
+| `tone?` | string | — | Custom accent color — any literal CSS color tints the resting + hover
  border (focus ring stays the global `--focus-ring`). For consistency with the
  other controls' custom-tone knob; a `status` still overrides for validation. |
 | `trailing?` | ReactNode | — | Content pinned to the end of the field (e.g. icons, buttons), after the
@@ -523,7 +523,7 @@ this; use `truncate` when an editable field should keep the same treatment. |
  clear/search affordances never appear — Anta owns that chrome. |
 | `value?` | string | — | Controlled value. Pair with `onChange` / `onInput`. |
 
-Use this when you are not using the React or Preact wrapper and a native HTML control does not fit: construct the equivalent Anta web component from the elements below.
+Use the web component directly when you are not using React or Preact and a native control does not fit.
 
 Slots hold the label, hint, and controls around the native field.
 
@@ -563,7 +563,7 @@ their `size` attribute, so Anta does not reuse it. `round` and a custom-color
 ```
 
 Reach for the props first: **`status`** sets a validation tone (border + message),
-**`tone`** a custom accent colour for the border (any CSS colour), **`size`** the
+**`tone`** a custom accent color for the border (any CSS color), **`size`** the
 dimensions. The focus ring is the global [`--focus-ring`](../colors.md#focus-ring).
 
 ```tsx
@@ -587,7 +587,7 @@ The border is drawn as an **inset `box-shadow`**, not a real `border`, so its wi
 (`0.5px` → `1px` when a `status` is set) and placement never change the box size —
 the field height stays locked to the matching Button. Drop the leading `inset` to
 draw the border as an outset ring instead. You can also re-point an `--input-*`
-colour token on one instance (`style={{ '--input-border': 'var(--border-1)' }}`)
+color token on one instance (`style={{ '--input-border': 'var(--border-1)' }}`)
 or a wrapping selector; the resolver lives in `@layer anta`, so any un-layered rule
 of yours wins.
 

package/docs/components/menu.md

@@ -1,6 +1,6 @@
 # Menu
 
-A dropdown or context menu that anchors to any target and just works. Place
+A dropdown or context menu that anchors to a target. Place
 `<Menu>` immediately after the trigger — a button, an icon, a whole region —
 and it opens on click, positions itself with room-aware flipping, and dismisses
 on outside-click, `Escape`, or scroll. Rows are dedicated **`MenuItem`s** (not
@@ -12,7 +12,7 @@ Open state is uncontrolled by default — pass **`onStateChange`** (event-first:
 observe it, or pass **`open`** to control it, applying `detail.next` to `open`
 from your `onStateChange` handler (submenus stay uncontrolled). `statechange` is
 **cancelable** and fires before the menu moves, so uncontrolled you can keep it
-open with `event.preventDefault()`. You can also grab a `ref` and call
+open with `event.preventDefault()`. You can also keep a `ref` and call
 `.open()` / `.close()` / `.toggle()`.
 
 ## Dropdown from a button
@@ -92,7 +92,7 @@ instead of its full border box. Anta's `Input` does this — it reports its fiel
 box — so a `Menu` placed after an `<Input>` (as in `Select`) lines up with the
 field, not the whole component (whose box also spans the label and hint).
 
-## Right-click & at-cursor
+## Open at the pointer
 
 Pass `context` to open on right-click (the `contextmenu` event) of the region
 the menu follows, positioned at the pointer — ideal for content surfaces like a
@@ -203,7 +203,7 @@ empty-state message (what `Select`'s `renderEmpty` uses).
 </Menu>
 ```
 
-## Pinned header & footer
+## Pinned header and footer
 
 `a-menu-header` and `a-menu-footer` name fixed regions around the scrolling
 items. Put `a-select-header` or `a-select-footer` in the same slots when a
@@ -225,7 +225,7 @@ footer stays the menu's divider.
 </Menu>
 ```
 
-## Custom content & the close contract
+## Custom content and the close behavior
 
 The close decision is read straight from the DOM on click — never from whether a
 handler called `preventDefault` — so it's safe in runtimes where event handlers
@@ -241,7 +241,7 @@ run off the UI thread. Walking out from the click, the nearest marker wins:
   menu without being a `MenuItem`.
 
 For programmatic open/close from app state, drive the `open` prop (the `state`
-attribute, `"open"` / `"closed"`) and react via `onStateChange`, or grab a `ref`
+attribute, `"open"` / `"closed"`) and react via `onStateChange`, or keep a `ref`
 and call `.open()` / `.close()` / `.toggle()`.
 
 ```tsx
@@ -313,7 +313,7 @@ a checkable menu.
 <MenuItem selectionIndicator="checkbox" label="Show archived" selected data-menu-open />
 ```
 
-## Badges, counters & hints
+## Badges, counters, and hints
 
 Drop a `<Tag>` (or any element) as a **child** of a `MenuItem` for a trailing
 counter or badge. Children render after the label but before the `kbd` hint and
@@ -356,6 +356,8 @@ navigating links.
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
+| `children?` | ReactNode | — | Item content. With `label` set, children are extra content — most
+ notably the nested `<Menu>` for a submenu parent. |
 | `copy?` | string | — | Text copied to the clipboard on activation. |
 | `copyNode?` | boolean \| string | — | Copy a DOM node as rich text (`text/html`) + plain text. `true` copies
  the nearest ancestor marked `data-copy-source`; a string is a CSS
@@ -363,11 +365,73 @@ navigating links.
  from the copied output. |
 | `copyUrl?` | true | — | Copy the current page URL (`location.href`). |
 | `copyWithUrl?` | boolean | — | Prefix the copied text with `// URL: <current page URL>`. |
+| `disabled?` | boolean | — | Disable the item: greyed out, not focusable for activation, no close. A
+ disabled link also drops its `href`, so it can't navigate. |
+| `hint?` | ReactNode | — | Secondary text under the label — explanatory copy, like `RadioGroup`'s
+ option `hint`. Requires `label` (it stacks in a column beneath it). Muted
+ (`--text-3`) and tracks the row's `tone`. A string, or any node. |
+| `icon?` | IconShape | — | Leading icon shape. |
+| `iconTrailing?` | IconShape | — | A trailing icon. On a `submenu` item this **overrides** the default
+ chevron (omit it to keep the chevron); on a normal item it's the trailing
+ glyph (omit for none). |
+| `indeterminate?` | boolean | — | Only meaningful with `selectionIndicator="checkbox"`: render the box in the
+ mixed state (`aria-checked="mixed"`) — e.g. a "Select all" row when some but
+ not all of its options are selected. |
+| `indicator?` | React.ReactNode | — | Replace the built-in selection-indicator *visual* with your own node,
+ rendered at the **leading** edge (where the checkbox / radio sit). Pair with
+ `selectionIndicator` to keep the semantics — the row stays the control and
+ carries `role` + `aria-checked`; only the drawn mark changes. Suppresses the
+ built-in checkbox / radio and the trailing `check` glyph. The node is made
+ passive (aria-hidden, no pointer events) so the row receives the click. |
+| `kbd?` | string | — | A trailing keyboard-shortcut hint, e.g. `"⌘E"`. |
+| `label?` | ReactNode | — | The item's text. Usually a string, but any node is accepted — e.g. a filtered
+ `Select` bolds the matched substring. Omit and pass `children` for richer
+ content. |
 | `onCopied?` | (ok) => void | — | Fires after the copy attempt with whether it succeeded. |
 | `onCopyRequest?` | () => void | — | Compute the copy content lazily. Fires on pointerdown / keydown; update
  `copy` (a state change) here and the activation copies the latest value.
  The gap lets the update land even off the UI thread — only the
  serializable `copy` string crosses. |
+| `onMouseDown?` | (event) => void | — | Raw `mousedown` on the row. Mainly to `preventDefault()` so the row doesn't
+ take focus on a mouse press — e.g. a combobox option keeping focus in its
+ input field while the click still selects. |
+| `onSelect?` | (event, detail) => void | — | Activation handler — fires when *this* item is chosen (click / Enter /
+ Space), unless it's `disabled`. It does **not** fire for a submenu parent
+ (clicking that opens the flyout, which isn't a selection) nor for a
+ selection bubbling up from a nested submenu. On a link item it fires
+ alongside the navigation. Receives the event plus a `{ value, label }`
+ detail. |
+| `role?` | string | — | ARIA role override. Defaults to the role implied by `selectionIndicator`
+ (`menuitem` / `menuitemcheckbox` / `menuitemradio`); set it to reparent the
+ row under a different container role — e.g. `option` inside a `listbox`. |
+| `selected?` | boolean | — | Mark the item as selected. On a plain row (no `selectionIndicator`) this is
+ a persistent background tint, the same resting fill a pressed row shows —
+ also the way to flag the current page on a link item. On a checkable row
+ (`selectionIndicator` set) it instead drives the leading `checkbox` / `radio`
+ indicator and the row's `aria-checked`. |
+| `selectionIndicator?` | 'checkbox' \| 'radio' \| 'check' | — | Turn the row into a checkable item, driven by `selected` (the row stays the
+ control and carries `aria-checked`):
+ - `'checkbox'` → `role="menuitemcheckbox"`, a leading passive `<a-checkbox>`
+   (before `icon`); the tint is dropped (the box carries state).
+ - `'radio'` → `role="menuitemradio"`, a leading passive `<a-radio>`; tint dropped.
+ - `'check'` → `role="menuitemradio"`, a trailing check glyph on the selected
+   row *and* the background tint (the canonical single-select look).
+ Omit for a plain row (the default). |
+| `submenu?` | boolean | — | Marks this item as a submenu parent: adds the trailing chevron and
+ `aria-haspopup="menu"`. Nest the flyout as a `<Menu>` child. |
+| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | neutral | Semantic tone — colors the label, icon, and hover/selected tint (and the
+ `checkbox`/`radio` indicator, which adopts it). A named tone, or any literal
+ CSS color (`'#ff1493'`, `'rebeccapurple'`) for a one-off custom tone whose
+ hue + chroma are kept while the lightness is pinned to match the brand text.
+ `critical` is the destructive action; `neutral` (the default) is the standard
+ gray. |
+| `toneSelected?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | neutral | Like `tone`, but applied only while the row is `selected` — an unselected row
+ stays neutral. The whole selected row (label, icon, tint, and the `checkbox` /
+ `radio` indicator) takes the tone. Same value set as `tone`; on a selected row
+ `toneSelected` wins over `tone` when both are set. |
+| `value?` | string \| number | — | An opaque value identifying this item, handed back in `onSelect`'s detail
+ so a shared handler can tell which row was chosen without a per-item
+ closure. |
 
 ## Keyboard
 
@@ -401,7 +465,7 @@ call `event.preventDefault()` to keep the menu as-is (e.g. block a dismiss).
 Controlled, the menu never self-moves — apply `detail.next` to `open` to accept,
 or do nothing to reject. (Submenus are always uncontrolled, regardless of `open`.)
 
-Use this when you are not using the React or Preact wrapper and a native HTML control does not fit: construct the equivalent Anta web component from the elements below.
+Use the web component directly when you are not using React or Preact and a native control does not fit.
 
 Put a focusable trigger immediately before `<a-menu>` and omit `state` for an
 uncontrolled menu. Its light-DOM `<a-menu-item>` rows need their own `tabindex`

package/docs/components/progress.md

@@ -106,7 +106,7 @@ radius.
 | `round?` | boolean \| number \| string | — | Fully-round track (`border-radius: 999px`); the fill is clipped to it. Pass a
  `number` (px) or a CSS length string for a custom radius. |
 | `size?` | 'small' \| 'medium' \| 'large' | medium | Size variant. Scales the track and the default label row together. |
-| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Colour variant, or any literal CSS colour for a one-off custom tone (the
+| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Color variant, or any literal CSS color for a one-off custom tone (the
  surface / indicator / text are derived from it in oklch). Named tones track
  light/dark automatically. |
 | `value?` | number \| false | — | Current progress value. Omit this prop, or pass `false`, to show
@@ -171,7 +171,7 @@ a-progress.fancy::part(indicator) {
 }
 a-progress.fancy::part(indicator)::after { background: none; }   /* hard right edge */
 
-/* the percentage / label / hint are light-DOM children — recolour for the bar */
+/* the percentage / label / hint are light-DOM children — recolor for the bar */
 a-progress.fancy a-progress-number,
 a-progress.fancy a-progress-text { color: #fff; }
 a-progress.fancy a-progress-hint { color: var(--text-2); }

package/docs/components/radio.md

@@ -5,7 +5,7 @@ A single-select control. `RadioGroup` is the whole component — you pass it an
 navigation, and the form value. There's no separate `Radio` component: options
 are data, not markup.
 
-## Options, label & hint
+## Options, label, and hint
 
 ```tsx
 <RadioGroup
@@ -27,6 +27,10 @@ styled like `Input`'s hint.
 The group's own `label` and `hint` form a header **above** the options: the
 `label` first, the `hint` (an instruction for the whole set) directly under it.
 
+Each option can also set `className`, `style`, and `data-*`.
+`RadioGroup` forwards them to that option's `<a-radio>` so you can add
+per-option presentation and application metadata.
+
 ## Tones
 
 ```tsx
@@ -42,12 +46,12 @@ The group's own `label` and `hint` form a header **above** the options: the
 ```
 
 Six named tones — `neutral` (default), `brand`, `info`, `success`, `warning`,
-`critical`. `tone` colours the **mark** in every state — the selected-ring fill + dot
+`critical`. `tone` colors the **mark** in every state — the selected-ring fill + dot
 and (for a tinted tone) the unselected ring border (a light shade of the fill that
 darkens on hover and active; `neutral` keeps a grey ring). The label and hint stay
-neutral — colour them in plain CSS with the `--text-N-{tone}` tokens. Set `tone` on
-the `RadioGroup` to colour every option, or on a single option to override just that
-one. Any literal CSS colour works too, for a one-off custom tone.
+neutral — color them in plain CSS with the `--text-N-{tone}` tokens. Set `tone` on
+the `RadioGroup` to color every option, or on a single option to override just that
+one. Any literal CSS color works too, for a one-off custom tone.
 
 ## Selected-only tone
 
@@ -67,7 +71,7 @@ neutral grey. Reach for it instead of `tone` when a resting tinted border would
 as a validation error. Same tone set; set it on the group, or on a single option to
 override one.
 
-To colour the **label and hint**, there's no prop — add a `color` rule on the
+To color the **label and hint**, there's no prop — add a `color` rule on the
 option's `a-radio-label` / `a-radio-hint` with a `--text-N-{tone}` value.
 
 ## Size
@@ -89,7 +93,7 @@ Three sizes scale the control circle **and** the label + hint type together:
 `large` (18px / 17px). Set it on the `RadioGroup`, or on a single option to
 override one.
 
-## Orientation & layout
+## Orientation and layout
 
 ```tsx
 <RadioGroup
@@ -145,11 +149,11 @@ navigation and dropped from the tab order.
 />
 ```
 
-`status` recolours the group `hint` for feedback — the same tone set as
+`status` recolors the group `hint` for feedback — the same tone set as
 [`Input`](./input.md): `critical`, `warning`, `success`, `info`, `brand`
 (omit for neutral). It styles the message only; drive it from your own validation.
 
-## Keyboard & accessibility
+## Keyboard and accessibility
 
 The group is one Tab stop: `Tab` moves into the selected option (or the first
 enabled one), the arrow keys (`↑`/`↓`/`←`/`→`) move the selection between enabled
@@ -250,8 +254,7 @@ element — `Input`, and the composed `Select` — skip it and expose only
 |------|------|---------|-------------|
 | `options` | RadioOption[] | — | The options. The wrapper renders one `<a-radio>` per entry and computes its
  `selected` / roving `tabindex` / `role` declaratively. |
-| `defaultValue?` | string | — | Initial selected value for the uncontrolled case (the wrapper then owns the
- selection in local state). |
+| `defaultValue?` | string | — | Initial selected value for uncontrolled use. |
 | `disabled?` | boolean | — | Disable the whole group. |
 | `hint?` | string | — | Plain-text description for the group, rendered directly under `label` (above
  the options) — typically instructional copy. Per-option helper text goes on
@@ -272,27 +275,27 @@ element — `Input`, and the composed `Select` — skip it and expose only
  (uncontrolled), or in controlled mode answer by updating `value` (reject by
  doing nothing). `'reset'` (form reset) and `'restore'` (bfcache / autofill) are
  not cancelable — filter on `reason` if you only track user picks. |
-| `onValueChange?` | (event, attrs) => void | — | Like `onChange`, but with a `{ value, name }` snapshot as the 2nd argument —
- the ergonomic "just give me the new value" callback (mirrors `Input`). |
+| `onValueChange?` | (event, attrs) => void | — | Like `onChange`, but with a `{ value, name }` snapshot as the second argument,
+ matching `Input`. |
 | `orientation?` | 'vertical' \| 'horizontal' | 'vertical' | Layout + arrow-key axis. |
 | `size?` | 'small' \| 'medium' \| 'large' | 'medium' | Size applied to every option (an option's own `size` wins). |
-| `status?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' | 'neutral' | Validation/feedback tone for the group `hint` — recolours it (same tone set
+| `status?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' | 'neutral' | Validation/feedback tone for the group `hint` — recolors it (same tone set
  as `Input`'s `status`). Use `critical` for an error message, etc.; omit for
  the neutral default. |
 | `tone?` | 'brand' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Mark tone applied to every option (an option's own `tone` wins), or any literal
- CSS color for a one-off custom tone. Colours the selected-ring fill + dot *and*
+ CSS color for a one-off custom tone. Colors the selected-ring fill + dot *and*
  the unselected ring border. Named tones track light/dark mode. Use `toneSelected`
  instead to tone only the selected option and leave the rest neutral. The option
- text stays neutral — recolour it in plain CSS via the `--text-N-{tone}` tokens. |
-| `toneSelected?` | 'brand' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Like `tone`, but coloured onto the **selected option only** — every unselected
+ text stays neutral — recolor it in plain CSS via the `--text-N-{tone}` tokens. |
+| `toneSelected?` | 'brand' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Like `tone`, but colored onto the **selected option only** — every unselected
  ring stays neutral grey. Applied to every option (an option's own `toneSelected`
  wins). Prefer this over `tone` when a resting tinted border would read as a
  validation state. |
-| `value?` | string | — | Controlled selected value. When provided, the consumer owns selection: the
- group follows this prop and a pick only *requests* a change via
- `onStateChange` (reject by not updating). Leave undefined for uncontrolled. |
+| `value?` | string | — | Controlled selected value. The group follows this prop and reports a
+ requested change through `onStateChange`. Leave it undefined for
+ uncontrolled use. |
 
-Use this when you are not using the React or Preact wrapper and a native HTML control does not fit: construct the equivalent Anta web component from the elements below.
+Use the web component directly when you are not using React or Preact and a native control does not fit.
 
 The group owns selection and the single tab stop. Put options in `<a-radio-list>`.
 
@@ -323,8 +326,8 @@ treatments.
 </div>
 ```
 
-Reach for the props first: **`tone`** colours the mark in every state,
-**`toneSelected`** only the selected option (any CSS colour for a custom tone, set on
+Reach for the props first: **`tone`** colors the mark in every state,
+**`toneSelected`** only the selected option (any CSS color for a custom tone, set on
 the group or a single option — derives the full curve in oklch), **`size`** the
 dimensions + type. To tint the label + hint, add a `color` rule on the option's
 `a-radio-label` / `a-radio-hint` with the `--text-N-{tone}` values — there's no
@@ -343,7 +346,7 @@ masked — same heart as the checkbox):
 
 ```css
 /* Outlined — an unfilled selected ring: keep the ring background and paint the
-   border + dot in the tone colour (light-dark() tunes both themes at once). */
+   border + dot in the tone color (light-dark() tunes both themes at once). */
 a-radio-group.outlined a-radio:state(selected)::before {
   background: var(--radio-bg);
   border-color: light-dark(#5f4bc3, #7460d7);
@@ -357,7 +360,7 @@ a-radio-group.square a-radio:state(selected)::before { background: light-dark(#0
 a-radio-group.square a-radio:state(selected)::after { background: light-dark(#fff, #000); }   /* contrasting dot */
 
 /* Heart — a bigger ring with a heart mark (the dot ::after, masked) on a pink fill.
-   Same heart SVG as the checkbox; mask-size: contain centres it in the bigger ring. */
+   Same heart SVG as the checkbox; mask-size: contain centers it in the bigger ring. */
 a-radio-group.heart a-radio::before { inline-size: 22px; block-size: 22px; }   /* bigger ring */
 a-radio-group.heart a-radio::after {
   inline-size: 13px; block-size: 13px; border-radius: 0;