@antadesign/anta 0.3.26 → 0.3.28

package/docs/components/switch.md

@@ -17,16 +17,16 @@ The `Switch` wrapper renders a form-associated `<a-switch>` element. It works un
 
 ## Selected-only tone
 
-`toneSelected` colors the checked track only. The unchecked track and thumb stay neutral until the switch is on. Use it when a resting tinted control could imply a validation state. It accepts the same values as `tone`.
+`toneScope="selected"` applies the switch's `tone` to the checked track only. The unchecked track and thumb stay neutral until the switch is on. Use it when a resting tinted control could imply a validation state.
 
 ```tsx
-<Switch toneSelected="brand" label="Off stays neutral" />
-<Switch defaultChecked toneSelected="critical" label="Checked track tinted" />
+<Switch tone="brand" toneScope="selected" label="Off stays neutral" />
+<Switch defaultChecked tone="critical" toneScope="selected" label="Checked track tinted" />
 ```
 
 ## Coloring the text
 
-There is no text-tone prop. To tint the label, set `color` on the switch with a theme-aware `--text-N-{tone}` token; to tint the hint, target `a-switch-hint`. Pair either with `tone` or `toneSelected` to color the whole control.
+There is no text-tone prop. To tint the label, set `color` on the switch with a theme-aware `--text-N-{tone}` token; to tint the hint, target `a-switch-hint`. Pair either with `tone` to color the whole control.
 
 ```css
 /* The class is only for the demo — use your own selector. */
@@ -123,33 +123,28 @@ The wrapper sets `role="switch"` and keeps `aria-checked` in sync with the curre
 
 Space toggles the switch. It follows the [WAI-ARIA switch pattern](https://www.w3.org/WAI/ARIA/apg/patterns/switch/).
 
-### Props
+## Component props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `checked?` | boolean | — | Controlled checked value. In controlled mode, update this in `onStateChange`. |
 | `defaultChecked?` | boolean | false | Initial checked value for an uncontrolled switch. |
 | `disabled?` | boolean | — | Disables interaction and removes the switch from the tab order. |
-| `hint?` | ReactNode | — | Secondary text rendered under the label. It does not become part of the
-accessible name. |
+| `hint?` | ReactNode | — | Secondary text rendered under the label. It does not become part of the accessible name. |
 | `label?` | string | — | Visible, stable label for the setting. Use `children` for richer label content. |
-| `labelPosition?` | 'start' \| 'end' | 'end' | Put the visible label before or after the control. Grid layout changes only
-the visual order, preserving DOM/source order for assistive technologies. |
+| `labelPosition?` | 'start' \| 'end' | 'end' | Put the visible label before or after the control. Grid layout changes only the visual order, preserving DOM/source order for assistive technologies. |
 | `name?` | string | — | Form field name. A checked switch submits `value` under this name. |
 | `onChange?` | (event) => void | — | Native post-apply `change` event. |
-| `onStateChange?` | (event, detail) => void | — | Fired before a user toggle applies. Call `event.preventDefault()` to veto an
-uncontrolled change; controlled consumers accept by updating `checked`. |
+| `onStateChange?` | (event, detail) => void | — | Fired before a user toggle applies. Call `event.preventDefault()` to veto an uncontrolled change; controlled consumers accept by updating `checked`. |
 | `onValueChange?` | (event, attrs) => void | — | Post-apply callback with the new form-relevant value snapshot. |
-| `round?` | boolean \| number \| string | — | Fully round the thumb and track. Pass a `number` (px) or CSS length string
-for a custom track radius; the thumb radius is 3px smaller. |
+| `round?` | boolean \| number \| string | — | Fully round the thumb and track. Pass a `number` (px) or CSS length string for a custom track radius; the thumb radius is 3px smaller. |
 | `size?` | 'small' \| 'medium' \| 'large' | 'medium' | Size variant. small=26×16px, medium=30×18px, large=34×20px. |
-| `tone?` | 'brand' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'brand' | Color of the track and thumb. A tinted tone also colors the unchecked
-track border and thumb; use `toneSelected` to color only the checked track. |
-| `toneSelected?` | 'brand' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'brand' | Like `tone`, but applies only while the switch is checked. The unchecked
-track and thumb stay neutral. If both are set, `tone` colors the unchecked
-state and `toneSelected` colors the checked track. |
+| `tone?` | 'brand' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'brand' | Color of the track and thumb. A tinted tone also colors the unchecked track border and thumb; use `toneScope="selected"` to color only the checked track. |
+| `toneScope?` | ToneScope | 'all' | Apply `tone` to every state, or only while checked so the unchecked track and thumb stay neutral. |
 | `value?` | string | "on" | Value submitted while checked. |
 
+## Web Component
+
 Use the web component directly when you are not using React or Preact and a native control does not fit.
 
 The focusable host carries the state. Label and hint are light-DOM children.
@@ -161,7 +156,9 @@ The focusable host carries the state. Label and hint are light-DOM children.
 </a-switch>
 ```
 
-Reach for the props first: **`tone`** colors the checked track plus the unchecked chrome, while **`toneSelected`** colors only the checked track. Both accept any CSS color; **`size`** scales the control, label, and hint. The focus ring is the global [`--focus-ring`](../colors.md#focus-ring).
+## Styling
+
+Reach for the props first: **`tone`** chooses the control color, while **`toneScope`** chooses whether it colors all states or only the checked track. `tone` accepts any CSS color; **`size`** scales the control, label, and hint. The focus ring is the global [`--focus-ring`](../colors.md#focus-ring).
 
 ```tsx
 <Switch tone="#e0457b" defaultChecked label="Custom color" />

package/docs/components/tabs.md

@@ -166,6 +166,8 @@ its value is active. The panel names its tab as its accessible label
 Panels are **optional**. Without panels, `Tabs` renders the strip. Listen to
 `onStateChange` / `onValueChange` and render the content yourself.
 
+### JSX vs DOM
+
 The strip renders from the `options` array; each `<TabPanel>` renders a
 self-managing `<a-tabpanel>`. `Tabs` **never reads or toggles the panels**: there's
 no child introspection, so it renders the same in static SSR and works with any
@@ -196,6 +198,8 @@ and shows/hides **itself** via its own off-DOM `:state(active)`; nothing writes
 writes the light DOM, only your JSX does, which keeps a worker-thread reactive engine
 in sync.
 
+### Hiding an inactive panel
+
 A `<TabPanel>` stays mounted while inactive (its DOM, form values, and scroll
 survive tab switches); `hideMode` picks how it hides:
 
@@ -265,6 +269,8 @@ const [tab, setTab] = useState('overview')
 />
 ```
 
+## Keyboard & accessibility
+
 Every enabled tab is in the tab order; `Tab` / `Shift`+`Tab` step through them.
 The arrow keys also move between enabled tabs (wrapping at the ends), `Home` /
 `End` jump to the first / last, and `Space` / `Enter` activate the focused tab;
@@ -275,6 +281,8 @@ Pass `label` for the tablist's accessible name. Each `<TabPanel>` names its tab
 its accessible label (`aria-labelledby`), set off-DOM so nothing writes the panel's
 attributes.
 
+## Routing
+
 `Tabs` reports the picked value and leaves navigation to the app, so a strip can
 switch routes as readily as panels. Treat each `value` as a path: control `value`
 from the current location and navigate in `onStateChange` (the pick fires *on click*;
@@ -319,54 +327,56 @@ so those suit an uncontrolled strip reacting to its own pick. **`onFocus`** /
 <Tabs defaultValue="a" onValueChange={(_e, { value }) => route(value)}>…</Tabs>
 ```
 
+## Tabs props
+
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `children?` | ReactNode | — | Optional `<TabPanel value="…">` panels, one per tab value. Each is a
- self-managing `<a-tabpanel>` that shows itself when its `value` is the active
- tab. Omit them to use `Tabs` as a bare selectable strip. To place panels in a
- different layout region, or to unmount an inactive panel, drive selection with
- a controlled `value` and render the content yourself (see the docs). |
-| `defaultValue?` | string | — | Initial active value for the uncontrolled case. After first render `Tabs`
- owns selection itself. |
+| `children?` | ReactNode | — | Optional `<TabPanel value="…">` panels, one per tab value. Each is a self-managing `<a-tabpanel>` that shows itself when its `value` is the active tab. Omit them to use `Tabs` as a bare selectable strip. To place panels in a different layout region, or to unmount an inactive panel, drive selection with a controlled `value` and render the content yourself (see the docs). |
+| `defaultValue?` | string | — | Initial active value for the uncontrolled case. After first render `Tabs` owns selection itself. |
 | `disabled?` | boolean | — | Disable the whole strip. |
 | `fill?` | boolean | false | Makes horizontal tabs share the available inline space equally. |
 | `label?` | string | — | Accessible name for the tablist (`aria-label`). |
-| `noslide?` | boolean | — | Disable the sliding indicator. By default the selected-tab indicator animates
- between tabs (a single rectangle, via CSS anchor positioning); `noslide` paints it
- per tab so it snaps with no movement. (Browsers without anchor positioning get that
- per-tab paint automatically — `noslide` is the explicit opt-out.) |
+| `noslide?` | boolean | — | Disable the sliding indicator. By default the selected-tab indicator animates between tabs (a single rectangle, via CSS anchor positioning); `noslide` paints it per tab so it snaps with no movement. (Browsers without anchor positioning get that per-tab paint automatically — `noslide` is the explicit opt-out.) |
 | `onBlur?` | (event) => void | — | Focus left the strip entirely — wired to `focusout`. |
 | `onChange?` | (event) => void | — | Fired *after* the active tab changes — a native `change` event. |
-| `onFocus?` | (event) => void | — | Focus entered the strip (any tab) — wired to `focusin` (focus lands on a tab,
- not the tablist). |
-| `onStateChange?` | (event, detail) => void | — | Fired whenever the active tab changes — event-first. `detail` is
- `{ next, prev }` (values; `null` = none). Cancelable: `event.preventDefault()`
- vetoes it (uncontrolled), or in controlled mode answer by updating `value`. |
+| `onFocus?` | (event) => void | — | Focus entered the strip (any tab) — wired to `focusin` (focus lands on a tab, not the tablist). |
+| `onStateChange?` | (event, detail) => void | — | Fired whenever the active tab changes — event-first. `detail` is `{ next, prev }` (values; `null` = none). Cancelable: `event.preventDefault()` vetoes it (uncontrolled), or in controlled mode answer by updating `value`. |
 | `onValueChange?` | (event, attrs) => void | — | Like `onChange`, but with a `{ value }` snapshot as the 2nd argument. |
-| `options?` | TabOption[] | — | The tabs, as a data array (the strip's single source). Each entry is a
- `TabOption` (`value`, `label` or `children`, `icon`, `iconTrailing`, `tone`,
- `disabled`, `round`, `className`, `style`). `className` and `style` land on
- that option's individual `<a-tab>`, not on the strip. |
-| `orientation?` | 'horizontal' \| 'vertical' | 'horizontal' | Layout + arrow-key axis. Horizontal ellipsizes labels when tabs overflow (scroll
- is opt-in via CSS); vertical stacks them. |
-| `priority?` | 'primary' \| 'secondary' \| 'tertiary' | 'primary' | Visual priority. `primary` is the raised pill on a recessed track (the
- segmented-control look); `secondary` keeps that sizing but drops the track, marking
- the selected tab with a subtle active background fill; `tertiary` is a bottom-underline
- indicator under the selected tab (no track, no rest line). `tone` colors `secondary` +
- `tertiary`; `primary` stays neutral. |
-| `round?` | boolean \| number \| string | — | Fully-round the tabs and the sliding indicator (and the primary track
- well). Applies strip-wide; a single tab's `round` rounds just that tab. A
- `number` (px) or CSS length string sets a custom radius on the top-level
- track well only — the tab pills + indicator stay fully round. |
-| `size?` | 'small' \| 'medium' \| 'large' | 'medium' | Size — small 24px · medium 28px · large 32px tall, matching Button's scale (the tab's
- label leading runs a touch tighter, offset by 1px more block padding per side). |
-| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Tone applied to the selected indicator/label, or any literal CSS color for a
- one-off custom tone (derived in oklch). Named tones track light/dark. |
-| `value?` | string | — | Controlled active value — the tab `value` to mark selected (and, when a
- `<TabPanel value="…">` shares it, the panel to reveal). When set, you own
- selection: the strip renders exactly what this says, and a user pick only
- *requests* a change via `onStateChange` — apply it by updating this prop.
- Leave undefined (and use `defaultValue`) for uncontrolled. |
+| `options?` | TabOption[] | — | The tabs, as a data array (the strip's single source). Each entry is a `TabOption` (`value`, `label` or `children`, `icon`, `iconTrailing`, `tone`, `disabled`, `round`, `className`, `style`). `className` and `style` land on that option's individual `<a-tab>`, not on the strip. |
+| `orientation?` | 'horizontal' \| 'vertical' | 'horizontal' | Layout + arrow-key axis. Horizontal ellipsizes labels when tabs overflow (scroll is opt-in via CSS); vertical stacks them. |
+| `priority?` | 'primary' \| 'secondary' \| 'tertiary' | 'primary' | Visual priority. `primary` is the raised pill on a recessed track (the segmented-control look); `secondary` keeps that sizing but drops the track, marking the selected tab with a subtle active background fill; `tertiary` is a bottom-underline indicator under the selected tab (no track, no rest line). `tone` colors `secondary` + `tertiary`; `primary` stays neutral. |
+| `round?` | boolean \| number \| string | — | Fully-round the tabs and the sliding indicator (and the primary track well). Applies strip-wide; a single tab's `round` rounds just that tab. A `number` (px) or CSS length string sets a custom radius on the top-level track well only — the tab pills + indicator stay fully round. |
+| `size?` | 'small' \| 'medium' \| 'large' | 'medium' | Size — small 24px · medium 28px · large 32px tall, matching Button's scale (the tab's label leading runs a touch tighter, offset by 1px more block padding per side). |
+| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Tone applied to the selected indicator/label, or any literal CSS color for a one-off custom tone (derived in oklch). Named tones track light/dark. |
+| `value?` | string | — | Controlled active value — the tab `value` to mark selected (and, when a `<TabPanel value="…">` shares it, the panel to reveal). When set, you own selection: the strip renders exactly what this says, and a user pick only *requests* a change via `onStateChange` — apply it by updating this prop. Leave undefined (and use `defaultValue`) for uncontrolled. |
+
+## Tab option props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | string | — | This tab's identity — pairs it with the `<TabPanel value="…">` of the same value, and the value reported by `onStateChange` / `onChange`. Unique per strip. |
+| `children?` | ReactNode | — | Tab content when you need more than a string — used if `label` is omitted. |
+| `className?` | string | — | CSS class on the option's rendered row. |
+| `disabled?` | boolean | — | Disable just this tab — skipped by keyboard nav and dropped from the tab order (a disabled-but-selected tab stays reachable, per the ARIA pattern). |
+| `icon?` | IconShape | — | Leading icon shape, rendered before the label. |
+| `iconTrailing?` | IconShape | — | Trailing icon shape, rendered after the label. |
+| `label?` | ReactNode | — | Visible label. The string shorthand for the tab's content; for richer content pass `children` instead (`label` wins when both are set). |
+| `round?` | boolean | — | Fully-round just this tab's box. `<Tabs round>` rounds the whole strip (tabs + sliding indicator) instead. |
+| `style?` | CSSProperties | — | Inline styles on the option's rendered row. |
+| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | inherits the strip's `tone | Per-tab tone override, same vocabulary as `<Tabs tone>` — colors this one tab's label + icons (all priorities/modes, named or custom color) and, when it's the active tab, its indicator. For a **custom literal color** the sliding indicator can't adopt it (the shared moving element can't read a descendant's color), so a custom tone colors the label everywhere and the indicator only in `noslide`; the six **named** tones color both in every mode. Overrides the strip's `tone` for this tab. |
+| `tooltip?` | ReactNode | — | Tooltip for this tab — a string or any node — shown **only when one of the tab's ellipsizing label parts is truncated** (tabs ellipsize when the strip overflows), so clipped content reveals its full text on hover while a tab that fits shows nothing. Rendered as a `truncatedOnly` `<Tooltip>` anchored to the tab. For an always-visible tooltip or other custom trigger content, use `children` with your own `<Tooltip>` instead. |
+
+## TabPanel props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | string | — | Pairs this panel with the tab (`options` entry) of the same `value`. |
+| `children?` | ReactNode | — | Panel content — arbitrary React/Preact. |
+| `className?` | string | — | CSS class on the rendered `<a-tabpanel>`. |
+| `hideMode?` | 'display' \| 'visibility' | display | How this panel hides while inactive: `display` (default — removed from layout and the a11y tree) or `visibility` (keeps its layout box, to measure it or avoid reflow). Both stay mounted; to *not render* an inactive panel, render it conditionally off a controlled `value` (see the Tabs docs). |
+| `style?` | CSSProperties | — | Inline style on the rendered `<a-tabpanel>`. |
+
+## Web Component
 
 Use the web component directly when you are not using React or Preact and a native control does not fit.
 
@@ -386,6 +396,8 @@ Add `fill` to make horizontal tabs share the available width equally.
 </div>
 ```
 
+## Styling
+
 Reach for the props first: **`tone`**, **`size`**, **`priority`**. The focus ring is
 the global `--focus-ring` (see [Colors](../colors.md#focus-ring)).
 

package/docs/components/tag.md

@@ -109,41 +109,30 @@ proper names, identifiers, and case-sensitive IDs keep their shape (`GitHub`,
 not `GITHUB`). Pass `allcaps` for the uppercase treatment: at this small size
 all-caps reads as a label at a glance and keeps a uniform, scannable shape,
 which suits short status words where the exact case carries no meaning.
-Uppercase also tracks wider (0.08ch vs the default 0.02ch) and steps each size
-down 1px, since caps read larger than mixed case at the same size.
+Without a theme, both treatments use `0.1ch` tracking. Antune and Antithesis
+retain their font-specific `0.02ch` mixed-case and `0.08ch` uppercase tracking.
+All-caps steps each size down 1px, since caps read larger than mixed case at the
+same size.
 
 ```tsx
 <Tag icon="external-link" label="GitHub" value="v1.6.9" />
 <Tag allcaps label="Running" />
 ```
 
-### Props
+## Component props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `allcaps?` | boolean | — | Render in all-caps instead of the default normal (mixed) case
- (uppercase tracks wider than the default body-text letter-spacing). |
+| `allcaps?` | boolean | — | Render in all-caps instead of the default normal (mixed) case. |
 | `icon?` | IconShape | — | Leading icon shape. Sits flush before the label, scaled to the pill. |
 | `iconTrailing?` | IconShape | — | Trailing icon shape. Renders last, after the value. |
-| `label?` | string | — | A short "key" shown before the value. When paired with `value` it
- renders bold (weight 600), same color. On its own (no `value`) it's
- treated as the tag's primary text and keeps the default styling. |
-| `priority?` | 'primary' \| 'secondary' \| 'tertiary' | secondary | Emphasis level. `secondary` (the default) is the subtle alpha-tint
- fill; `primary` is a solid fill with white text; `tertiary` is a
- transparent outline. Omitting it (or passing `'secondary'`) renders
- the default and emits no DOM attribute. |
-| `size?` | 'small' \| 'medium' \| 'large' | medium | Size variant. `small` = 16px tall, `medium` = 20px, `large` = 24px
- (matching `Button`). Omit the attribute or pass `'medium'` for the
- default — both render identically and emit no DOM attribute. |
-| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | neutral | Semantic tone, or any literal CSS color (`'#ff1493'`, `'rebeccapurple'`)
- for a one-off custom tone. Each tone renders the secondary tag style:
- `--text-3-{tone}` text over an alpha tint of the tone's hue (fill + a
- slightly stronger hairline border). A custom color is tinted the same
- way, with the text deepened to a readable foreground. `'neutral'` (the
- default) is the gray tag — the same as omitting `tone`. |
-| `value?` | string | — | The tag's primary text — a status, count, version, duration, etc.
- Rendered in the default color and weight, with no divider from the
- label; the color + weight contrast does the separating. |
+| `label?` | string | — | A short "key" shown before the value. When paired with `value` it renders bold (weight 600), same color. On its own (no `value`) it's treated as the tag's primary text and keeps the default styling. |
+| `priority?` | 'primary' \| 'secondary' \| 'tertiary' | secondary | Emphasis level. `secondary` (the default) is the subtle alpha-tint fill; `primary` is a solid fill with white text; `tertiary` is a transparent outline. Omitting it (or passing `'secondary'`) renders the default and emits no DOM attribute. |
+| `size?` | 'small' \| 'medium' \| 'large' | medium | Size variant. `small` = 16px tall, `medium` = 20px, `large` = 24px (matching `Button`). Omit the attribute or pass `'medium'` for the default — both render identically and emit no DOM attribute. |
+| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | neutral | Semantic tone, or any literal CSS color (`'#ff1493'`, `'rebeccapurple'`) for a one-off custom tone. Each tone renders the secondary tag style: `--text-3-{tone}` text over an alpha tint of the tone's hue (fill + a slightly stronger hairline border). A custom color is tinted the same way, with the text deepened to a readable foreground. `'neutral'` (the default) is the gray tag — the same as omitting `tone`. |
+| `value?` | string | — | The tag's primary text — a status, count, version, duration, etc. Rendered in the default color and weight, with no divider from the label; the color + weight contrast does the separating. |
+
+## Web Component
 
 Use the web component directly when you are not using React or Preact and a native control does not fit.
 
@@ -157,6 +146,8 @@ Use `a-tag-label` for the key and `a-tag-value` for its value.
 </a-tag>
 ```
 
+## Styling
+
 Reach for the props first: **`tone`** sets the color (any CSS color for a custom
 tone — it derives the fill / border / text in oklch), **`priority`** the fill style,
 **`size`** the dimensions.

package/docs/components/text.md

@@ -97,34 +97,19 @@ more" and "Show less". `collapsible` takes effect only with `expandable`.
 <Text truncate={3} expandable collapsible>{longSentence}</Text>
 ```
 
-### Props
+## Component props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `collapsible?` | boolean | — | Let the reader collapse back after expanding: the chevron becomes a
- "Show more" / "Show less" toggle that stays visible while expanded.
- Only takes effect together with `expandable`. |
-| `expandable?` | boolean | — | Show a fade hint and chevron over the truncated text and let the user
- expand it by clicking the chevron region or pressing Enter while the
- chevron has keyboard focus. Only takes effect together with `truncate`.
- On its own, expanding is **one-way** — the control is removed once
- expanded; add `collapsible` for a two-way toggle. |
+| `collapsible?` | boolean | — | Let the reader collapse back after expanding: the chevron becomes a "Show more" / "Show less" toggle that stays visible while expanded. Only takes effect together with `expandable`. |
+| `expandable?` | boolean | — | Show a fade hint and chevron over the truncated text and let the user expand it by clicking the chevron region or pressing Enter while the chevron has keyboard focus. Only takes effect together with `truncate`. On its own, expanding is **one-way** — the control is removed once expanded; add `collapsible` for a two-way toggle. |
 | `inline?` | boolean | — | Render as inline-block instead of the default block element. |
-| `priority?` | 'primary' \| 'secondary' \| 'tertiary' \| 'quaternary' | secondary | Visual priority. Maps to text-1..text-4 (`primary` = text-1, the
- strongest). The default is `secondary` (text-2) — body text reads a
- step softer than the strongest foreground; pass `primary` for emphasis. |
+| `priority?` | 'primary' \| 'secondary' \| 'tertiary' \| 'quaternary' | secondary | Visual priority. Maps to text-1..text-4 (`primary` = text-1, the strongest). The default is `secondary` (text-2) — body text reads a step softer than the strongest foreground; pass `primary` for emphasis. |
 | `size?` | 'small' \| 'medium' \| 'large' | medium | Type scale. `small` = 13/16, `medium` = 15/20, `large` = 17/24. |
-| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | neutral | Color tint. `neutral` (the default) is the untinted `--text-{N}` scale; a
- named tone applies the matching `--text-{N}-{tone}` palette. Any literal CSS
- color (`'#ff1493'`, `'rebeccapurple'`) is a one-off custom tone — its hue is
- kept while lightness/chroma are pinned per priority in oklch. |
-| `truncate?` | boolean \| number | — | Truncate with a trailing ellipsis. `true` (or `1`) clamps to a
- single line; any integer ≥ 2 clamps to that many lines; `0` or a
- negative value means no truncation. A clipped, non-expandable JSX
- `Text` shows its text content in a tooltip by default. Nest a
- `<Tooltip>` to provide your own tooltip instead. Uses the
- `-webkit-line-clamp` technique, supported in all major browsers
- (Firefox 68+, Chrome, Safari, Edge). |
+| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | neutral | Color tint. `neutral` (the default) is the untinted `--text-{N}` scale; a named tone applies the matching `--text-{N}-{tone}` palette. Any literal CSS color (`'#ff1493'`, `'rebeccapurple'`) is a one-off custom tone — its hue is kept while lightness/chroma are pinned per priority in oklch. |
+| `truncate?` | boolean \| number | — | Truncate with a trailing ellipsis. `true` (or `1`) clamps to a single line; any integer ≥ 2 clamps to that many lines; `0` or a negative value means no truncation. A clipped, non-expandable JSX `Text` shows its text content in a tooltip by default. Nest a `<Tooltip>` to provide your own tooltip instead. Uses the `-webkit-line-clamp` technique, supported in all major browsers (Firefox 68+, Chrome, Safari, Edge). |
+
+## Web Component
 
 Use the web component directly when you are not using React or Preact and a native control does not fit.
 
@@ -136,6 +121,8 @@ Use `<a-text>` directly for a block that carries the text priority and tone.
 </a-text>
 ```
 
+## Styling
+
 Color comes from **`priority`** (the neutral text level) and **`tone`** (the tint);
 `size` and the type props set the rest. For a named tone, `Text` consumes the
 global **text role tokens** (`--text-1` … `--text-5`, the `-{tone}` tints,

package/docs/components/title.md

@@ -93,18 +93,15 @@ The four priorities are shown across every named tone at `level={3}`. Omit
 document outline or SEO needs heading elements; the reset applies the same type
 scale.
 
-### Props
+## Component props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `level?` | 1 \| 2 \| 3 \| 4 \| 5 \| 6 | 2 | Heading level, 1-6. Drives font-size, line-height, and vertical
- rhythm. Also surfaced to assistive tech via `aria-level`
- (h1 is typically reserved for the page title). |
+| `level?` | 1 \| 2 \| 3 \| 4 \| 5 \| 6 | 2 | Heading level, 1-6. Drives font-size, line-height, and vertical rhythm. Also surfaced to assistive tech via `aria-level` (h1 is typically reserved for the page title). |
 | `priority?` | 'primary' \| 'secondary' \| 'tertiary' \| 'quaternary' | primary | Visual priority. Maps to text-1..text-4 (`primary` = text-1). |
-| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | neutral | Color tint. `neutral` (the default) is the untinted `--text-{N}` scale; a
- named tone applies the matching `--text-{N}-{tone}` palette. Any literal CSS
- color (`'#ff1493'`, `'rebeccapurple'`) is a one-off custom tone — its hue is
- kept while lightness/chroma are pinned per priority in oklch. |
+| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | neutral | Color tint. `neutral` (the default) is the untinted `--text-{N}` scale; a named tone applies the matching `--text-{N}-{tone}` palette. Any literal CSS color (`'#ff1493'`, `'rebeccapurple'`) is a one-off custom tone — its hue is kept while lightness/chroma are pinned per priority in oklch. |
+
+## Web Component
 
 Use the web component directly when you are not using React or Preact and a native control does not fit.
 
@@ -116,6 +113,8 @@ Set the heading role and level when writing `<a-title>` directly.
 </a-title>
 ```
 
+## Styling
+
 `priority` selects a neutral text level. Named `tone`s use the matching global
 text tokens. A literal `tone` is stored in `--title-tone-source` and resolved
 into the four priority levels.

package/docs/components/toaster.md

@@ -222,13 +222,14 @@ Toaster.manager.add(() => <Banner tone="critical" message="Connection lost" />,
 })
 ```
 
-### Props
+## Component props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `label?` | string | 'Notifications' | Accessible label for the region landmark. |
-| `toaster?` | Toaster | — | The store this region renders. Omit to bind the default store driven by
- `Toaster.manager`; pass a `createToaster()` for an isolated region. |
+| `toaster?` | Toaster | — | The store this region renders. Omit to bind the default store driven by `Toaster.manager`; pass a `createToaster()` for an isolated region. |
+
+## Web Component
 
 Use the web component directly when you are not using React or Preact and a native control does not fit.
 
@@ -266,6 +267,8 @@ remove the toast from the DOM.
 </script>
 ```
 
+## Styling
+
 The region and item are plain custom elements — style them with ordinary CSS
 (`@layer anta`, so an un-layered rule of yours wins without `!important`).
 

package/docs/components/tooltip.md

@@ -117,32 +117,20 @@ arrives later works normally; a bubble whose content is cleared while it's open
 closes itself. Content that's a single icon or image (an element, no text) still
 shows.
 
-### Props
+## Component props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `children?` | ReactNode | — | Tooltip content. Renders anything — text, markup, an icon + text.
- Lives in the light DOM, so it's styleable with your own plain CSS. |
-| `delay?` | number | 300 | Show delay in milliseconds after hover / focus. Never use `0` — use
- ~`50` for a near-instant tooltip (0 has caused issues in practice). |
-| `follow?` | boolean | — | Follow the cursor instead of pinning under the anchor. The bubble is
- pinned (anchored beneath the target) by default; pass `follow` for the
- cursor-tracking behavior, which fades by distance as the cursor leaves. |
-| `interactive?` | boolean | — | Make the bubble hoverable and clickable — enables pointer events and
- keeps it open while the cursor is over it, so its content (links,
- buttons) can be interacted with. Always pinned (an interactive bubble
- can't follow the cursor, even with `follow`). |
-| `placement?` | 'top' \| 'bottom' | bottom | Which side of the anchor the bubble prefers. Auto-flips to the other
- side when there isn't room. |
-| `round?` | boolean \| number \| string | — | Round the bubble to a 20px radius (matching a round menu). Pass a `number`
- (px) or a CSS length string for a custom radius. |
-| `truncatedOnly?` | boolean | — | Only show when the target is actually truncated (its text overflows and is
- ellipsized); a label that fits gets no tooltip. The check is a UI-thread
- layout read, re-measured on each show. By default it measures every Anta
- ellipsizing label part inside the anchor, then the anchor itself —
- override with `truncatedSelector`. |
-| `truncatedSelector?` | string | — | CSS selector (resolved within the anchor) for the element or elements
- whose overflow decides whether a `truncatedOnly` tooltip shows. |
+| `children?` | ReactNode | — | Tooltip content. Renders anything — text, markup, an icon + text. Lives in the light DOM, so it's styleable with your own plain CSS. |
+| `delay?` | number | 300 | Show delay in milliseconds after hover / focus. Never use `0` — use ~`50` for a near-instant tooltip (0 has caused issues in practice). |
+| `follow?` | boolean | — | Follow the cursor instead of pinning under the anchor. The bubble is pinned (anchored beneath the target) by default; pass `follow` for the cursor-tracking behavior, which fades by distance as the cursor leaves. |
+| `interactive?` | boolean | — | Make the bubble hoverable and clickable — enables pointer events and keeps it open while the cursor is over it, so its content (links, buttons) can be interacted with. Always pinned (an interactive bubble can't follow the cursor, even with `follow`). |
+| `placement?` | 'top' \| 'bottom' | bottom | Which side of the anchor the bubble prefers. Auto-flips to the other side when there isn't room. |
+| `round?` | boolean \| number \| string | — | Round the bubble to a 20px radius (matching a round menu). Pass a `number` (px) or a CSS length string for a custom radius. |
+| `truncatedOnly?` | boolean | — | Only show when the target is actually truncated (its text overflows and is ellipsized); a label that fits gets no tooltip. The check is a UI-thread layout read, re-measured on each show. By default it measures every Anta ellipsizing label part inside the anchor, then the anchor itself — override with `truncatedSelector`. |
+| `truncatedSelector?` | string | — | CSS selector (resolved within the anchor) for the element or elements whose overflow decides whether a `truncatedOnly` tooltip shows. |
+
+## Web Component
 
 Use the web component directly when you are not using React or Preact and a native control does not fit.
 
@@ -155,6 +143,8 @@ Place `<a-tooltip>` inside the element it describes.
 </a-button>
 ```
 
+## Styling
+
 The bubble lives in shadow DOM and is exposed as a single **part** — style the box
 (background, frost, shadow, radius, padding, a border) with `::part(bubble)`. Its
 *content* is slotted light DOM with a **normalized text baseline** (Anta body

package/docs/index.md

@@ -41,7 +41,6 @@ Anta is designed for a clean DOM. Prefer the props and attributes exposed by eac
 - [Select](./components/select.md)
 - [SelectFaceted](./components/select-faceted.md)
 
-- [Box](./components/box.md)
 - [Banner](./components/banner.md)
 - [Card](./components/card.md)
 - [Dialog](./components/dialog.md)
@@ -49,6 +48,9 @@ Anta is designed for a clean DOM. Prefer the props and attributes exposed by eac
 - [Expander](./components/expander.md)
 - [Menu](./components/menu.md)
 
+- [Box](./components/box.md)
+- [Capture](./components/capture.md)
+
 ## Packages
 
 - [Table](./packages/table.md)

package/docs/install-config.md

@@ -15,7 +15,7 @@ of a floating tag such as `"latest"`.
 import '@antadesign/anta/tokens.css'  // CSS custom properties
 import '@antadesign/anta/reset.css'   // reset and typography defaults
 import '@antadesign/anta/elements'    // registers <a-*> elements
-import '@antadesign/anta/theme-anta.css' // optional hand-tuned reference palette
+import '@antadesign/anta/theme-antune.css' // optional Antune theme
 import { Progress } from '@antadesign/anta'
 
 <Progress value={42} label="Uploaded" hint="3 of 7" />
@@ -43,18 +43,19 @@ recommended; the reference theme is optional.
 
 | Import | Provides | Skip if… |
 |---|---|---|
-| `@antadesign/anta/tokens.css` | Six seed tokens, derived role scales (`--bg-1…5`, `--text-1…5`, `--border-1…5`), `.dark`, the 15px root size, and layer order. Override a seed to reskin its tone. | You provide those variables. |
+| `@antadesign/anta/tokens.css` | Six seed tokens, derived role scales (`--bg-1…5`, `--text-1…5`, `--border-1…5`), `.dark` and its `color-scheme`, the 15px root size, and layer order. Override a seed to reskin its tone. | You provide those variables. |
 | `@antadesign/anta/reset.css` | A small reset plus Anta's focus, heading, list, and link typography in `@layer anta.reset`. | You use another reset and typography. |
 | `@antadesign/anta/elements` | Registers every `<a-*>` element and its CSS. Per-element entries register one; see [Registering elements](#registering-elements). | You render only on the server or register elements individually. |
 | `@antadesign/anta` | Typed React/Preact wrappers such as `Progress`, `Text`, and `Icon`. | You write `<a-*>` elements directly. |
 | `@antadesign/anta/bundle.css` | One minified stylesheet containing tokens, reset, element, and JSX-wrapper styles. | You want granular CSS imports. |
 | `@antadesign/anta/bundle` | One minified ESM runtime that registers every `<a-*>` element and re-exports the JSX API. | You want granular JS imports. |
-| `@antadesign/anta/theme-anta.css` *(optional)* | The hand-tuned reference palette. Import last to replace the seed-derived default. | You want the seed-derived or your own palette. |
+| `@antadesign/anta/theme-antune.css` *(optional)* | Antune, the hand-tuned reference palette. Import last to replace the seed-derived default. | You want the seed-derived or your own palette. |
+| `@antadesign/anta/theme-antithesis.css` *(optional)* | Antithesis: warm color seeds, pill buttons, square text fields, and `1px` tag corners. Import as the only theme. | You want Antune, the seed-derived palette, or your own theme. |
 
 Load `tokens.css` before element CSS. Elements read its variables; without it,
 they render unstyled.
 
-To use the optional reference palette, import `theme-anta.css` after the element
+To use the optional reference palette, import `theme-antune.css` after the element
 registration import. It ships in `@antadesign/anta`; omit it to keep the
 seed-derived default palette or provide your own theme.
 
@@ -93,6 +94,30 @@ Token custom properties stay unlayered so they apply everywhere.
 > `@layer base { … }`; `reset.css` already applies the same universal reset in
 > `@layer anta.reset`.
 
+## AI setup
+
+Anta includes version-matched Markdown documentation in its npm package.
+Append this section to your application's agent instruction file, such as
+`AGENTS.md`, `CLAUDE.md`, or your tool's equivalent. Keep existing project rules:
+
+```md
+## Anta
+
+Before Anta UI work, read
+`node_modules/@antadesign/anta/docs/index.md`
+and the pages relevant to the task.
+Verify component names, imports, props, and event signatures against the
+installed documentation and TypeScript declarations. Do not infer Anta APIs
+from similarly named components in other libraries.
+```
+
+The path is relative to the application directory where Anta is installed.
+Adjust it for your workspace or package-manager layout. Installing Anta does
+not modify your agent configuration.
+
+For tools without local file access, provide the [web documentation index](https://anta.design/llms.txt)
+and your installed Anta version. Web documentation may describe a newer release.
+
 ## Registering elements
 
 JSX wrappers render `<a-*>` tags. Register their classes before those tags reach
@@ -235,10 +260,15 @@ Use `dark` or `light` on another ancestor to scope its color scheme and palette.
 
 ## Fonts
 
-Anta is designed for a customized TT Interphases Pro, but ships no font binaries. Components use `--sans-serif` and `--monospace` with system fallbacks. `tokens.css` sets `1rem` to 15px.
+Without an optional theme, `tokens.css` defines system stacks in `--sans-serif`,
+`--serif`, and `--monospace`. Reference themes register hosted fonts and replace
+some of those same variables. Components and theme rules decide which stack to
+use. Theme-free components do not force font-specific stylistic sets or
+variable-font axes. `tokens.css` also sets `1rem` to 15px.
 
-Register application-owned fonts, then override the font variables. This example
-uses separate Roman and Italic variable files:
+Register application-owned fonts and redefine the variables in CSS loaded after
+the Anta styles and optional theme. This example uses separate Roman and Italic
+variable files:
 
 ```css
 @font-face {
@@ -257,11 +287,15 @@ uses separate Roman and Italic variable files:
 
 :root {
   --sans-serif: "App Sans", sans-serif;
+  --serif: Georgia, serif;
   --monospace: ui-monospace, monospace;
 }
 ```
 
-Anta's semantic italics (`em`, `i`, `var`, and `dt`) select the Italic face.
+Place this application stylesheet after `theme-antune.css` or
+`theme-antithesis.css`, not before it. When all stylesheets are in the document
+head, the override applies before the first paint. Anta's semantic italics
+(`em`, `i`, `var`, and `dt`) select the Italic face.
 
 ### Variable slant