@antadesign/anta 0.3.23 → 0.3.25

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.23",
+  "version": "0.3.25",
   "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",