@antadesign/anta 0.3.17 → 0.3.19

package/docs/components/card.md

@@ -0,0 +1,322 @@
+# Card
+
+A surface container: a bordered, toned box that groups related content. The
+`Card` JSX wrapper renders an `<a-card>`, which lays out an optional full-bleed
+`media` region plus a `header` / body / `footer` stack. Pass `href` to turn the
+whole card into a link.
+
+A card stylizes only its own surface, never its content's typography. Pass
+`header` and body (`children`) as strings and the wrapper wraps them in a
+`<Title>` and a `<Text>` that follow the card's `tone` and `size`; pass your own
+nodes to take over. It shares the `tone` / `priority` / `size` vocabulary with the
+rest of Anta.
+
+## Anatomy
+
+A card is three stacked sections — `header`, body (`children`), `footer` — plus an
+optional full-bleed `media` region. Each is optional and an empty one reserves no
+space. Spacing comes from one `--card-padding`: the outer inset and the body→footer
+gap are a full `--card-padding`, and the header sits a half-step closer to its body
+(`--card-padding / 2`). A string `header` becomes a `<Title>` and a string body a
+`<Text>`; pass your own node (`<Title>`, `<Text>`, a layout) to take over. An
+optional `subtitle` renders under the title as smaller text (`<Text size="small">`). There's
+no dedicated actions slot: lay out header controls (a button, a tag) inside the
+`header` itself.
+
+```tsx
+<Card
+  media={<img src="/hero.jpg" alt="" />}
+  icon="book-open"        {/* a string shape → an <Icon> in a circular chip */}
+  header="Card title"
+  subtitle="A short supporting subtitle"
+  footer={<><Button priority="secondary" label="Launch" /><Button priority="tertiary" label="Edit" /></>}
+>
+  The body sits under the header. Every section is optional.
+</Card>
+
+{/* mediaPosition moves the media to another edge */}
+<Card
+  media={<img src="/hero.jpg" alt="" />}
+  mediaPosition="left"
+  header="Card title"
+  footer={<><Button priority="secondary" label="Launch" /><Button priority="tertiary" label="Edit" /></>}
+>
+  The same four zones, with the media bleeding to the left edge instead of the top.
+</Card>
+```
+
+## Priority
+
+`priority` sets the surface. `primary` (the default) is a clean sheet — `bg-1`
+in light mode, `bg-4` in dark (and a toned card's cleanest tint: `bg-2-{tone}`
+light, `bg-4-{tone}` dark); `secondary` is a subtle fill (`bg-2`, or the deeper
+tint for a toned card); `tertiary` is a frosted panel: the `primary` surface
+made semi-transparent with a backdrop blur, so it reads over busy, colored, or
+image backgrounds (the blur shows where there's detail behind). All three carry
+a hairline ring — `border-4` for a neutral card, or the tone's `border-4-{tone}`
+when toned (stepping to `border-3` on hover).
+
+```tsx
+<Card header="Primary (default)">…</Card>              {/* primary is the default */}
+<Card priority="secondary" header="Secondary">…</Card>
+<Card priority="tertiary" header="Tertiary">…</Card>
+```
+
+## Tones
+
+A semantic `tone` tints the surface, border, and text. The set matches the rest of
+Anta: `neutral` (the default) plus `brand`, `info`, `success`, `warning`, and
+`critical`. Color comes from the theme tokens, so every tone tracks light and dark
+mode. A toned card is how you build a **banner** or **callout** — a filled card
+with an icon and a message (add a `footer` for an action):
+
+```tsx
+{/* A string `icon` gets the circular chip; pass a bare <Icon> node for a plain
+    tinted glyph, as these banners do. */}
+<Card tone="info" priority="primary" icon={<Icon shape="info" />} header="Heads up">…</Card>
+<Card tone="success" priority="primary" icon={<Icon shape="circle-check" />} header="All checks passed">…</Card>
+<Card tone="warning" priority="primary" icon={<Icon shape="warning-triangle" />} header="Approaching quota">…</Card>
+<Card tone="critical" priority="primary" icon={<Icon shape="warning-diamond" />} header="Deployment failed">…</Card>
+```
+
+`tone` also accepts **any literal CSS color** for a one-off tint — the hue is kept
+while lightness and chroma are pinned to the named-tone curve (and re-tuned for
+dark mode), the same mechanism as `Button` / `Expander` / `Tag`. The surface,
+border, and the `<Title>` / `<Text>` the wrapper adds all derive from the color —
+`Title` and `Text` take a custom tone too, so a string `header` / body tints to
+match:
+
+```tsx
+<Card tone="#ff1493" priority="primary" header="Magenta">…</Card>
+<Card tone="rebeccapurple" priority="primary" header="Purple">…</Card>
+<Card tone="#0d9488" priority="primary" header="Teal">…</Card>
+```
+
+## Size
+
+`size` scales the padding, the auto-wrapped body text, and the icon chip —
+`small`, `medium` (the default), `large`.
+
+```tsx
+<Card size="small" header="Small">…</Card>
+<Card header="Medium (default)">…</Card>      {/* medium is the default */}
+<Card size="large" header="Large">…</Card>
+```
+
+## Round
+
+`round` softens the corners. A `number` (px) or CSS length sets a custom radius —
+the usual choice for a card (`round="0"` squares them); bare `round` goes fully
+round (`999px`, clamped to the box). Omit it for the default (`--card-radius`, 8px).
+
+```tsx
+<Card round={16} header="Custom radius">…</Card>
+<Card round="0" header="Square">…</Card>
+```
+
+## Header controls
+
+There's no dedicated actions slot. For a control at the top-right of the header — a
+"more" button, a tag — pass a laid-out node as the `header` and put the title and
+the control in it yourself (a flex row). You own the layout, so the title and
+control sit exactly where you place them.
+
+```tsx
+<Card
+  header={
+    <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between', gap: 8 }}>
+      <Title level={4}>Production database</Title>
+      <Button size="small" priority="tertiary" icon="more" aria-label="More" />
+    </div>
+  }
+>
+  Region us-east-1 · 4 vCPU · 16 GB
+</Card>
+```
+
+## Footer
+
+`footer` is a **left-aligned** row (it wraps under pressure) — the opposite of
+`Dialog`'s right-aligned footer, since a card reads as left-aligned content rather
+than a decision surface. Pass several buttons as a fragment.
+
+```tsx
+<Card
+  header="Invite teammates"
+  footer={<><Button priority="primary" size="small" label="Send invites" /><Button size="small" label="Copy link" /></>}
+>
+  <Text>They'll get access to this project and its test runs.</Text>
+</Card>
+```
+
+## Media
+
+Pass `media` for a full-bleed image or illustration — it escapes the card padding
+and clips to the corners. `mediaPosition` places it on the `top` (the default),
+`bottom`, `left`, or `right` edge.
+
+**Top** (default)
+
+**Left**
+
+```tsx
+<Card media={<img src="/hero.jpg" alt="" />} header="Top media">…</Card>          {/* top is the default */}
+<Card media={<img src="/hero.jpg" alt="" />} mediaPosition="left" header="Left media">…</Card>
+{/* mediaPosition also takes "bottom" and "right" */}
+```
+
+## Link card
+
+Give a card an `href` and the whole thing becomes a link — a single focusable
+anchor, keyboard-activatable, with the `hover` lift and inset focus ring. The
+accessible name comes from the header (falling back to the body, then the URL), so
+a screen reader announces one concise link instead of the whole card's text. A
+link card is display content: keep interactive controls (buttons, nested links)
+out of it — its text is non-selectable and the whole surface navigates.
+
+```tsx
+<Card
+  href="/docs/ci"
+  header={<><Icon shape="book-open" /> CI integration guide</>}
+>
+  Wire Antithesis into your pipeline in a few minutes.
+</Card>
+```
+
+Set `target` / `rel` for a new-tab link (`target="_blank" rel="noopener"`), or
+`aria-label` to override the derived link name.
+
+## Selected
+
+`selected` draws an inset ring in the tone color — for choice cards, plan pickers,
+and selected list items.
+
+```tsx
+<Card selected tone="brand" priority="primary" header="Team plan">…</Card>
+<Card header="Free plan">…</Card>
+```
+
+## Loading
+
+`loading` dims the card with a skeleton pulse and sets `aria-busy`. On a link card
+it also blocks navigation until the load resolves.
+
+```tsx
+<Card loading header="Loading…">
+  <Text>Content is being fetched.</Text>
+</Card>
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children?` | ReactNode | — | The card body. A string is wrapped in a `<Text>` at secondary priority,
+ following the card's `tone` and `size`; pass your own nodes to take over. |
+| `footer?` | ReactNode | — | Footer content, usually action buttons. Rendered as a **left-aligned** row
+ (wraps under pressure) — the opposite of `Dialog`'s right-aligned footer. |
+| `header?` | ReactNode | — | Header content, in the top zone. A string is wrapped in a `<Title>` — a real
+ heading in the document outline, tinted to match `tone`, at a level that
+ tracks `size` (small → 5, medium → 4, large → 3). Pass your own node
+ (`<Title level={2}>`, an `<h2>`) for a different level or styling. Omit for
+ no header. |
+| `href?` | string | — | Turn the whole card into a link. The card renders a focusable anchor and its
+ accessible name comes from `header` → body → this URL (override with
+ `aria-label`). A link card is display content — don't nest interactive
+ controls inside it. |
+| `icon?` | (string & {}) \| string \| number \| bigint \| boolean \| ReactElement \| Iterable \| ReactPortal \| Promise \| null | — | Leading visual for the header, laid out to the left of the `header` /
+ `subtitle` as one aligned row (so it doesn't sit inline in the title, where it
+ mis-aligns). A **string** is an icon shape, rendered as an `<Icon>` inside a
+ circular chip (sized per the card via `--card-icon-size`); pass an `<img>`,
+ initials (`<Text>`), or any node to use it as-is. Omit for none. |
+| `loading?` | boolean | — | Loading state — dims the card with a skeleton pulse, sets `aria-busy`, and (in
+ link mode) blocks navigation. |
+| `media?` | ReactNode | — | Media (image, illustration) rendered full-bleed to the card edge, clipped to
+ its corners. Position it with `mediaPosition`. |
+| `mediaPosition?` | 'top' \| 'bottom' \| 'left' \| 'right' | 'top' | Which edge the `media` bleeds to. |
+| `ping?` | string | — | Space-separated URLs the browser pings on navigation (only with `href`). |
+| `priority?` | 'primary' \| 'secondary' \| 'tertiary' | 'primary' | Surface emphasis. `primary` (the default) is a clean sheet; `secondary` is a
+ subtle fill; `tertiary` is a frosted, semi-transparent panel with a backdrop
+ blur. |
+| `rel?` | string | — | Anchor rel (only with `href`). |
+| `round?` | boolean \| number \| string | — | Fully-round corners (`border-radius: 999px`, clamped to the box). Pass a
+ `number` (px) or a CSS length string (`'1rem'`) for a custom radius. Omit for
+ the default `--card-radius`. |
+| `selected?` | boolean | — | Selected / chosen state — draws an inset ring in the tone color, for
+ choice-card / plan-picker patterns. |
+| `size?` | 'small' \| 'medium' \| 'large' | 'medium' | Size variant — scales the padding. |
+| `subtitle?` | ReactNode | — | A secondary line under the header title, rendered as smaller text
+ (`<Text size="small">`) in the heading section. Tinted to match `tone`, like
+ the title. Omit for no subtitle. |
+| `target?` | string | — | Anchor target (only with `href`). |
+| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Semantic tone, or any literal CSS color (`'#ff1493'`, `'rebeccapurple'`) for
+ a one-off custom tone. Named tones re-point the surface + text; a custom
+ color keeps its hue while lightness/chroma are pinned. `'neutral'` (the
+ default) is the same as omitting it. |
+
+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.
+
+Slots hold media, header, and footer content. Unslotted content is the card body.
+
+```html
+<a-card>
+  <a-title slot="header" level="5" role="heading" aria-level="5">Release notes</a-title>
+  <a-text>Everything without a slot attribute becomes the body.</a-text>
+  <a-button slot="footer" role="button" tabindex="0" size="small">
+    <a-button-label>Read more</a-button-label>
+  </a-button>
+</a-card>
+```
+
+Reach for the props first: **`tone`** sets the color (any CSS color for a custom
+tone — it derives the surface in oklch), **`priority`** the fill, **`size`** the
+padding. The one custom-color knob worth keeping is **`--card-tone-source`** (the
+color a custom `tone` derives from — set it to drive the palette from your own
+variable). The corner radius is **`--card-radius`**.
+
+```tsx
+<Card tone="#e0457b" header="Custom" />
+```
+
+**Header heading level.** A string `header` becomes a `<Title>` whose level tracks
+`size` — small → 5, medium → 4, large → 3 — a real heading in the document outline.
+For a different level or your own styling, pass a `<Title level={n}>` (or an
+`<h2>`–`<h6>`) as the header; the card zeroes its top margin so it spaces the same
+either way:
+
+```tsx
+<Card header={<Title level={2}>Heading semantics</Title>}>
+  The header is a level-2 heading node, in the page outline.
+</Card>
+```
+
+For everything else, `<a-card>` exposes shadow **parts** —
+`::part(container)` (the box / anchor), `::part(media)`, `::part(content)`,
+`::part(header)` (the icon + text zone), `::part(icon)`, `::part(title)` (the
+title / subtitle text column), `::part(body)`, `::part(footer)` — which you style
+directly. Each section carries its own `--card-padding`, so a divider on
+`::part(header)` reads as a true section rule.
+
+Each example keeps its CSS in a `<style>` **inside** its own preview, targeting a
+demo class on that preview's card — so the rule you read is literally in the
+preview's DOM, next to the element it styles. In your app, swap the demo class for
+your own selector.
+
+**Scroll a capped body.** The card never scrolls, and the body doesn't by default.
+When you cap the card's height and want the body to scroll instead of the card
+growing, that's one line on `::part(body)`:
+
+```css
+/* cap the card's height, then let the body scroll */
+a-card.scrollable { height: 160px; }
+a-card.scrollable::part(body) { overflow: auto; }
+```
+
+**Separate the header** with a divider by styling `::part(header)`:
+
+```css
+a-card.divided::part(header) {
+  padding-bottom: 8px;
+  border-bottom: 1px solid var(--border-5);
+}
+```

package/docs/components/checkbox.md

@@ -0,0 +1,297 @@
+# Checkbox
+
+Checkboxes let users select one or more items from a set, or toggle an option on or off. Use them for multiple independent choices; for a single immediate setting, use a switch instead.
+
+The `Checkbox` wrapper renders an `<a-checkbox>` element that manages its own state. It works both controlled and uncontrolled with `checked` / `defaultChecked` (boolean or `'indeterminate'`) and `onStateChange` for updates.
+
+## Tone
+
+`tone` colours the **mark** — the checked-box fill and, for a tinted tone, the
+unselected box border (a light shade of the fill that darkens on hover and active,
+like the neutral border; `neutral` keeps a grey border). The label and hint stay
+neutral. Six named tones (`neutral` default), or pass any CSS color for a custom tone.
+
+```tsx
+<Checkbox defaultChecked tone="neutral">Neutral</Checkbox>
+<Checkbox defaultChecked tone="brand">Brand</Checkbox>
+<Checkbox defaultChecked tone="critical">Critical</Checkbox>
+<Checkbox defaultChecked tone="mediumaquamarine">Custom color</Checkbox>
+```
+
+## Selected-only tone
+
+`toneSelected` tones the **checked mark only** — the empty box stays neutral grey
+until it's checked. Reach for it instead of `tone` when a resting tinted border would
+read as a validation error. Same value set as `tone`.
+
+```tsx
+<Checkbox toneSelected="brand">Off stays neutral</Checkbox>
+<Checkbox defaultChecked toneSelected="critical">Checked mark tinted</Checkbox>
+```
+
+## Colouring the text
+
+There's no text-tone prop. To tint the **label**, set `color` on the checkbox with a
+theme-aware `--text-N-{tone}` token (the label inherits it); for the **hint**, add a
+`color` rule on the `a-checkbox-hint` child. Pair either with `tone` / `toneSelected`
+to tint the whole control.
+
+```css
+/* Mark via the prop, text via a plain color rule — the label inherits the host
+   colour, the hint is targeted directly. The class is just for the demo — swap
+   your own selector. */
+a-checkbox.toned-text { color: var(--text-1-critical); }
+a-checkbox.toned-text a-checkbox-hint { color: var(--text-3-critical); }
+```
+
+## Size
+
+Three sizes scale the box **and** the label + hint type together: `small`
+(14px box / 13px label), `medium` (16px / 15px, the default), and `large`
+(18px / 17px).
+
+```tsx
+<Checkbox defaultChecked size="small">Small</Checkbox>
+<Checkbox defaultChecked>Medium</Checkbox>
+<Checkbox defaultChecked size="large">Large</Checkbox>
+```
+
+## Label & hint
+
+Pass the label as `children` or the `label` prop. Add a `hint` for a secondary line beneath. For a label-less checkbox (e.g. a table "select all"), pass `aria-label`.
+
+```tsx
+<Checkbox label="Email notifications" hint="Weekly digest, never marketing." />
+<Checkbox aria-label="Select all rows" />
+```
+
+## States
+
+Checkboxes are unchecked, checked, or indeterminate (for partial selection in groups).
+
+```tsx
+<Checkbox defaultChecked label="Checked" />
+<Checkbox label="Unchecked" />
+<Checkbox defaultChecked="indeterminate" label="Indeterminate" />
+```
+
+## Disabled
+
+The `disabled` attribute dims the checkbox and removes it from the tab order.
+
+```tsx
+<Checkbox disabled label="Disabled" />
+<Checkbox disabled defaultChecked label="Disabled checked" />
+```
+
+## Controlled
+
+Uncontrolled by default: pass `defaultChecked` and read the value from `onStateChange` or at form-submit. Make it controlled with `checked` and `onStateChange` to drive it from your store.
+
+```tsx
+const [agreed, setAgreed] = useState(false)
+
+<Checkbox
+  checked={agreed}
+  onStateChange={(_e, { next }) => setAgreed(next as boolean)}
+>
+  I agree
+</Checkbox>
+```
+
+`onStateChange` fires before the element applies, with signature `(event, { next, prev })`. Call `event.preventDefault()` to veto the change. A controlled checkbox with no `onStateChange` is read-only.
+
+## Events
+
+Three callbacks, in firing order:
+
+| Callback | When | Cancelable | Payload |
+|---|---|---|---|
+| `onStateChange(e, { next, prev })` | **before** the toggle applies | ✅ `e.preventDefault()` vetoes | next / prev state |
+| `onChange(e)` | **after** it applies | — | native `change` event |
+| `onValueChange(e, attrs)` | **after** it applies | — | `{ checked, indeterminate, name, value }` |
+
+Reach for **`onStateChange`** only to intercept or veto (or to drive a controlled
+checkbox). For the everyday "react to the new value", use **`onValueChange`** — it
+hands you the value without touching `event.target`. `onChange` is the plain
+native hook. (In controlled mode `onChange`/`onValueChange` fire once you've updated
+`checked`.) `onFocus` / `onBlur` work too — the host is the focusable element.
+
+Checkbox has `onStateChange` (and `Input` doesn't) because its state is
+**discrete** — `checked · unchecked · indeterminate` — so a transition can be
+vetoed *before* it applies. A text field's value is free-form, with no discrete
+state to model or veto, so `Input` (and the composed `Select`) expose only the
+`onValueChange` half. The `onValueChange` shape is identical across all of them.
+
+```tsx
+<Checkbox onValueChange={(_e, { checked }) => save(checked)}>Subscribe</Checkbox>
+```
+
+## Indeterminate
+
+Set `checked="indeterminate"` to show the "mixed" state (minus glyph). Common for a parent checkbox whose state derives from its children: all on = checked, all off = unchecked, mixed = indeterminate.
+
+```tsx
+function ParentChild() {
+  const [on, setOn] = useState([true, false])
+  return (
+    <>
+      <Checkbox
+        checked={on[0] && on[1] ? true : on[0] || on[1] ? 'indeterminate' : false}
+        onStateChange={(_e, { next }) => setOn([next === true, next === true])}
+      >
+        Parent
+      </Checkbox>
+      <div style={{ marginInlineStart: 24 }}>
+        <Checkbox
+          checked={on[0]}
+          onStateChange={(_e, { next }) => setOn([next === true, on[1]])}
+        >
+          Child 1
+        </Checkbox>
+        <Checkbox
+          checked={on[1]}
+          onStateChange={(_e, { next }) => setOn([on[0], next === true])}
+        >
+          Child 2
+        </Checkbox>
+      </div>
+    </>
+  )
+}
+```
+
+## Accessibility
+
+The wrapper sets `role="checkbox"` and `aria-checked` (`"true"` / `"false"` / `"mixed"`), and derives the accessible name from `label` or `children`. For a label-less checkbox, pass `aria-label`.
+
+Space toggles the checkbox. Follows the [WAI-ARIA checkbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/).
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `checked?` | CheckboxValue | — | Controlled checked state. When provided the checkbox is controlled — it
+ renders exactly this and never self-applies; `onStateChange` is a *request*
+ the consumer accepts by updating this prop. Use `defaultChecked` for an
+ uncontrolled checkbox. `'indeterminate'` shows the minus glyph and takes
+ visual precedence; clicking it requests `true`. |
+| `defaultChecked?` | CheckboxValue | false | Initial checked state for an uncontrolled checkbox. Read once; later
+ changes ignored (the element then owns the state). |
+| `disabled?` | boolean | — | Disable the checkbox (no interaction, dropped from the tab order). |
+| `hint?` | ReactNode | — | Secondary text rendered under the label — explanatory copy, like
+ Input's hint. Not part of the accessible name. |
+| `label?` | string | — | Visible label — the *value* of the checkbox (clicked along with the box).
+ Convenience for the common single-string case; for richer content (markup,
+ a link, an info icon) use `children`. When both are supplied, `label`
+ renders first. Required unless `children` or `aria-label` is provided
+ (a `role="checkbox"` takes its name from the author, not the markup). |
+| `name?` | string | — | Form field name. Inside a `<form>` the checkbox submits under this name,
+ contributing `value` when checked — like a native checkbox. |
+| `onChange?` | (event) => void | — | Fired *after* the checked state changes — a native `change` event (the
+ post-apply counterpart to `onStateChange`). Not cancelable. For a controlled
+ checkbox this fires once you've updated `checked`. |
+| `onStateChange?` | (event, detail) => void | — | Fired on click / Space *before* the element applies any change. Event-first
+ so `event.preventDefault()` is the synchronous veto (uncontrolled mode);
+ `detail` carries `{ next, prev }`. In controlled mode the element never
+ self-applies — answer by updating `checked`, reject by doing nothing. |
+| `onValueChange?` | (event, attrs) => void | — | Like `onChange`, but with a `{ checked, indeterminate, name, value }` snapshot
+ as the 2nd argument — the ergonomic "just give me the new value" callback
+ (mirrors `Input`'s `onValueChange`). |
+| `round?` | boolean \| number \| string | — | Round the checkbox mark to a circle (`border-radius: 999px` on the box). Pass
+ a `number` (px) or a CSS length string for a rounded-square mark instead. |
+| `size?` | 'small' \| 'medium' \| 'large' | 'medium' | Size variant. small=14px, medium=16px, large=18px box. |
+| `tone?` | 'brand' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Colour of the **mark** in every state — the checked-box fill *and* the
+ unselected box border. A named tone or any literal CSS color (`'#ff1493'`,
+ `'rebeccapurple'`) for a one-off custom tone. Named tones track light/dark mode
+ automatically; a custom colour keeps its hue + chroma and pins lightness to the
+ fill curve. Use `toneSelected` instead to tone only the checked mark and leave
+ the empty box neutral. The label + hint stay neutral — recolour them in plain
+ CSS via the theme-aware `--text-N-{tone}` tokens. |
+| `toneSelected?` | 'brand' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Like `tone`, but coloured onto the **checked mark only** — the empty box stays
+ neutral grey until it's checked. Prefer this over `tone` when a resting tinted
+ border would read as a validation state. Same value set as `tone`; if both are
+ set, `tone` governs the off-state border and `toneSelected` the checked fill. |
+| `value?` | string | "on" | Value submitted with the form when checked — like a native checkbox. |
+
+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.
+
+The focusable host carries the state. Label and hint are light-DOM children.
+
+```html
+<a-checkbox role="checkbox" tabindex="0" name="updates" default-state="checked">
+  <a-checkbox-label>Email updates</a-checkbox-label>
+  <a-checkbox-hint>Product and security notices.</a-checkbox-hint>
+</a-checkbox>
+```
+
+### Native HTML checkbox
+
+For a standard HTML form, add `data-anta` to a native checkbox. It keeps the
+browser's label behavior, checked and indeterminate states, and form submission
+while using Anta's control surface.
+
+`size`, `tone`, `tone-selected`, and `round` use the matching Checkbox visual
+treatments.
+
+```html
+<div style="display: grid; gap: 8px">
+  <label><input data-anta type="checkbox" name="updates" size="small" tone="brand"> Product updates</label>
+  <label><input data-anta type="checkbox" name="security" tone-selected="success" checked> Security notices</label>
+  <label><input data-anta type="checkbox" name="billing" size="large" round tone="warning" checked> Billing alerts</label>
+</div>
+```
+
+Reach for the props first: **`tone`** colours the mark in every state,
+**`toneSelected`** only the checked mark (any CSS colour for a custom tone — it
+derives the full rest/hover/active curve in oklch), **`size`** the dimensions + type.
+To tint the label + hint, add a `color` rule (on the host for the label, on
+`a-checkbox-hint` for the hint) with the `--text-N-{tone}` tokens — there's no
+text-tone prop. The focus ring is the global
+[`--focus-ring`](../colors.md#focus-ring).
+
+```tsx
+<Checkbox tone="#e0457b" defaultChecked>Custom colour</Checkbox>
+```
+
+For anything else, `<a-checkbox>` is light-DOM — the **box is `::before`**, the
+**check/minus glyph is `::after`** (a masked SVG — swap `--checkbox-mask-check` for a
+custom mark), the label/hint are the `a-checkbox-label` / `a-checkbox-hint` children.
+Target them with plain CSS, **per state** (an un-layered rule beats `@layer anta`
+without `!important`). The classes below are just for the demos:
+
+```css
+/* Outlined — an unfilled box: the checked box keeps its background and paints the
+   border + checkmark in the tone colour (light-dark() tunes both themes at once). */
+a-checkbox.outlined:state(checked)::before {
+  background: var(--checkbox-bg);
+  border-color: light-dark(#5f4bc3, #7460d7);
+}
+a-checkbox.outlined:state(checked)::after {
+  background-color: light-dark(#5f4bc3, #7460d7);
+}
+
+/* Customized — bold label, bigger circular box, bigger checkmark.
+   Colours use light-dark() so they're tuned for both themes at once. */
+a-checkbox.customized { font-weight: 700; }
+a-checkbox.customized::before,
+a-checkbox.customized::after { inline-size: 24px; block-size: 24px; margin-block-start: -2px; }
+a-checkbox.customized::before { border-radius: 50%; border-width: 2px; }
+a-checkbox.customized::after { mask-size: 16px; }                /* bigger mark */
+a-checkbox.customized:state(checked)::before {
+  background: light-dark(#1f6e5f, #2f9c84);
+  border-color: light-dark(#1f6e5f, #2f9c84);
+}
+
+/* Beautified — a full white heart mark swapped in via --checkbox-mask-check
+   (centred by the default mask-position), sized down a touch, on a pink fill */
+a-checkbox.beautified {
+  --checkbox-mask-check: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M12 21.35l-1.45-1.32C5.4 15.36 2 12.28 2 8.5 2 5.42 4.42 3 7.5 3c1.74 0 3.41.81 4.5 2.09C13.09 3.81 14.76 3 16.5 3 19.58 3 22 5.42 22 8.5c0 3.78-3.4 6.86-8.55 11.54z'/%3E%3C/svg%3E");
+}
+a-checkbox.beautified::before { border-radius: 8px; }
+a-checkbox.beautified::after { mask-size: 10px; }            /* smaller heart */
+a-checkbox.beautified:state(checked)::before {
+  background: light-dark(#ec4899, #f472b6);                  /* pink, both themes */
+  border-color: transparent;
+}
+```