@antadesign/anta 0.3.23 → 0.3.25

package/docs/components/breadcrumbs.md

@@ -0,0 +1,177 @@
+# Breadcrumbs
+
+Hierarchy navigation assembled from Anta Buttons. Breadcrumb entries can be
+links, actions, or copy controls. Set `maxItems` to fold one middle range into a
+More menu without measuring the available width.
+
+## Items
+
+Pass ordered data through `items`. An `href` renders a native link with the
+Button appearance; omit it for an action button. Each item accepts `label`,
+`icon`, `iconTrailing`, `tone`, `disabled`, `onClick`, `className`, `style`,
+`id`, `title`, and `data-*` / `aria-*` attributes. `size`, priority, and
+underline treatment belong to the whole trail so every visible control retains
+the same height.
+
+```tsx
+<Breadcrumbs
+  aria-label="Project location"
+  items={[
+    { label: 'Home', href: '/', icon: 'home' },
+    { label: 'Projects', href: '/projects', icon: 'folder-open', tone: 'brand' },
+    { label: 'Refresh', icon: 'refresh', onClick: reload },
+  ]}
+/>
+```
+
+An item with `current` receives `aria-current="page"`. The current item may
+remain a link when revisiting the page is useful, or it can be an action such as
+copying the current path.
+
+## Priority, size, underline, and padding
+
+Breadcrumbs use either `tertiary` or `quaternary` Button priority. `size` drives
+every visible crumb and the More control: small is 24px, medium is 28px, and
+large is 32px. `underline` and `underlineOnHover` forward to each visible Button.
+With `priority="quaternary"` (the default), `paddingless` removes their horizontal
+padding without changing their height, and uses a `0.75ch` gap around separators.
+
+```tsx
+<Breadcrumbs priority="tertiary" size="small" items={items} />
+<Breadcrumbs priority="quaternary" underline="solid" underlineOnHover items={items} />
+<Breadcrumbs paddingless items={items} />
+<Breadcrumbs priority="tertiary" size="large" items={items} />
+```
+
+The default is medium quaternary. `tertiary` adds a hover fill. `quaternary`
+keeps the trail text-only, which suits dense page headers. An underline is
+permanent unless `underlineOnHover` is set. `paddingless` is only available with
+quaternary priority.
+
+## Separators
+
+Pass any of `→`, `/`, `•`, or `▸` for a text separator. Pass an
+Anta icon shape for an icon separator. Separators are decorative and hidden from
+assistive technology.
+
+```tsx
+<Breadcrumbs separator="→" items={items} />
+<Breadcrumbs separator="/" items={items} />
+<Breadcrumbs separator="•" items={items} />
+<Breadcrumbs separator="▸" items={items} />
+<Breadcrumbs separator="chevron-right" items={items} />
+```
+
+`chevron-right` is the default. The icon form accepts any registered `IconShape`,
+including icons added by an application through Anta's icon generator. Icon
+separators use no flex gap; text separators keep the configured gap.
+
+## Folding into More
+
+`maxItems` limits the number of original breadcrumb entries that remain visible;
+the More control does not count. When folding, `itemsBeforeCollapse` controls
+where More appears. Its default is `0`, so More comes first and the most recent
+items remain visible. The final original item is always kept visible.
+
+```tsx
+// More / Projects / Anta / Button.tsx
+<Breadcrumbs maxItems={3} items={items} />
+
+// Home / Workspace / More / src / Button.tsx
+<Breadcrumbs maxItems={4} itemsBeforeCollapse={2} items={items} />
+```
+
+The More trigger is an icon-only Button followed by an Anta `Menu`; it supports
+pointer, keyboard, and outside-dismiss interaction through the existing menu
+primitive. Folded links retain their native link behavior, while folded actions
+become menu selections.
+
+## Copying the current item
+
+An item with `copy`, `copyNode`, or `copyUrl` uses `ButtonCopy` while visible and
+`MenuItemCopy` if it is folded. Copy entries cannot combine with `href`. Mark a
+copying final item `current` when it represents the current page.
+
+```tsx
+<Breadcrumbs
+  items={[
+    { label: 'Home', href: '/' },
+    {
+      label: 'Button.tsx',
+      current: true,
+      copy: 'src/components/Button.tsx',
+      iconPlacement: 'trailing',
+      copiedLabel: 'Path copied',
+    },
+  ]}
+/>
+```
+
+Use `copyUrl` to copy `location.href`, `copyNode` to copy a marked rendered
+region, or `copy` for a known string. For dynamic text, pass a controlled `copy`
+string and set it from `onCopyRequest`. `onCopied` receives the result.
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `items` | BreadcrumbItem[] | — | Ordered breadcrumb entries. |
+| `itemsBeforeCollapse?` | number | 0 | Number of original items kept before the More control when `maxItems`
+ collapses the trail. The rest of the visible-item budget is kept from the
+ end, so `0` puts More first. |
+| `maxItems?` | number | — | Maximum number of original breadcrumb items left visible. The More
+ control does not count. Omit to keep every item visible. |
+| `moreLabel?` | string | 'Show more breadcrumbs' | Accessible name for the More control. |
+| `paddingless?` | boolean | — | Remove horizontal padding from every visible breadcrumb control. |
+| `priority?` | 'quaternary' \| 'tertiary' | quaternary | Button priority applied to every visible item and the More control. |
+| `separator?` | BreadcrumbSeparator | 'chevron-right' | Separator between visible entries. |
+| `size?` | 'small' \| 'medium' \| 'large' | 'medium' | Button size applied to every visible item and the More control. |
+| `underline?` | 'solid' \| 'dashed' \| 'dotted' | — | Underline style applied to every visible breadcrumb control. |
+| `underlineOnHover?` | boolean | — | Hide the underline at rest and reveal it on hover. |
+
+`Breadcrumbs` deliberately adds no custom-element behavior: it assembles Anta
+Buttons, an optional Menu, and two light-DOM layout tags. When you are not using
+JSX, import the Breadcrumbs stylesheet and the primitives, then compose the same
+structure yourself. Keep an overflow Menu immediately after its More Button.
+
+```ts
+import '@antadesign/anta/components/Breadcrumbs.css'
+import '@antadesign/anta/elements'
+```
+
+```html
+<a-breadcrumbs role="navigation" aria-label="Project location" data-paddingless>
+  <a href="/" data-anta role="button" priority="quaternary" paddingless>
+    <a-button-label>Home</a-button-label>
+  </a>
+  <a-breadcrumb-separator aria-hidden="true">•</a-breadcrumb-separator>
+
+  <a-button role="button" tabindex="0" priority="quaternary" paddingless
+    aria-label="Show more breadcrumbs" aria-haspopup="menu">
+    <a-icon shape="more" aria-hidden="true"></a-icon>
+  </a-button>
+  <a-menu autowidth>
+    <a href="/workspace" data-anta-menu-item role="menuitem"><a-menu-item-label>Workspace</a-menu-item-label></a>
+    <a href="/workspace/projects" data-anta-menu-item role="menuitem"><a-menu-item-label>Projects</a-menu-item-label></a>
+  </a-menu>
+
+  <a-breadcrumb-separator aria-hidden="true">•</a-breadcrumb-separator>
+  <a href="/workspace/projects/anta" data-anta role="button" priority="quaternary"
+    paddingless aria-current="page"><a-button-label>Anta</a-button-label></a>
+</a-breadcrumbs>
+```
+
+Use `priority`, `size`, and `separator` before adding CSS. A `className` on
+`Breadcrumbs` lands on the navigation wrapper; item `className` values land on
+their individual Buttons. The composed structure uses light-DOM tags, so plain
+CSS can style a separator directly.
+
+```tsx
+<Breadcrumbs className="project-breadcrumbs" separator="chevron-right" items={items} />
+```
+
+```css
+.project-breadcrumbs a-breadcrumb-separator {
+  color: var(--text-2);
+}
+```

package/docs/components/button.md

@@ -190,11 +190,13 @@ dropped (a valid `0` still renders).
 <Button tone="brand" priority="tertiary" underline="solid"  label="Solid" />
 <Button tone="brand" priority="tertiary" underline="dashed" label="Dashed" />
 <Button tone="brand" priority="tertiary" underline="dotted" label="Dotted" />
+<Button tone="brand" priority="quaternary" underline="solid" underlineOnHover label="Hover only" />
 ```
 
 When the button has a [link mode](#link-mode), or you simply want an
 underline stylistically, it supports three styles — `solid`, `dashed`,
-`dotted` (only valid on `priority="tertiary"` / `"quaternary"`).
+`dotted` (only valid on `priority="tertiary"` / `"quaternary"`). Set
+`underlineOnHover` to keep that underline hidden until pointer hover.
 
 ## States
 
@@ -286,11 +288,11 @@ carries a link back to where it came from.
 <ButtonCopy copy={snippet} copyWithUrl label="Copy snippet" />  {/* snippet + source URL */}
 ```
 
-### Lazy content
+### Copy dynamic text
 
-When the content is expensive to compute or changes over time, keep `copy`
-reactive and refresh it in **`onCopyRequest`**, which fires on **pointerdown** —
-the click that follows copies the latest value.
+`copy` is a controlled string. Start it at `''`, then set the new text in
+`onCopyRequest`. The next render updates `copy`, and activation writes that value.
+`onCopyRequest` does not return text. It does not add a polling loop.
 
 ```tsx
 const [report, setReport] = useState('')
@@ -298,16 +300,28 @@ const [report, setReport] = useState('')
 <ButtonCopy
   copy={report}
   label="Copy report"
-  onCopyRequest={() => setReport(generateReport())} // recomputed on pointerdown
+  onCopyRequest={() => setReport(generateReport())}
 />
 ```
 
-The value is recomputed on pointerdown and read on the click a moment later, so
-the pointerdown→click gap absorbs the work — including an update that arrives from
-another thread. Only the serializable `copy` string crosses, through the normal
-re-render, so this holds in off-UI-thread runtimes (a worker-rendered app) where a
-callback couldn't. The clipboard API's user-gesture requirement is preserved
-because the write happens on the click.
+`onCopyRequest` fires on pointerdown or Enter/Space keydown, before the click or
+menu selection that writes to the clipboard.
+
+#### Why `copy` is controlled
+
+In a usual React or Preact app, an `onClick` handler can calculate a string and
+call the Clipboard API itself. `ButtonCopy` also supports applications rendered
+from a worker. The DOM copy control and Clipboard API are on the browser UI
+thread, but the application's JSX code can be elsewhere. A function cannot cross
+that boundary as a callable reference.
+
+The request tells the application to calculate the text. Its state update makes
+the renderer send the string as the `copy` attribute. The control then writes that
+attribute during activation, when the browser permits clipboard access. A
+`lazyCopy: () => string` prop could only hide this same state update inside the
+wrapper. A generic return value would also need a defined clipboard format and
+serialization; Anta supports text (`copy`), a DOM region (`copyNode`), and the
+current URL (`copyUrl`).
 
 ### Props
 
@@ -340,10 +354,9 @@ because the write happens on the click.
  activation, and removes the button from the tab order while active. |
 | `onClick?` | (e) => void | — | Click handler. |
 | `onCopied?` | (ok) => void | — | Fires after the copy attempt with whether it succeeded. |
-| `onCopyRequest?` | () => void | — | Compute the copy content lazily. Fires on pointerdown / keydown; update
- `copy` (a state change) here and the activation copies the latest value.
- The gap lets the update land even off the UI thread — only the
- serializable `copy` string crosses. |
+| `onCopyRequest?` | () => void | — | Refresh a dynamic `copy` value before activation. Set the new string in
+ application state so the next render updates `copy`. Return values are
+ ignored. Fires on pointerdown and Enter/Space keydown. |
 | `paddingless?` | boolean | — | Drops outer padding to zero. |
 | `ping?` | string | — | Space-separated URLs the browser pings on navigation. |
 | `priority?` | 'primary' \| 'secondary' \| 'tertiary' \| 'quaternary' | secondary | Visual emphasis. |
@@ -369,6 +382,7 @@ because the write happens on the click.
  brand curve so any input stays legible. |
 | `type?` | 'button' \| 'submit' \| 'reset' | — | Form submission type. |
 | `underline?` | 'solid' \| 'dashed' \| 'dotted' | — | Underline style. |
+| `underlineOnHover?` | boolean | — | Hide the underline at rest and reveal it on hover. |
 
 ## Link mode
 

package/docs/components/dialog.md

@@ -193,13 +193,13 @@ destructive button, and it works the same with or without a close button or
 focusable content. A screen reader announces the dialog by its `header` text
 (mirrored to the dialog's accessible name), and the ✕ is the last tab stop.
 
-To focus a specific control on open instead (a search field, say), put
-`autofocus` on it; the dialog honors that and skips the default. On close, focus
-returns to whatever opened the dialog, from the native `<dialog>`.
+To focus a specific control on open instead (a search field, say), pass
+`autoFocus`; the dialog focuses it before returning from the opening interaction.
+On close, focus returns to whatever opened the dialog, from the native `<dialog>`.
 
 ```tsx
 <Dialog header="Rename" footer={…}>
-  <Input label="Name" autofocus />   {/* focus the field on open */}
+  <Input label="Name" autoFocus />
 </Dialog>
 ```
 

package/docs/components/input-time.md

@@ -68,6 +68,7 @@ range is clamped to the nearest bound as you step or leave the field, and flags
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
+| `autoFocus?` | boolean | — | Focus this field when its containing `Dialog` opens. |
 | `children?` | ReactNode | — | Extra content rendered under the field, above the hint (a no-box child like
  a `<Tooltip>` takes no space and anchors to the field). |
 | `clearable?` | boolean | — | Show a clear button once the field has a value. |

package/docs/components/input.md

@@ -431,6 +431,7 @@ wraps to fewer columns as it narrows. Resize the preview to see it reflow.
 | `autoComplete?` | 'off' \| 'on' \| 'name' \| 'username' \| 'email' \| 'current-password' \| 'new-password' \| 'one-time-code' \| 'tel' \| 'url' \| (string & {}) | — | Native autocomplete token. Overrides the value derived from `type`
  (`email` / `tel` / `url`) — set it for the cases `type` can't express, e.g.
  `username`, `current-password`, `new-password`, `one-time-code`, or `off`. |
+| `autoFocus?` | boolean | — | Focus this field when its containing `Dialog` opens. |
 | `children?` | ReactNode | — | Extra content rendered directly under the field, above the hint/error (it
  pushes the message down). A no-box child like an Anta `<Tooltip>` takes no
  space and anchors to the field — consistent with how tooltips attach
@@ -544,6 +545,10 @@ file name, with an Anta-styled chooser button. `submit` and `reset` inputs use t
 matching Anta button chrome; set `priority="primary"` on a submit control when it
 is the form's main action.
 
+`<textarea data-anta>` uses the same field chrome. Set `rows` for its height; one
+field-height is the minimum, and it resizes vertically. Native textareas do not
+autogrow; use Input's [`multiline`](#multiline) instead.
+
 Use `data-anta-size="small"` or `"large"` for field sizing. Native inputs own
 their `size` attribute, so Anta does not reuse it. `round` and a custom-color
 `tone` work the same way as Input.
@@ -556,6 +561,7 @@ their `size` attribute, so Anta does not reuse it. `round` and a custom-color
 <input data-anta round type="url" name="site" placeholder="Rounded URL">
 <input data-anta type="password" name="password" value="password">
 <input data-anta tone="rebeccapurple" type="number" name="seats" value="3" min="1">
+<textarea data-anta rows="3" name="notes" placeholder="Notes"></textarea>
 <input data-anta type="file" name="attachment" accept=".pdf,.docx">
 
 <input data-anta type="submit" value="Submit" priority="primary">

package/docs/components/menu.md

@@ -366,11 +366,12 @@ chevron stay centered on the row, so it composes with a trailing counter.
 </Menu>
 ```
 
-`MenuItemCopy` is a row that copies to the clipboard when chosen — `copy` for a
-literal string, `copyNode` for a DOM region. It composes a `<MenuItem>` with a
-slotted `<a-copy>` element that performs the write, and keeps the menu open on
-select so the check / retone feedback shows. `onCopied(ok)` fires after each
-attempt.
+`MenuItemCopy` is a row that copies to the clipboard when chosen: `copy` for a
+string, `copyNode` for a DOM region, or `copyUrl` for the current URL. It composes
+a `<MenuItem>` with a slotted `<a-copy>` element that performs the write, and
+keeps the menu open on select so the check / retone feedback shows. `onCopied(ok)`
+fires after each attempt. `iconPlacement="trailing"` moves the feedback glyph to
+the end of the row; `"none"` shows a cursor-near confirmation instead.
 
 Copy sits alongside normal items, so a "Share" menu can mix a copy-link row with
 navigating links.
@@ -391,6 +392,7 @@ navigating links.
 |------|------|---------|-------------|
 | `children?` | ReactNode | — | Item content. With `label` set, children are extra content — most
  notably the nested `<Menu>` for a submenu parent. |
+| `copiedLabel?` | string | Copied | Text in the successful no-icon confirmation. |
 | `copy?` | string | — | Text copied to the clipboard on activation. |
 | `copyNode?` | boolean \| string | — | Copy a DOM node as rich text (`text/html`) + plain text. `true` copies
  the nearest ancestor marked `data-copy-source`; a string is a CSS
@@ -404,6 +406,9 @@ navigating links.
  option `hint`. Requires `label` (it stacks in a column beneath it). Muted
  (`--text-3`) and tracks the row's `tone`. A string, or any node. |
 | `icon?` | IconShape | — | Leading icon shape. |
+| `iconPlacement?` | 'leading' \| 'trailing' \| 'none' | 'leading' | Where the copy glyph sits relative to the label — or `'none'` to omit it.
+ Without a glyph, a successful copy shows a confirmation label near the
+ pointer and leaves the row unchanged. |
 | `iconTrailing?` | IconShape | — | A trailing icon. On a `submenu` item this **overrides** the default
  chevron (omit it to keep the chevron); on a normal item it's the trailing
  glyph (omit for none). |
@@ -416,15 +421,18 @@ navigating links.
  carries `role` + `aria-checked`; only the drawn mark changes. Suppresses the
  built-in checkbox / radio and the trailing `check` glyph. The node is made
  passive (aria-hidden, no pointer events) so the row receives the click. |
-| `kbd?` | string | — | A trailing keyboard-shortcut hint, e.g. `"⌘E"`. |
+| `kbd?` | string | — | Trailing shortcut hint, e.g. `"⌘E"`. Anta translates it to
+ `aria-keyshortcuts` and hides the visual glyphs from assistive technology.
+ Use `+` within a chord and spaces between shortcuts (`"⌘K ⌘S"` becomes
+ `"Meta+K Meta+S"`). Pass `aria-keyshortcuts` to override the translation.
+ This does not bind the shortcut. |
 | `label?` | ReactNode | — | The item's text. Usually a string, but any node is accepted — e.g. a filtered
  `Select` bolds the matched substring. Omit and pass `children` for richer
  content. |
 | `onCopied?` | (ok) => void | — | Fires after the copy attempt with whether it succeeded. |
-| `onCopyRequest?` | () => void | — | Compute the copy content lazily. Fires on pointerdown / keydown; update
- `copy` (a state change) here and the activation copies the latest value.
- The gap lets the update land even off the UI thread — only the
- serializable `copy` string crosses. |
+| `onCopyRequest?` | () => void | — | Refresh a dynamic `copy` value before activation. Set the new string in
+ application state so the next render updates `copy`. Return values are
+ ignored. Fires on pointerdown and Enter/Space keydown. |
 | `onMouseDown?` | (event) => void | — | Raw `mousedown` on the row. Mainly to `preventDefault()` so the row doesn't
  take focus on a mouse press — e.g. a combobox option keeping focus in its
  input field while the click still selects. |

package/docs/components/tag.md

@@ -183,3 +183,50 @@ a-tag.badge a-tag-label { font-weight: 600; letter-spacing: 0.15ch; }
 
 For a *solid* recolor, prefer `tone` / `priority` — don't reach for the resolved
 `--tag-bg` / `--tag-border` / `--tag-text` (they're recomputed per priority and tone).
+
+### Interactive tags
+
+`Tag` is presentational. Wrap it in an anchor for navigation or a native button
+for an action. The outer control receives focus and keyboard activation.
+
+```tsx
+<a className="tag-link" href="/builds/42">
+  <Tag tone="info" icon="external-link" label="Build" value="#42" />
+</a>
+```
+
+```css
+a.tag-link {
+  display: inline-flex;
+  text-decoration: none;
+  cursor: pointer;
+}
+```
+
+A removable tag has one interactive child: its remove `Button`. Keep the label
+as tag content, give the button an accessible name, and let the segment divider
+separate it. Remove the tag's block padding so the small button keeps its target
+size. The negative focus offset keeps its focus ring inside the tag's clipped edge.
+
+```tsx
+<Tag className="removable-tag" tone="info">
+  <span>Frontend</span>
+  <Button priority="quaternary" size="small" icon="x" aria-label="Remove Frontend" />
+</Tag>
+```
+
+```css
+a-tag.removable-tag {
+  padding-block: 0;
+}
+a-tag.removable-tag > a-button {
+  align-self: stretch;
+}
+a-tag.removable-tag > a-button:focus-visible {
+  outline-offset: -2px;
+}
+```
+
+When a tag both opens something and removes it, render two sibling controls in a
+compound layout. Do not place a remove button inside an anchor or button that
+wraps the tag.

package/docs/index.md

@@ -25,6 +25,7 @@ Anta is designed for a clean DOM. Prefer the props and attributes exposed by eac
 - [Progress](./components/progress.md)
 
 - [Button](./components/button.md)
+- [Breadcrumbs](./components/breadcrumbs.md)
 - [Checkbox](./components/checkbox.md)
 - [Radio](./components/radio.md)
 - [Switch](./components/switch.md)

package/docs/install-config.md

@@ -44,7 +44,7 @@ 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/reset.css` | A small reset plus Anta's focus, heading, list, and link typography in `@layer anta`. | You use another reset and typography. |
+| `@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. |
@@ -60,9 +60,16 @@ seed-derived default palette or provide your own theme.
 
 ### Cascade layers
 
-Anta's reset and element CSS live in `@layer anta`. `tokens.css` declares
-`@layer base, anta, components, utilities`, placing Anta above preflight resets
-and below your component and utility layers.
+Anta's reset and element CSS use child layers inside `@layer anta`. `tokens.css`
+orders them above preflight resets and below your component and utility layers:
+
+```css
+@layer base, anta, components, utilities;
+@layer anta.reset, anta.components, anta.theme;
+```
+
+`anta.theme` lets the optional reference palette replace component formulas. The
+outer `anta` layer keeps its public cascade position.
 
 To change that order, declare it in CSS loaded **before** `tokens.css`. The
 first declaration fixes a layer's position:
@@ -84,7 +91,7 @@ Token custom properties stay unlayered so they apply everywhere.
 > Unlayered styles beat layered ones regardless of specificity. This reset
 > overrides Anta's element defaults. Delete the duplicate, or put your reset in
 > `@layer base { … }`; `reset.css` already applies the same universal reset in
-> `@layer anta`.
+> `@layer anta.reset`.
 
 ## Registering elements
 
@@ -213,25 +220,39 @@ specifier with a bundler or import map.
 
 ## Dark mode
 
-Add the `dark` class to any ancestor element:
+For a page-wide dark mode, add `dark` to `html`. The `body` `--bg-2` background
+then paints the browser canvas, and the root controls scrollbar colors:
 
 ```html
-<div class="dark">
-  <Progress value={50} />
-</div>
+<html class="dark">
+  <body>
+    <Progress value={50} />
+  </body>
+</html>
 ```
 
+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 a 15px root size (`1rem = 15px`).
+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.
 
-To use your own fonts, register `@font-face` declarations and override the variables:
+Register application-owned fonts, then override the font variables. This example
+uses separate Roman and Italic variable files:
 
 ```css
 @font-face {
   font-family: "App Sans";
-  src: url("/path/to/your/sans.woff2") format("woff2");
-  /* ... */
+  src: url("/fonts/app-sans-roman.woff2") format("woff2");
+  font-style: normal;
+  font-weight: 100 900;
+}
+
+@font-face {
+  font-family: "App Sans";
+  src: url("/fonts/app-sans-italic.woff2") format("woff2");
+  font-style: italic;
+  font-weight: 100 900;
 }
 
 :root {
@@ -240,6 +261,30 @@ To use your own fonts, register `@font-face` declarations and override the varia
 }
 ```
 
+Anta's semantic italics (`em`, `i`, `var`, and `dt`) select the Italic face.
+
+### Variable slant
+
+A variable font with a standard `slnt` axis can provide both instances. Expose it
+through `font-style: oblique` instead of setting `slnt` on italic elements:
+
+```css
+@font-face {
+  font-family: "App Variable";
+  src: url("/fonts/app-variable.woff2") format("woff2");
+  font-style: oblique 0deg 12deg;
+  font-weight: 100 900;
+  font-stretch: 75% 100%;
+}
+
+:root {
+  --sans-serif: "App Variable", sans-serif;
+}
+```
+
+The browser selects `0deg` for normal text and `11deg` for semantic italics. Use
+the range your font declares to avoid combining `slnt` with a synthetic oblique.
+
 ## Browser support
 
 Anta targets evergreen browsers and ships **no baseline polyfills**. Its floor is [custom-element states](https://developer.mozilla.org/en-US/docs/Web/API/CustomStateSet), used throughout the components for their internal CSS state, alongside the [Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API):