@antadesign/anta 0.3.18 → 0.3.19

package/docs/components/tabs.md

@@ -0,0 +1,471 @@
+# Tabs
+
+A tablist for switching between views. The strip is data-driven: pass an
+`options` array (like [RadioGroup](./radio.md)), each entry a unique `value` plus a
+`label` (or `children`) and optional `icon` / `iconTrailing`. That alone is a
+selectable strip that emits the chosen value; add matching `<TabPanel>` children
+(see [Panels](#panels)) to show and hide the content too.
+
+## Priority
+
+```tsx
+<Tabs priority="primary"   defaultValue="a">…</Tabs>  {/* default */}
+<Tabs priority="secondary" defaultValue="a">…</Tabs>
+<Tabs priority="tertiary"  defaultValue="a">…</Tabs>
+```
+
+`priority` sets the selected-tab indicator:
+
+- **`primary`** (default): a pill on a track.
+- **`secondary`**: a filled tab, no track.
+- **`tertiary`**: an underline.
+
+## Tones
+
+Six named tones: `neutral` (default), `brand`, `info`, `success`, `warning`,
+`critical`. Any CSS colour works for a one-off custom tone. The tone runs through the
+strip's labels, indicator, and track at every priority. Rows are tones (the last is a
+custom colour); columns are priorities.
+
+**Primary**
+
+**Secondary**
+
+**Tertiary**
+
+```tsx
+<Tabs tone="brand" priority="secondary" defaultValue="a">…</Tabs>
+<Tabs tone="#e0457b" priority="tertiary" defaultValue="a">…</Tabs>  {/* any CSS colour */}
+```
+
+**Per-tab tone.** A `tone` on an individual option overrides the strip's tone for that one
+tab: it colours the label and icons in every mode, and the indicator when it's the active tab.
+A named tone colours the sliding indicator too; a custom literal colour tones the label
+everywhere but the indicator only under `noslide` (the single shared sliding element can't
+read a descendant's colour).
+
+```tsx
+<Tabs
+  defaultValue="overview"
+  label="Review queue"
+  options={[
+    { value: 'overview', label: 'Overview' },
+    { value: 'approved', label: 'Approved', icon: 'circle-check', tone: 'success' },
+    { value: 'flagged', label: 'Flagged', tone: 'warning' },
+    { value: 'rejected', label: 'Rejected', tone: 'critical' },
+  ]}
+/>
+```
+
+## Size
+
+```tsx
+<Tabs size="small" defaultValue="a">…</Tabs>
+```
+
+Three sizes reuse [Button](./button.md)'s type scale, so a strip lines up with
+same-size buttons and inputs: `small`, `medium` (default), `large`. Icons scale
+with the tab.
+
+## Orientation
+
+`horizontal` (default) lays the tabs in a row; `vertical` stacks them into a column.
+The arrow keys follow the axis: `←`/`→` when horizontal, `↑`/`↓` when vertical. To
+put panels **beside** a vertical strip, wrap `<Tabs>` in your own flex row (the strip
+and panels are siblings; see [Panels](#panels)). Vertical works at every priority:
+
+**Primary**
+
+**Secondary**
+
+**Tertiary**
+
+```tsx
+<Tabs
+  orientation="vertical"
+  priority="tertiary"
+  defaultValue="general"
+  options={[
+    { value: 'general', label: 'General' },
+    { value: 'members', label: 'Members' },
+    { value: 'integrations', label: 'Integrations' },
+  ]}
+/>
+```
+
+## Icons & content
+
+A tab option takes a leading **`icon`** and a trailing **`iconTrailing`**; here the
+trailing dot flags an unsaved file. For more than text, give the option **`children`**
+instead of `label`, like a [Tag](./tag.md) counter.
+
+```tsx
+<Tabs
+  defaultValue="app"
+  label="Open files"
+  options={[
+    { value: 'app', icon: 'braces', children: <>app.tsx <Tag size="small" value="2" /></> },
+    { value: 'readme', label: 'README.md', icon: 'file' },
+    { value: 'styles', icon: 'file', iconTrailing: 'circle-small-solid', children: 'styles.css' },
+  ]}
+/>
+```
+
+## Overflow
+
+When the tabs don't fit, their labels truncate with an ellipsis; the strip never
+widens the page. To scroll or wrap labels instead, see [Styling](#styling).
+
+Set an option's **`tooltip`** and a clipped tab reveals its full label on hover; tabs
+that fit show nothing. It renders as a `truncatedOnly` [Tooltip](./tooltip.md#show-only-when-truncated)
+anchored to the tab, so it shows only when the label ellipsizes. Hover the truncated
+tabs above to see it.
+
+```tsx
+<Tabs
+  defaultValue="overview"
+  label="Sections"
+  options={sections.map(({ value, label }) => ({
+    value,
+    label,
+    tooltip: label,
+  }))}
+/>
+```
+
+## Panels
+
+```tsx
+{/* The strip and panels are flat siblings — you arrange them. A flex column gaps
+    them; the strip centres itself (a <Tabs> `style` lands on <a-tabs>). */}
+<div style={{ display: 'flex', flexDirection: 'column', gap: 12 }}>
+  <Tabs
+    defaultValue="account"
+    label="Settings"
+    style={{ alignSelf: 'center' }}
+    options={[
+      { value: 'account', label: 'Account', icon: 'home' },
+      { value: 'security', label: 'Security' },
+      { value: 'billing', label: 'Billing' },
+    ]}
+  >
+    <TabPanel value="account"><AccountForm /></TabPanel>
+    <TabPanel value="security"><SecurityForm /></TabPanel>
+    <TabPanel value="billing"><BillingForm /></TabPanel>
+  </Tabs>
+</div>
+```
+
+Add a `<TabPanel value="…">` child for each option; each panel shows itself when
+its value is active. The panel names its tab as its accessible label
+(`aria-labelledby`, off-DOM). Panel content is arbitrary React, so it renders normally.
+
+Panels are **optional**. With none, `Tabs` is just the strip: listen to
+`onStateChange` / `onValueChange` and render the content yourself.
+
+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
+renderer. There is **no wrapper element**: the JSX becomes the strip followed by the
+panels as flat **siblings**, and `className` / `id` / `style` / `...rest` land on the
+strip. Arranging them is up to you (see below):
+
+```html
+<a-tabs role="tablist">
+  <a-tab role="tab" value="account" tabindex="0"><a-tab-label>Account</a-tab-label></a-tab>
+  …
+</a-tabs>
+<a-tabpanel role="tabpanel" value="account">…</a-tabpanel>   <!-- active: shown -->
+<a-tabpanel role="tabpanel" value="security">…</a-tabpanel>  <!-- inactive: display:none -->
+```
+
+A horizontal strip stacks above its panels in normal flow with no extra markup; for a
+vertical strip beside its panels, wrap `<Tabs>` in your own flex row. The panels find
+the strip as a sibling under the same parent (`a-tabpanel` → `:scope > a-tabs`), so
+keep them together; to split them into separate layout regions, drive a
+controlled `value` and render the panels yourself.
+
+Each `<a-tabpanel>` sits **beside** `<a-tabs>` (its sibling, never inside it, so a
+panel never lands in the primary track). It reads the active value from `<a-tabs>`
+and shows/hides **itself** via its own off-DOM `:state(active)`; nothing writes
+`hidden` / `inert` on it. The panel↔tab link is off-DOM too
+(`internals.ariaLabelledByElements`), so no `id` wiring is needed. No web component
+writes the light DOM, only your JSX does, which keeps a worker-thread reactive engine
+in sync.
+
+A `<TabPanel>` stays mounted while inactive (its DOM, form values, and scroll
+survive tab switches); `hideMode` picks how it hides:
+
+- **`display`** (default): `display:none`; leaves the tab order + a11y tree.
+- **`visibility`**: `visibility:hidden`, keeping its layout box (to avoid reflow
+  or to measure a hidden panel).
+
+```tsx
+<TabPanel value="b" hideMode="visibility"><Chart /></TabPanel>
+```
+
+To **not render** an inactive panel at all (unmount it to reset its state or defer an
+expensive subtree, or mount it lazily on first open), drive selection with a
+controlled `value` and render the panels yourself. `Tabs` passes panels straight
+through, so you decide what's mounted:
+
+```tsx
+const [tab, setTab] = useState('a')
+
+// Unmount inactive — only the open panel exists:
+<Tabs value={tab} onStateChange={(_e, { next }) => next && setTab(next)} options={…}>
+  {tab === 'a' && <TabPanel value="a"><Expensive /></TabPanel>}
+  {tab === 'b' && <TabPanel value="b"><Form /></TabPanel>}
+</Tabs>
+
+// Lazy — mount on first open, keep after (track a "seen" set in state):
+{seen.has('b') && <TabPanel value="b"><Heavy /></TabPanel>}
+```
+
+The same controlled pattern places the strip and panels in **different layout
+regions**: render `<Tabs options={…} value onStateChange>` in one place and your
+content wherever you like, switching on the value yourself.
+
+## Controlled vs. uncontrolled
+
+The active tab is named by a single **value string**, the `value` of one of your
+`options`. Whatever value is active, `Tabs` marks that tab selected and reveals the
+`<TabPanel value="…">` that shares it (if any). You choose who owns that value:
+
+**Uncontrolled.** Pass `defaultValue` (an option's `value`) and let `Tabs` own the
+active tab from there:
+
+```tsx
+<Tabs
+  defaultValue="overview"
+  options={[
+    { value: 'overview', label: 'Overview' },
+    { value: 'activity', label: 'Activity' },
+  ]}
+/>
+```
+
+**Controlled.** Pass `value` (an option's `value`) + `onStateChange` and own it
+yourself. `onStateChange` fires *before* the pick applies: set `value` to the new tab
+to accept, or do nothing to reject.
+
+```tsx
+const [tab, setTab] = useState('overview')
+
+<Tabs
+  value={tab}
+  onStateChange={(e, { next }) => setTab(next)}
+  options={[
+    { value: 'overview', label: 'Overview' },
+    { value: 'activity', label: 'Activity' },
+  ]}
+/>
+```
+
+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;
+arrow / `Home` / `End` navigation activates as it moves (selection follows focus).
+Disabled tabs are skipped and dropped from the tab order.
+
+Pass `label` for the tablist's accessible name. Each `<TabPanel>` names its tab as
+its accessible label (`aria-labelledby`), set off-DOM so nothing writes the panel's
+attributes.
+
+`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*;
+`onValueChange` waits for `value` to change, which for a route happens only after
+you've already navigated). Skip the `<TabPanel>`s, since the router renders the view.
+
+```tsx
+<Tabs
+  value={pathname}
+  onStateChange={(_e, { next }) => next && navigation.navigate(next)}
+  options={[
+    { value: '/settings/profile', label: 'Profile' },
+    { value: '/settings/billing', label: 'Billing' },
+  ]}
+/>
+```
+
+Swap `navigation.navigate` for whatever the app uses (`router.push`, Astro's
+`navigate`, `location.assign`). Controlling `value` from the route keeps the right
+tab active through back/forward and deep links. To guard a switch (unsaved edits),
+veto it in `onStateChange` with `event.preventDefault()`.
+
+## Events
+
+Three callbacks, in firing order:
+
+| Callback | When | Cancelable | Payload |
+|---|---|---|---|
+| `onStateChange(e, { next, prev })` | **before** a pick applies | ✅ | next / prev value |
+| `onChange(e)` | **after** selection applies | — | native `change` event |
+| `onValueChange(e, { value })` | **after** selection applies | — | `{ value }` |
+
+Use **`onStateChange`** when you control `value`: it fires on the user's pick before
+anything applies, so it's your chance to set the new `value`. Applying it (or the
+element self-applying, uncontrolled) then fires **`onChange`** / **`onValueChange`**,
+so those suit an uncontrolled strip reacting to its own pick. **`onFocus`** /
+**`onBlur`** report focus entering and leaving the strip (wired to `focusin` /
+`focusout`, since focus lands on a tab).
+
+```tsx
+// Uncontrolled: the strip owns selection, so onValueChange fires on each pick.
+<Tabs defaultValue="a" onValueChange={(_e, { value }) => route(value)}>…</Tabs>
+```
+
+| 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. |
+| `disabled?` | boolean | — | Disable the whole strip. |
+| `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.) |
+| `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`. |
+| `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`). |
+| `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` colours `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. |
+
+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.
+
+Keep the tab strip and panels as siblings under one parent. Panels read the active
+value from `<a-tabs>`.
+
+```html
+<div>
+  <a-tabs role="tablist" default-state="account">
+    <a-tab role="tab" value="account" tabindex="0"><a-tab-label>Account</a-tab-label></a-tab>
+    <a-tab role="tab" value="security" tabindex="-1"><a-tab-label>Security</a-tab-label></a-tab>
+  </a-tabs>
+  <a-tabpanel role="tabpanel" value="account">Account settings</a-tabpanel>
+  <a-tabpanel role="tabpanel" value="security">Security settings</a-tabpanel>
+</div>
+```
+
+Reach for the props first: **`tone`**, **`size`**, **`priority`**. The focus ring is
+the global `--focus-ring` (see [Colors](../colors.md#focus-ring)).
+
+For anything else the strip is light-DOM: `<a-tabs>` the tablist, each `<a-tab>` a
+tab (its text wrapped in `<a-tab-label>`), `<a-tabpanel>` a panel, and the moving
+indicator is `<a-tabs>`'s `::before`. Target them with ordinary CSS (an un-layered rule
+beats `@layer anta` without `!important`) and reach for real properties
+(`border-radius`, `padding`, `background`, …), **not** the internal `--*` output tokens.
+The demo classes below (`.square-tabs`, `.glow-tabs`, …) are just hooks; swap your own.
+
+**Roomier track.** The strip hugs its tabs by default (0 padding), so it's exactly a
+same-size button tall. For a gap around the selected pill (the classic "well" look), add
+`padding` and bump `border-radius` by the same amount, so the outer corner stays concentric
+with the tabs' 4px. The strip grows 2×the padding taller.
+
+```css
+a-tabs.roomy-1 { padding: 1px; border-radius: 5px; }   /* 4 + 1 */
+a-tabs.roomy-3 { padding: 3px; border-radius: 7px; }   /* 4 + 3 */
+```
+
+**Squarer primary.** Square corners, heavier labels, and a roomier `4px` track with no
+border or ring on the strip (`box-shadow: none` drops the default track ring) — just a 1px
+square ring on the raised pill. The track is `<a-tabs>`, the sliding pill its `::before`:
+
+```css
+a-tabs.square-tabs         { border-radius: 0; padding: 4px; box-shadow: none; }  /* no track border / ring */
+.square-tabs a-tab         { border-radius: 0; font-weight: 600; }
+a-tabs.square-tabs::before { border-radius: 0; box-shadow: 0 0 0 1px light-dark(#cfcfd6, #46464e); }  /* 1px square pill ring */
+```
+
+**Tertiary glowing underline.** Recolour the sliding underline and add a radial highlight
+rising from it. The slider is a full-cover box whose `border-bottom` is the line, so a
+`background` gradient on it fills the tab behind the label. Because it's one element, the
+glow **slides with the line** between tabs, with no `noslide` and no separate per-tab
+background.
+
+```css
+/* The class is on the <a-tabs> element itself, so target a-tabs.glow-tabs (not a descendant).
+   The tertiary slider is a full-cover box with a border-bottom line — recolour the border and
+   fill it with a gradient; both slide together. Where CSS anchor positioning isn't supported
+   there's no slider — tertiary falls back to the per-tab ::after underline (a plain line). */
+a-tabs.glow-tabs::before {
+  border-bottom-color: light-dark(#8067ff, #907aff);   /* recolour the sliding line */
+  background:                                          /* highlight rising from the line, slides with it */
+    radial-gradient(80% 100% at 50% 100%,
+      color-mix(in oklch, light-dark(#8067ff, #907aff) 30%, transparent), transparent 70%);
+}
+```
+
+**Scroll instead of ellipsizing.** Keep full labels and let the strip scroll
+horizontally: pin each tab to its content width (`flex: none`) and make the strip
+scrollable.
+
+```css
+.scroll-tabs a-tabs { overflow-x: auto; scrollbar-width: thin; }
+.scroll-tabs a-tab  { flex: none; }
+```
+
+**Equal-width tabs.** By default tabs are sized to their labels (and compress only
+when the strip overflows). For a segmented-control look where every tab is the same
+width, let them fill the strip from a zero basis:
+
+```css
+.equal-tabs a-tabs { width: 100%; }
+.equal-tabs a-tab  { flex: 1 1 0; max-width: none; }
+```
+
+**Wrap labels.** Let long labels wrap so the tabs grow taller instead of truncating:
+
+```css
+.wrap-tabs a-tab,
+.wrap-tabs a-tab-label { white-space: normal; text-overflow: clip; overflow: visible; text-align: center; }
+```
+
+**Disable the slide.** By default the selected-tab indicator slides between tabs (a
+single rectangle, via CSS anchor positioning). Pass `noslide` to paint it on each tab
+instead, so the highlight snaps with no movement. It's also the automatic fallback
+where anchor positioning isn't supported.
+
+```tsx
+<Tabs noslide defaultValue="a">…</Tabs>
+```
+
+**Fully-rounded pill.** The built-in **`round`** prop rounds the track, every tab, **and**
+the sliding pill to `999px` in one flag, no CSS needed (it drives `--tab-radius`, which feeds
+the tabs, the moving indicator, and the primary track well):
+
+```tsx
+<Tabs round defaultValue="a" label="Sections">…</Tabs>   {/* pill track + tabs + indicator */}
+```

package/docs/components/tag.md

@@ -0,0 +1,185 @@
+# Tag
+
+A compact pill for status, labels, and metadata. The `Tag` JSX wrapper
+renders an `<a-tag>` styled tag — there's no JavaScript, so tone, size,
+and case are all plain attributes and the styling is identical whether
+you use the wrapper or author the element by hand. Content is composed
+from `icon`, `label`, `value`, and `iconTrailing` props, the same way
+`Button` works.
+
+## Priority
+
+`priority` sets the emphasis. `secondary` (the default) is the subtle
+alpha-tint fill; `primary` is a solid fill with white text; `tertiary` is
+a transparent outline. It composes with every tone — named or custom —
+and tracks dark mode.
+
+```tsx
+<Tag allcaps priority="primary" tone="brand" label="Primary" />
+<Tag allcaps tone="brand" label="Secondary" />
+<Tag allcaps priority="tertiary" tone="brand" label="Tertiary" />
+```
+
+## Tones
+
+Omit `tone` for the neutral gray tag, or pick a semantic tone. Color
+comes from the theme tokens, so every tone tracks light and dark mode
+automatically.
+
+```tsx
+<Tag allcaps label="Neutral" />
+<Tag allcaps tone="brand" label="Brand" />
+<Tag allcaps tone="info" label="Info" />
+<Tag allcaps tone="success" label="Success" />
+<Tag allcaps tone="warning" label="Warning" />
+<Tag allcaps tone="critical" label="Critical" />
+```
+
+`tone` also accepts any literal CSS color for a one-off tag. The hue is
+kept while lightness and chroma are pinned to the named-tone curve.
+
+```tsx
+<Tag allcaps tone="#ff1493" label="Magenta" />
+<Tag allcaps tone="rebeccapurple" label="Purple" />
+<Tag allcaps tone="#0d9488" label="Teal" />
+```
+
+Every tone — named or custom — paints its fill and border as
+semi-transparent alpha tints rather than solid colors, so a tag picks up
+whatever surface sits behind it. Here the same tags sit on a `--bg-4`
+panel instead of the page canvas.
+
+## Size
+
+Three sizes — `small` (16px), `medium` (20px, the default — emits no
+attribute), and `large` (24px) — matching `Button`. Height is intrinsic
+(line-height + padding rather than a fixed value), so the text is never
+clipped.
+
+```tsx
+<Tag allcaps tone="info" size="small" label="Small" />
+<Tag allcaps tone="info" label="Medium" />
+<Tag allcaps tone="info" size="large" label="Large" />
+```
+
+## Icon, label & value
+
+Set `icon` / `iconTrailing` for a leading or trailing glyph (scaled to
+the pill), and pair `label` with `value` for a two-part tag. `value` is
+the primary text (default color and weight); the `label` sits before it
+as a bold "key" (weight 600, same color) with no divider — the weight
+contrast does the separating. Tabular figures are always on, so counts,
+versions, and timers don't reflow.
+
+```tsx
+<Tag allcaps tone="success" icon="circle-check" label="Build" value="passed" />
+<Tag allcaps tone="info" icon="hourglass" label="Running" value="20m 16s" />
+<Tag allcaps icon="github-logo" label="Commit" value="4f90d13" />
+<Tag allcaps tone="warning" label="Retries" value="3" iconTrailing="refresh" />
+```
+
+## Segments
+
+For an arbitrary multi-part tag, pass several **children** instead of
+`label` / `value` — each segment after the first gets a hairline divider
+(a leading `icon` stays flush). The divider-less `label` + `value`
+pairing is the exception; everything else segments like this.
+
+```tsx
+<Tag allcaps>
+  <span>v2.1.0</span>
+  <span>stable</span>
+  <span>x64</span>
+</Tag>
+<Tag allcaps tone="info">
+  <span>GET</span>
+  <span>200</span>
+  <span>142 ms</span>
+</Tag>
+<Tag allcaps tone="critical" icon="warning-triangle">
+  <span>Exit 137</span>
+  <span>OOM</span>
+</Tag>
+```
+
+## Case
+
+Tags are normal (mixed) case by default, so the text is read as written —
+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.
+
+```tsx
+<Tag icon="github-logo" label="GitHub" value="v1.6.9" />
+<Tag allcaps label="Running" />
+```
+
+### 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). |
+| `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. |
+
+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 `a-tag-label` for the key and `a-tag-value` for its value.
+
+```html
+<a-tag tone="success">
+  <a-icon shape="check" aria-hidden="true"></a-icon>
+  <a-tag-label>Build</a-tag-label>
+  <a-tag-value>Passed</a-tag-value>
+</a-tag>
+```
+
+Reach for the props first: **`tone`** sets the colour (any CSS colour for a custom
+tone — it derives the fill / border / text in oklch), **`priority`** the fill style,
+**`size`** the dimensions.
+
+```tsx
+<Tag allcaps tone="#e0457b" priority="secondary" label="Custom" />
+```
+
+`<a-tag>` is light-DOM, so for anything a tone can't give you it's plain CSS (an
+un-layered rule beats `@layer anta` without `!important`). The `.badge` class below
+takes a **gradient** background (impossible from `tone`, which is a solid colour),
+**1px** corners, and taller vertical padding so it reads completely differently:
+
+```css
+a-tag.badge {
+  background: linear-gradient(135deg, #1f6e5f, #845ec2);   /* a tone can't do gradients */
+  color: #fff;
+  border-radius: 1px;                                       /* sharp corners */
+  padding-block: 5px;                                       /* tighter vertical padding */
+  padding-inline: 14px;
+}
+a-tag.badge a-tag-label { font-weight: 600; letter-spacing: 0.15ch; }
+```
+
+For a *solid* recolour, prefer `tone` / `priority` — don't reach for the resolved
+`--tag-bg` / `--tag-border` / `--tag-text` (they're recomputed per priority and tone).