@antadesign/anta 0.3.18 → 0.3.19

package/docs/components/tooltip.md

@@ -0,0 +1,177 @@
+# Tooltip
+
+A small floating bubble that describes the element it's placed inside. Render
+`<Tooltip>` as a child of the element it annotates — it doesn't affect that
+element's layout, and its content can be anything.
+
+It shows on hover (after a short `delay`) and on keyboard focus, and dismisses
+on mouse leave, blur, Esc, or when the anchor scrolls away. On touch
+devices — where there's no hover and a tap shouldn't surface it — it opens on
+**press-and-hold** and lingers briefly after you lift, so it stays readable. By
+default the bubble is **pinned** under the anchor; pass `follow` to make it
+**track the cursor** (fading out as the cursor moves away), or `interactive` to
+make it hoverable and clickable (for content like links).
+
+When the anchor implements **`getAnchorRect(): DOMRect`**, the bubble positions
+against that rect instead of the anchor's full box. Anta's `Input` reports its
+field box, so a tooltip on an `<Input>` points at the field, not the surrounding
+label or hint.
+
+## Examples
+
+```tsx
+// Place <Tooltip> inside the element it describes; hover or focus the anchor.
+// Pinned under the anchor by default — prefer the top side here (auto-flips
+// down when there's no room).
+<span style={{ cursor: 'help' }}>
+  Status
+  <Tooltip placement="top">Last checked 2 minutes ago</Tooltip>
+</span>
+
+// A near-instant tooltip on a keyboard-focusable button. Never use delay={0} — use ~50.
+<Button priority="tertiary" underline="dashed" label="Focus me with the keyboard">
+  <Tooltip delay={50}>Shows on focus, dismiss with Esc</Tooltip>
+</Button>
+
+// `follow` tracks the cursor and fades by distance as you move away.
+<Button label="Follow the cursor">
+  <Tooltip follow>Tracks the pointer, fades as you leave</Tooltip>
+</Button>
+
+// Rich content — render anything.
+<Button icon="info">
+  <Tooltip placement="top">
+    <strong>Heads up</strong> — this action can't be undone
+  </Tooltip>
+</Button>
+
+// Interactive: the bubble becomes hoverable + clickable, so its content
+// (links, buttons) works. Always pinned — a bubble that follows the cursor
+// can't be entered, so `interactive` ignores `follow`. Move from the anchor
+// into the bubble to click; press Esc to dismiss.
+<Button label="Interact">
+  <Tooltip interactive placement="top">
+    See the <a href="/guide">full guide</a> for details
+  </Tooltip>
+</Button>
+```
+
+The underlying `<a-tooltip>` works in plain HTML too, as a child of any element:
+
+```html
+<button>
+  Publish
+  <a-tooltip>Makes the draft public</a-tooltip>
+</button>
+```
+
+### Adjacent and nested tooltips
+
+Only one tooltip shows at a time. Moving between **adjacent** anchors hands off
+cleanly — the outgoing bubble cross-fades out as the next fades in (no blink).
+With `follow` tooltips (used below to show it), the outgoing bubble also keeps
+trailing the cursor and fades by distance from its anchor (transparent by ~100px
+away), so a near hop reads as a smooth cross-fade and a far one is already gone.
+With **nested** anchors, the inner (descendant) tooltip wins while you're over
+it, and the outer takes back over when you leave. Hover the examples to feel it.
+
+```tsx
+// Adjacent — moving from one to the next cross-fades, no blink. `follow` adds
+// the cursor-trailing + distance fade so the hand-off is most visible.
+<Button label="First"><Tooltip follow>First tooltip</Tooltip></Button>
+<Button label="Second"><Tooltip follow>Second tooltip</Tooltip></Button>
+
+// Nested — wrap stray text in a <span> so the tooltip stays a direct child of
+// the box (its anchor). The inner tooltip wins while you're over the inner button.
+<div tabIndex={0}>
+  <span>Outer box</span>
+  <Tooltip follow>Outer tooltip</Tooltip>
+  <Button label="Inner button"><Tooltip follow>Inner tooltip</Tooltip></Button>
+</div>
+```
+
+### Show only when truncated
+
+Pass **`truncatedOnly`** and the tooltip appears only when its target's text is
+actually ellipsized — a label that fits gets no tooltip. The check is a UI-thread
+layout read, re-measured on each hover (so resizing the container flips it live). By
+default it measures the nearest Anta ellipsizing label (`a-tab-label` /
+`a-button-label`) inside the anchor, then the anchor itself; point it elsewhere with
+**`truncatedSelector`**. Hover both — only the clipped one reveals its full text:
+
+```tsx
+{/* Only the clipped span shows a tooltip. The anchor IS the clipping box here,
+    so no selector is needed; inside a tab or <Button> the default finds the label. */}
+<span style={{ maxWidth: 130, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>
+  A long label that gets truncated
+  <Tooltip truncatedOnly>A long label that gets truncated</Tooltip>
+</span>
+```
+
+### Empty tooltips
+
+A tooltip with nothing to show — no element children and no non-whitespace text —
+doesn't open, so `<Tooltip>{maybeEmpty}</Tooltip>` never flashes a blank bubble. This
+is automatic (no prop) and re-checked on each hover, so a tooltip whose content
+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
+
+| 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 behaviour, 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 the nearest
+ Anta ellipsizing label part (`<a-tab-label>` / `<a-button-label>`) inside
+ the anchor, then the anchor itself — override with `truncatedSelector`. |
+| `truncatedSelector?` | string | — | CSS selector (resolved within the anchor) for the element whose overflow
+ decides whether a `truncatedOnly` tooltip shows. |
+
+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.
+
+Place `<a-tooltip>` inside the element it describes.
+
+```html
+<a-button role="button" tabindex="0" priority="secondary">
+  <a-button-label>Publish</a-button-label>
+  <a-tooltip>Make the draft public</a-tooltip>
+</a-button>
+```
+
+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
+typography), so it ignores the anchor's styling; to restyle the text, put a class on
+the content you pass to `<Tooltip>` and target that (a rule on the content wins over
+the baseline). Both together — hover the button to see it; the classes are just for
+the demo:
+
+```css
+/* the bubble box — a shadow part */
+a-tooltip.fancy::part(bubble) {
+  background: #1a161d;
+  border-radius: 10px;
+  padding: 8px 12px;
+  box-shadow: 0 4px 18px rgba(0, 0, 0, 0.35);
+  backdrop-filter: none;            /* opt out of the frost */
+}
+/* the slotted content — a class on what you pass to <Tooltip> */
+.tip-rich { color: #fff; font-size: 15px; font-weight: 600; letter-spacing: 0.01em; }
+```

package/docs/credits.md

@@ -0,0 +1,22 @@
+# Credits
+
+## Consumers
+
+Anta is the design system behind Antithesis, its primary and main consumer.
+
+## Maintainers
+
+- Vlad Korobov — designer, engineer, manager
+- Ksenia Toloknova — lead designer
+- Leonid Kniazev — contributing designer
+- Vehbi Karaagac — engineer
+
+## Icons
+
+Anta's icon set is built on the shoulders of several excellent open-source icon libraries. We're grateful to the maintainers and contributors of these projects:
+
+- Lucide — the modern, beautifully consistent icon family that supplies the majority of Anta's icons (ISC license).
+- Feather — the predecessor that Lucide forked from; a portion of icons trace their lineage back to Cole Bemis's original strokes (MIT license).
+- Blueprint by Palantir — additional product-UI glyphs covering domains the previous two don't (Apache License 2.0).
+
+Full license texts and per-icon attribution are reproduced verbatim in the package's NOTICES.md.

package/docs/index.md

@@ -0,0 +1,52 @@
+# Anta documentation
+
+Anta is designed for a clean DOM. Prefer the props and attributes exposed by each component over custom `className` or `style` definitions. Learn about Anta components from the documentation links and use them whenever they meet the need. For example, use `<Title>` instead of `<h1>` through `<h6>`, `<Text>` instead of a styled `<div>` or `<p>`, and `<Tooltip>` instead of an element's `title` attribute. Refer to each component's documentation page to learn about configuration, customization, and styling.
+
+## Documentation
+
+- [Overview](./overview.md)
+- [Comparison](./comparison.md)
+- [Install & Config](./install-config.md)
+- [Normalization](./normalization.md)
+- [Colors](./colors.md)
+- [Theming](./theming.md)
+- [Accessibility](./accessibility.md)
+- [Credits](./credits.md)
+- [Changelog](./changelog.md)
+
+## Components
+
+- [Title](./components/title.md)
+- [Text](./components/text.md)
+- [Tag](./components/tag.md)
+- [Tooltip](./components/tooltip.md)
+- [Icon](./components/icon.md)
+- [Loader](./components/loader.md)
+- [Progress](./components/progress.md)
+
+- [Button](./components/button.md)
+- [Checkbox](./components/checkbox.md)
+- [Radio](./components/radio.md)
+- [Switch](./components/switch.md)
+- [Slider](./components/slider.md)
+- [Tabs](./components/tabs.md)
+
+- [Expander](./components/expander.md)
+- [Menu](./components/menu.md)
+
+- [Input](./components/input.md)
+- [InputAutocomplete](./components/input-autocomplete.md)
+- [InputDate](./components/input-date.md)
+- [InputTime](./components/input-time.md)
+- [Select](./components/select.md)
+- [SelectFaceted](./components/select-faceted.md)
+
+- [Banner](./components/banner.md)
+- [Card](./components/card.md)
+- [Dialog](./components/dialog.md)
+- [Toaster](./components/toaster.md)
+
+## Packages
+
+- [Table](./packages/table.md)
+- [Stickers](./packages/stickers.md)

package/docs/install-config.md

@@ -0,0 +1,240 @@
+# Install & Config
+
+## Installation
+
+```sh
+npm install @antadesign/anta   # or pnpm / bun
+```
+
+Pin an exact version in `package.json` (`"@antadesign/anta": "0.3.16"`) instead
+of a floating tag such as `"latest"`.
+
+### Usage
+
+```tsx
+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 { Progress } from '@antadesign/anta'
+
+<Progress value={42} label="Uploaded" hint="3 of 7" />
+```
+
+### What you import (and why)
+
+Tokens, elements, and the JSX layer render a styled component. The reset is
+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/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/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. |
+
+Load `tokens.css` before element CSS. Elements read its variables; without it,
+they render unstyled.
+
+### 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.
+
+To change that order, declare it in CSS loaded **before** `tokens.css`. The
+first declaration fixes a layer's position:
+
+```css
+/* your global.css, loaded before anta */
+@layer reset, anta, my-components, utilities;
+```
+
+Token custom properties stay unlayered so they apply everywhere.
+
+> **Gotcha: an unlayered hard reset defeats Anta's element rules.**
+>
+> ```css
+> *, *::before, *::after { box-sizing: border-box; }
+> * { margin: 0; }
+> ```
+>
+> 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`.
+
+## Registering elements
+
+JSX wrappers render `<a-*>` tags. Register their classes before those tags reach
+the DOM. Registration needs `HTMLElement`, so the import is a no-op in Node.js
+and Worker threads.
+
+```ts
+import '@antadesign/anta/elements'  // auto-registers all elements
+```
+
+`/elements` registers everything. Per-element entries register one element and
+load only its CSS:
+
+```ts
+import '@antadesign/anta/elements/a-tooltip'  // only <a-tooltip> + its CSS
+import '@antadesign/anta/elements/a-button'   // only <a-button> + its CSS
+```
+
+Both are idempotent, side-effect imports and safe during SSR.
+
+Use a static import in your app entry, outside components and hooks:
+
+```ts
+// src/main.tsx (or wherever your root render lives)
+import '@antadesign/anta/elements'
+import { createRoot } from 'react-dom/client'
+import App from './App'
+createRoot(document.getElementById('root')!).render(<App />)
+```
+
+Module initialisation registers the classes before the first render, avoiding a
+flash of un-upgraded elements.
+
+> **Why not `useEffect(() => import('@antadesign/anta/elements'), [])`?**
+> `useEffect` runs after paint and the import resolves later. The browser can
+> paint unregistered elements first. `useLayoutEffect` is still asynchronous and
+> warns during SSR hydration.
+
+Choose the entry point for your runtime:
+
+- **Plain HTML or static sites:** a `<script type="module">` in the document head.
+- **Astro or Next.js:** a client-only script. In Astro, use
+  `<script>import '@antadesign/anta/elements'</script>`; in Next.js, import it
+  from a `'use client'` file.
+- **Worker-rendered UI:** the UI-thread bootstrap that owns the DOM. A Worker
+  has no `HTMLElement`.
+
+## Framework setup
+
+### React
+
+Works out of the box.
+
+### Preact with compat
+
+If your bundler aliases `react` to `preact/compat`, Anta works without setup.
+
+### Preact without compat
+
+Call `configure()` before rendering any anta components:
+
+```ts
+import { configure } from '@antadesign/anta'
+import { h, Fragment } from 'preact'
+configure(h, Fragment)
+```
+
+### TypeScript: typing raw `<a-*>` tags in JSX
+
+JSX wrappers such as `<Button>` and `<Progress>` need no extra typing. Configure
+JSX only when you write raw `<a-*>` tags.
+
+**Option A (preferred)** — point JSX types at Anta in `tsconfig.json`:
+
+```jsonc
+{ "compilerOptions": { "jsx": "react-jsx", "jsxImportSource": "@antadesign/anta" } }
+```
+
+Every `a-*` tag type-checks, standard HTML tags keep working, and importing
+`@antadesign/stickers` adds its tags automatically.
+
+**Option B** — if `jsxImportSource` cannot change, merge Anta's tag map into
+your JSX namespace with `AntaIntrinsicElements` (and `StickerIntrinsicElements`
+when needed):
+
+```ts
+import type { AntaIntrinsicElements } from '@antadesign/anta'
+import type { StickerIntrinsicElements } from '@antadesign/stickers' // only if you use stickers
+
+declare global {
+  namespace JSX {
+    interface IntrinsicElements extends AntaIntrinsicElements, StickerIntrinsicElements {}
+  }
+}
+```
+
+With `@types/react` 18+ and `jsx: "react-jsx"`, JSX is module-scoped. Extend
+the `react` module instead:
+
+```ts
+import type { AntaIntrinsicElements } from '@antadesign/anta'
+
+declare module 'react' {
+  namespace JSX {
+    interface IntrinsicElements extends AntaIntrinsicElements {}
+  }
+}
+```
+
+Both options reject unknown tags and invalid props. New tags arrive with Anta
+upgrades; there is no per-tag list to maintain.
+
+### Raw web components (no JSX)
+
+Elements also work in plain HTML. Registration loads their CSS; resolve the bare
+specifier with a bundler or import map.
+
+```html
+<script type="module">
+  import '@antadesign/anta/elements'
+</script>
+
+<a-progress value="42" max="100" tone="info"></a-progress>
+```
+
+## Dark mode
+
+Add the `dark` class to any ancestor element:
+
+```html
+<div class="dark">
+  <Progress value={50} />
+</div>
+```
+
+## 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`).
+
+To use the Antithesis fonts, register your own `@font-face` declarations and override the variables:
+
+```css
+@font-face {
+  font-family: "Antithesis sans";
+  src: url("/path/to/your/sans.woff2") format("woff2");
+  /* ... */
+}
+
+:root {
+  --sans-serif: "Antithesis sans", sans-serif;
+  --monospace: "Antithesis mono", monospace;
+}
+```
+
+## 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):
+
+| Browser | Minimum version |
+| --- | --- |
+| Chrome / Edge | 125 (May 2024) |
+| Safari | 17.4 (Mar 2024) |
+| Firefox | 126 (May 2024) |
+
+This is [Baseline 2024](https://web.dev/baseline). Anta also relies on relative
+OKLCH, `:has()`, `dvh`, cascade layers, and constructable shadow DOM. Older
+browsers can fail hard, including `:state()` being unrecognized or
+`showPopover()` throwing. Gate Anta on your own support matrix when you support
+older browsers.
+
+Two features progressively enhance with fallbacks: `checkVisibility()` falls
+back to `getClientRects()`, and typed CSS `attr()` supports raw
+`<a-icon size>` in Chrome 133+ and Safari 18.2+. Elsewhere use `<Icon size>`
+or `--icon-size`.

package/docs/normalization.md

@@ -0,0 +1,105 @@
+# Normalization
+
+Anta ships an opinionated reset + typography baseline in **`reset.css`**, so plain
+HTML (`<h2>`, `<ul>`, `<a>`, `<table>`…) renders in the same visual language as the
+components — no per-page restyling to make prose match a `<Title>` or a `<Table>`.
+
+It's a **separate import**, and every rule lives in a single cascade layer
+(`@layer anta`), so it's easy to layer your own reset around it or override any
+piece. If you'd rather bring your own reset, just don't import this one.
+
+```js
+import '@antadesign/anta/tokens.css'   // design tokens
+import '@antadesign/anta/reset.css'     // ← this page (optional)
+import '@antadesign/anta/elements'      // web components (client-side only)
+```
+
+## What it normalizes
+
+### Structural reset
+
+- `box-sizing: border-box` on every element (and `::before` / `::after`).
+- `margin: 0` on everything — apps build spacing from explicit values.
+- Replaced elements (`img`, `picture`, `video`, `canvas`, `svg`) → `display: block` + `max-width: 100%`, so a stray large asset can't blow out the layout.
+- Form controls (`input`, `button`, `textarea`, `select`) → `font: inherit`.
+- Keyboard-focused elements → a 1px `--focus-ring` outline. Component-specific
+  focus styles keep their own geometry.
+- `overflow-wrap: break-word` on paragraphs + headings; `text-wrap: pretty` on `<p>` and `text-wrap: balance` on headings.
+
+### Typography (Anta's opinion)
+
+This is **not** a neutral normalize — these defaults make raw markup match the components.
+
+- **Headings** adopt the exact scale of `<Title level={n}>` — `h1`–`h6` sizes, line-heights, weight `≈585`, `letter-spacing: 0`, color `--text-1` (kept in lockstep with `a-title.css`) — plus per-level block margins for document rhythm. Those margins live only on the raw headings: `<Title>` itself is margin-free and leaves spacing to its container, so running prose gets the rhythm while the component stays neutral.
+- `strong` → `font-weight: 600`.
+- `dfn` (defined term) → non-italic, with a dotted underline at half the surrounding text's strength (`3px` offset) in place of the UA italic. No `cursor: help` — that's for where the term is actually hoverable.
+- Inline `code` → `line-height: 1em` so it doesn't inflate the line box of surrounding prose.
+- **Lists** (`ul` / `ol`): `3ch` left padding so markers hug the text; a small bottom margin between items; markers toned to `--text-5`.
+- `menu` is stripped to a clean semantic container (no disc markers / default padding).
+- **Links** get `--link-color` with a hairline underline (75% alpha, `0.5px`); hover only thickens it to `1px` (no color repaint). Anchor-buttons (`<a role="button">`) are excluded so they keep button styling.
+- `::selection` → the focus-ring colour, tuned per theme (20% alpha in light, 30% in dark).
+- **Tables**: `border-collapse`, `tabular-nums`, and a polite cell baseline; opt into a framed look with `<table data-bordered>` (outer frame + column dividers + rounded corners).
+
+Everything above is defined in `src/reset.css`, inside `@layer anta` — read that file
+for the authoritative set (it's short and commented). The headings block is duplicated
+in `src/elements/a-title.css`; the two are kept in sync.
+
+## Cascade layers — how to override
+
+Anta declares this layer order once (in `tokens.css`):
+
+```css
+@layer base, anta, components, utilities;
+```
+
+Everything Anta ships — this reset **and** the element styles — lives in **`@layer anta`**. That placement is deliberate:
+
+- **Above `base`** — a framework preflight you drop into `@layer base` (e.g. Tailwind) won't wipe Anta's typography.
+- **Below `components` and `utilities`** — your own component or utility CSS overrides Anta with no specificity battles.
+- **Unlayered CSS beats every layer** — so any plain rule you write already wins over Anta's reset, no `!important` needed.
+
+> **Gotcha — don't re-add a _universal_ hard reset unlayered.** Overriding a
+> *specific* element unlayered is the intended escape hatch (below). But a blanket
+> `* { margin: 0 }` / `*, *::before, *::after { box-sizing: border-box }` left
+> **unlayered** also outranks Anta's *per-element* defaults — its `p`, `caption`,
+> and `ul / ol` margins — because unlayered wins over `@layer anta` regardless of
+> specificity. Anta already runs that universal `*` reset itself, inside
+> `@layer anta`, so the copy-pasted duplicate is redundant *and* harmful: delete it,
+> or if you keep your own reset wrap it in `@layer base { … }` (below `anta`) so
+> Anta's element defaults still apply.
+
+### Override one thing
+
+Write the rule unlayered (or in a layer after `anta`) — targeting a **specific** element, not `*`:
+
+```css
+/* wins over Anta's @layer anta reset — no !important */
+h2 { letter-spacing: -0.01em; }
+```
+
+### Bring your own reset
+
+Because `reset.css` is a separate import, you can simply **not import it** and let your
+own reset govern typography — keep the tokens and elements:
+
+```js
+import '@antadesign/anta/tokens.css'   // keep — tokens
+import '@antadesign/anta/elements'      // keep — components
+// no '@antadesign/anta/reset.css'      // your reset is in charge
+```
+
+**One dependency to keep:** Anta's elements don't set their own `box-sizing` — they
+assume the global `* { box-sizing: border-box }` that this reset provides. Every common
+reset (normalize.css, Tailwind's preflight, etc.) sets it too, so swapping resets is
+normally seamless; but if yours doesn't, keep that one rule or component padding,
+`max-width`, and icon-button sizing will be slightly off.
+
+Or import both and override only the pieces you want (unlayered, or in a later layer).
+
+## Why it's opinionated
+
+A blank-slate reset would leave headings, lists, links, and tables looking like raw
+browser defaults — out of step with the components beside them. Anta's reset instead
+gives plain markup the same baseline as `<Title>`, `<Table>`, and the link styles, so a
+page mixing prose and components reads as one system. When you want a clean slate, opt
+out above.

package/docs/overview.md

@@ -0,0 +1,10 @@
+# Overview
+
+Anta is Antithesis's design system. It combines global CSS tokens,
+framework-agnostic declarative web components, and JSX wrappers for dynamic
+state and conditional composition.
+
+Components use an attribute-driven DOM instead of utility-class stacks and
+wrapper elements. Web components never mutate their own attributes, so they
+work with Worker-driven UIs and other reactive renderers. JSX wrappers provide
+the React and Preact integration layer.