@antadesign/anta 0.3.24 → 0.3.26

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):

package/docs/normalization.md

@@ -1,12 +1,10 @@
 # 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>`.
+`reset.css` gives plain HTML (`<h2>`, `<ul>`, `<a>`, `<table>`) the same baseline as
+Anta components.
 
-It's a **separate import**, and every rule lives in a single cascade layer
-(`@layer anta`), so it is easy to override individual rules or use a different
-reset. Omit this import when another reset provides the baseline.
+It is a separate import in `@layer anta.reset`. Override individual rules, or omit
+it when another reset provides the baseline.
 
 ```js
 import '@antadesign/anta/tokens.css'   // design tokens
@@ -18,6 +16,9 @@ import '@antadesign/anta/elements'      // web components (client-side only)
 
 ### Structural reset
 
+- `html` uses `--sans-serif`, `--text-2`, 22px leading, and `color-scheme`.
+  `.dark` selects dark mode; `.light` restores it in a dark subtree. `body` paints
+  `--bg-2`, including the browser canvas.
 - `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.
@@ -28,21 +29,31 @@ import '@antadesign/anta/elements'      // web components (client-side only)
 
 ### Typography (Anta's opinion)
 
-This is **not** a neutral normalize — these defaults make raw markup match the components.
+These defaults make raw markup match Anta 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.
+- **Headings** match `<Title level={n}>` and have document margins. `<Title>` remains margin-free.
+- **Block rhythm:** `p`, `ul`, `ol`, `blockquote`, `dl`, `pre`, and `figure` have a
+  `1rem` bottom margin, removed on a last child. `table` and `hr` have no reset margin.
 - `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.
+- Inline `code` → a tone-aware `--monospace` pill. `line-height: 1em` preserves the
+  surrounding line box; `pre code` has no pill.
 - **Lists** (`ul` / `ol`): `3ch` left padding so markers hug the text; a small bottom margin between items; markers toned to `--text-5`.
+- **Blockquotes** → a 3px `--text-5` rule on the left with `2ch` total left inset.
+- `mark` → a theme-specific yellow with near-black text.
+- `del` → `--text-2-critical` with a strike; `ins` → `--text-2-success` without an underline.
+- `var` and `dt` → italic at `font-weight: 600`.
+- `small` and `figcaption` → `calc(13em / 15)`; `figcaption` also uses `--text-3`.
+- `sub` / `sup` → 75% with relative offsets that preserve line height.
+- `hr` → a 1px `--border-4` line.
+- `pre` → a bordered `--bg-3` code surface with horizontal scrolling.
 - `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 color, 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.
+See `src/reset.css` for the full set. Heading values are duplicated in
+`src/elements/a-title.css` and kept in sync.
 
 ## Cascade layers — how to override
 
@@ -50,30 +61,26 @@ Anta declares this layer order once (in `tokens.css`):
 
 ```css
 @layer base, anta, components, utilities;
+@layer anta.reset, anta.components, anta.theme;
 ```
 
-Everything Anta ships — this reset **and** the element styles — lives in **`@layer anta`**. That placement is deliberate:
+Anta uses child layers inside `@layer anta`: `anta.reset`, `anta.components`, and
+the optional `anta.theme`.
 
 - **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.
+> **Don't add an unlayered universal reset.** It overrides Anta's element defaults.
+> Anta already applies `box-sizing` and `margin: 0`; delete duplicates, or put your
+> reset in `@layer base`.
 
 ### 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 */
+/* wins over Anta's @layer anta.reset — no !important */
 h2 { letter-spacing: -0.01em; }
 ```
 
@@ -95,8 +102,10 @@ Or import both and override only the pieces you want (unlayered, or in a later l
 
 ## 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.
+The reset gives headings, lists, links, and tables the same baseline as Anta
+components. Omit it when your own reset should control them.
+
+Tags styled by the reset, rendered live.
+
+`abbr`, `q`, and `cite` keep browser typographic styles. `dd` has no browser indent
+because the reset clears margins. The reset adds no `kbd` typography.

package/docs/theming.md

@@ -23,6 +23,9 @@ Anta's palette is generative. Every color in the system derives from six tone se
 }
 ```
 
-Past the seeds, any look and feel is reachable. Anta's styles live in `@layer anta`, so an un-layered rule you write wins without `!important`, and shadow-DOM components expose `::part(...)` hooks. Per component, the `tone` prop takes a named tone or any CSS color and derives that component's full rest/hover/active curve from it. Each component page lists its own hooks under Styling.
+Anta's styles use ordered child layers inside `@layer anta`. Your unlayered CSS
+overrides them without `!important`, and shadow-DOM components expose
+`::part(...)`. A component's `tone` accepts a named tone or CSS color and derives
+its rest, hover, and active values. Each component page lists its styling hooks.
 
 The lab below shows the derivation live. For each toned component, the shipped Default sits next to a Custom preview driven by the seed picker, with the formula constants editable and the resolved CSS shown.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antadesign/anta",
-  "version": "0.3.24",
+  "version": "0.3.26",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -62,7 +62,7 @@
     "dev:run": "echo $$ > \"$ANTA_DEV_PID_FILE\"; trap 'rm -f \"$ANTA_DEV_PID_FILE\"' EXIT; pnpm run build:dev && pnpm --filter @antadesign/stickers run build:dev && pnpm --filter anta-site run docs && (node scripts/dev-watch.mjs & pnpm --filter anta-site run dev:server & wait)",
     "stop": "node scripts/dev-stop.mjs",
     "typecheck": "tsc --noEmit -p src/tsconfig.json",
-    "lint": "node scripts/lint-getters.mjs",
+    "lint": "node scripts/lint-getters.mjs && node scripts/lint-css-layers.mjs",
     "verify": "pnpm run lint && pnpm run typecheck && pnpm --filter anta-site run docs:api",
     "icons": "node scripts/generate-icons.mjs --input src/elements/icons --output src/elements --name a-icon.shapes --internal",
     "clean": "rm -rf dist",