@signal9/era-ui 10.0.0 → 11.0.0

package/dist/generated-docs/utilities.md

@@ -9,7 +9,7 @@ never the `h-(--era-h-control)` var-class spelling. Everything below rides along
 with the stylesheet and needs no import:
 
 ```ts
-import "@sig-nine/era-ui/css";
+import "@signal9/era-ui/css";
 ```
 
 ```svelte
@@ -23,7 +23,7 @@ motion):
 
 | Stock-looking class | What it resolves to |
 |---|---|
-| `rounded-icon/xxs/sm/md/lg` | the concentric radius ladder (collapses on `data-corners="square"`) |
+| `rounded-icon/pill/chip/control/bar` | the concentric radius ladder (collapses on `data-corners="square"`) |
 | `rounded-menu-item` | menu-row radius, concentric inside a `rounded-control` panel |
 | `shadow` / `shadow-lg` | resting control edge / floating panel chrome, per surface |
 | `shadow-well` / `shadow-pressed` / `shadow-highlight` | recessed, pressed/latched, hover-material chrome |
@@ -31,10 +31,21 @@ motion):
 | `transition-*` (bare) | duration + easing default to the motion axis |
 | `ease-base` / `duration-base` | the motion axis, named explicitly |
 | `text-body` | density-derived body/control text size |
-
-Deliberate gaps: `w-*`/`min-w-*` tier names would shadow Tailwind's container
-scale (`min-w-md` stays 28rem), and the concentric-inset tokens are advanced
-enough to stay var-form — `min-w-(--era-h-control)` etc. remain the escape hatch.
+| `p-gutter` / `gap-gutter` / `mt-gutter` / … | the spacing scale — EVERY spacing prefix works |
+
+The spacing names (`gutter`, `card`, `panel`, `content`, `menu`, `field`, the
+`inset-*` and concentric `*-inset-*` insets, `glyph-*`) are registered as a
+Tailwind spacing scale, so every prefix derives automatically: `p-`, `px-`,
+`pt-`, `mt-`, `gap-`, `gap-x-`, `inset-`, `translate-`, and the rest. The TIER
+names (`icon`, `pill`, `chip`, `control`, `bar`) are heights, not spacing, so
+they are registered per prefix instead — `h-`, `w-`, `min-h-`, `min-w-` and
+`size-` — and the two vocabularies deliberately share no word. Putting a tier
+in the spacing scale would silently make `px-control` mean 24px of padding.
+
+The var form (`h-(--era-h-control)`) still works and is the escape hatch for a
+token with no registered name — `--era-sp`, the press-sink offsets, anything
+a component reaches for once. `scripts/check-canonical.ts` fails the build if
+source uses it where a name exists.
 
 | Utility | Use it for |
 |---|---|
@@ -44,20 +55,33 @@ enough to stay var-form — `min-w-(--era-h-control)` etc. remain the escape hat
 | `era-text-trim` | vertically center single-line control text (a label beside an icon, a button's own text) without a translateY nudge. Fixed-height, non-editable elements ONLY: never on an <input>/<textarea>, and never on the same element as `truncate` or any overflow clip — put it on the fixed-height ROW and let the truncating child centre inside it. See era-text-trim-caps for ALL-CAPS. |
 | `truncate` | single-line horizontal truncation with an ellipsis — put it on the truncating CHILD inside a trimmed or leading-none row, never on the same element as era-text-trim; it will not clip ascenders or descenders. |
 | `era-text-trim-caps` | the era-text-trim variant for ALL-CAPS single-line strings (kbd hints, acronym badges) — never for mixed-case text (a label like "System" reads high; use era-text-trim), and never on the same element as `truncate`. |
-| `era-token-ink` `era-ink-center` | the ink centring for a token pill — a badge, a KV value, any short caps-or-digits label in a fixed-height box; it needs no icon sibling (with one the box must stay flex, and the general trim applies). |
+| `era-ink-center` | on a native single-line <input> (or the text layer that must mirror one) inside a fixed-height field — never alongside era-text-trim. |
+| `era-token-ink` | the ink centring for a token pill — a badge, a KV value, any short caps-or-digits label in a fixed-height box, CENTRED horizontally and with no icon sibling. For a left-aligned sentence-case label use era-label-ink; when an icon really must sit beside the text, see the note there. |
+| `era-label-ink` | the ink centring for a fixed-height control holding ONE line of sentence-case text and no icon — a menu item, a nav trigger, a button label. Never alongside `truncate` (the trimmed box becomes the clip). |
 | `era-shimmer` | the in-progress text treatment — put it on a "working…" / "thinking…" label while a task streams, instead of a spinner beside the text. |
 | `era-collapse` | the height sweep for a bits-ui Collapsible.Content — put it on the Content element itself (it carries its own overflow: hidden). |
 | `h-icon` `h-pill` `h-chip` `h-control` `h-bar` | the tier-height ladder — h-icon (icon) · h-pill (nested pill) · h-chip (standalone pill) · h-control (control) · h-bar (bar); the named form of h-(--era-h-*). |
 | `min-h-icon` `min-h-pill` `min-h-chip` `min-h-control` `min-h-bar` | minimum tier height for containers that may grow — a bar that is at least lg-tier but can wrap (min-h-bar). |
+| `w-icon` `w-pill` `w-chip` `w-control` `w-bar` | a tier-sized WIDTH — the horizontal twin of the h-* ladder, for a rail or a column measured in tiers rather than in content. |
+| `min-w-icon` `min-w-pill` `min-w-chip` `min-w-control` `min-w-bar` | a minimum tier WIDTH — the floor that makes a single-glyph control render as a square rather than a skinny pill (min-w-control on an icon button, min-w-pill on a badge). These could not exist before the ladder was renamed: the old rungs were sm/md/lg, and Tailwind's container scale already owns min-w-md and min-w-lg, so the names collided and every call site had to write min-w-(--era-h-control) by hand. icon/pill/chip/control/bar collide with nothing. |
 | `size-icon` `size-pill` `size-chip` `size-control` `size-bar` | a tier-sized square — size-icon is THE icon size (a Lucide glyph beside body text), size-control a square control face. |
-| `gap-gutter` `p-gutter` `px-gutter` `py-gutter` | the inter-element gap (sp/2) — flex/grid gap between sibling controls, and the matching gutter padding a scrollable list or rail owes its rows on all four sides (p-gutter on the rail = gap-gutter between its rows). |
-| `p-inset-pill` `p-inset-chip` `p-inset-control` `px-inset-pill` `px-inset-chip` `px-inset-control` `py-inset-pill` `py-inset-chip` `py-inset-control` | text-symmetric content padding — (tier − text)/2, the inset that vertically centers body text in its tier; px-inset-control is a text button's side padding, p-inset-control a code block's. |
-| `px-pill` `px-chip` | pill side padding — the wider-than-vertical horizontal breathing room badge/chip text wants (glyph-advance derived, ~2× the vertical inset). |
-| `px-field` | text-field side padding — where typed text starts in a control-tier input; the named form of px-(--era-field-px). |
-| `p-panel` `p-card` | optical padding for unbounded containers — p-panel for compact shells and menu-adjacent chrome, p-card for cards/dialogs/popovers, p-content for full content panels. Grows super-linearly with density so whitespace holds its perceived share as controls loosen. |
-| `p-content` | — |
-| `p-menu` | menu-panel padding — the surface-owned inset (0 on flat, 2px on glass/bevel) that keeps row highlights inside a floating panel's frame; pairs with rounded-menu-item on the rows. |
+| `px-pill` `px-chip` `pl-pill` `pr-pill` `pl-chip` `pr-chip` | pill side padding — the wider-than-vertical horizontal breathing room badge/chip text wants (glyph-advance derived, ~2× the vertical inset). |
+| `p-section` | padding for a content panel that sits UNDER a section header row — the even-padding exception, and the reason it is not called p-section: it deliberately under-pays the block start. For an evenly padded content panel use p-section, which is the plain token. |
 | `duration-base` | the motion axis as an explicit transition-duration — for the rare case a utility (not the transition-* default) needs to name it; 0s at data-motion="instant", longer at "extra". |
+| `text-body` | — |
+| `leading-body` | — |
+| `rounded-icon` `rounded-pill` `rounded-chip` `rounded-control` `rounded-bar` `rounded-menu-item` | — |
+| `shadow` | — |
+| `shadow-sm` `shadow-lg` `shadow-well` `shadow-pressed` `shadow-highlight` | — |
+| `bg-well` `text-well` `border-well` `bg-elevated` `text-elevated` `border-elevated` `bg-highlight` `text-highlight` `border-highlight` `bg-overlay` `text-overlay` `border-overlay` | — |
+| `p-gutter` `px-gutter` `py-gutter` `gap-gutter` `p-panel` `px-panel` `py-panel` `gap-panel` `p-card` `px-card` `py-card` `gap-card` `p-content` `px-content` `py-content` `gap-content` `p-menu` `px-menu` `py-menu` `gap-menu` `p-field` `px-field` `py-field` `gap-field` | — |
+| `p-inset-pill` `px-inset-pill` `py-inset-pill` `gap-inset-pill` `p-inset-chip` `px-inset-chip` `py-inset-chip` `gap-inset-chip` `p-inset-control` `px-inset-control` `py-inset-control` `gap-inset-control` | text-symmetric content padding — (tier − text)/2, the inset that vertically centres body text in its tier; px-inset-control is a text button's side padding, p-inset-control a code block's. |
+| `p-icon-inset-pill` `px-icon-inset-pill` `py-icon-inset-pill` `gap-icon-inset-pill` `p-icon-inset-chip` `px-icon-inset-chip` `py-icon-inset-chip` `gap-icon-inset-chip` `p-icon-inset-control` `px-icon-inset-control` `py-icon-inset-control` `gap-icon-inset-control` `p-icon-inset-bar` `px-icon-inset-bar` `py-icon-inset-bar` `gap-icon-inset-bar` `p-pill-inset-chip` `px-pill-inset-chip` `py-pill-inset-chip` `gap-pill-inset-chip` `p-pill-inset-control` `px-pill-inset-control` `py-pill-inset-control` `gap-pill-inset-control` `p-chip-inset-control` `px-chip-inset-control` `py-chip-inset-control` `gap-chip-inset-control` `p-chip-inset-bar` `px-chip-inset-bar` `py-chip-inset-bar` `gap-chip-inset-bar` | the concentric inset for a nested pair — (h-container − h-child)/2, the gap that makes a child control sit evenly inside its container, and the radius step that keeps their corners concentric. Named for the pair it joins: gap-icon-inset-control seats an icon in a control. |
+| `p-glyph-icon` `px-glyph-icon` `py-glyph-icon` `gap-glyph-icon` `p-glyph-pill` `px-glyph-pill` `py-glyph-pill` `gap-glyph-pill` | the glyph size for a tier — the INK inside the box, not the box (size-glyph-pill is the dismiss × in a pill, size-pill is the pill). |
+| `bg-field` `text-field` `border-field` `bg-field-highlight` `text-field-highlight` `border-field-highlight` | the recessed field fill — bg-field is a text input's resting well, bg-field-highlight its focused/hovered face. |
+| `ease-base` | — |
+| `bg-divider` `text-divider` `border-divider` `bg-divider-faded` `text-divider-faded` `border-divider-faded` `bg-background` `text-background` `border-background` `bg-foreground` `text-foreground` `border-foreground` `bg-1` `text-1` `border-1` `bg-2` `text-2` `border-2` `bg-3` `text-3` `border-3` `bg-4` `text-4` `border-4` `bg-5` `text-5` `border-5` `bg-6` `text-6` `border-6` `bg-7` `text-7` `border-7` `bg-8` `text-8` `border-8` `bg-9` `text-9` `border-9` `bg-10` `text-10` `border-10` `bg-11` `text-11` `border-11` `bg-12` `text-12` `border-12` `bg-border` `text-border` `border-border` `bg-surface` `text-surface` `border-surface` `bg-hover` `text-hover` `border-hover` `bg-fg` `text-fg` `border-fg` `bg-bright` `text-bright` `border-bright` `bg-muted` `text-muted` `border-muted` | — |
+| `bg-fill` `text-fill` `border-fill` `bg-link` `text-link` `border-link` `bg-primary` `text-primary` `border-primary` `bg-primary-fg` `text-primary-fg` `border-primary-fg` `bg-primary-hover` `text-primary-hover` `border-primary-hover` `bg-destructive` `text-destructive` `border-destructive` `bg-destructive-fg` `text-destructive-fg` `border-destructive-fg` `bg-success` `text-success` `border-success` `bg-success-fg` `text-success-fg` `border-success-fg` `bg-warning` `text-warning` `border-warning` `bg-warning-fg` `text-warning-fg` `border-warning-fg` | — |
 | `glass-blur` | the backdrop blur for a floating panel (popover, dialog, taskbar) — it applies only inside a data-surface="glass" subtree and is inert elsewhere, so it is safe to leave on a panel that renders under every surface. |
 
 ## era-interactive
@@ -235,9 +259,47 @@ Declared in `index.css`.
 }
 ```
 
-## era-token-ink · era-ink-center
+## era-ink-center
+
+**Use it for:** on a native single-line <input> (or the text layer that must mirror one) inside a fixed-height field — never alongside era-text-trim.
+
+The EDITABLE counterpart of era-text-trim — for native <input>s, which the
+trim is forbidden on (it collapses the UA's inner editor box and slices the
+glyphs; see typography/collapsed-text-trim).
+
+Without help, a tier-height input centres its text by FONT BOX, and the ui
+stacks' font box is deeply asymmetric: ascent ≈1.07em against descent
+≈0.29em. Centring that box parks the visible band (caps, x-height) ~0.115em
+LOW — so a field's text sat visibly below the trimmed label beside it.
+
+The value is OPTICAL, not the derivation's: pure x-band centring computes
+to ~0.23em of padding, but pixel-measured against real Title-Case text it
+over-lifts — the eye weighs the cap-to-baseline mass, which x-band
+centring parks ~2px high (caps 2.75px off the top against 5.7px of air
+under the baseline, measured at dense). 0.08em splits the difference
+between the x-band ideal and the cap-band ideal, landing caps ~3.7px in an
+18px field with ~4.7px under the baseline — the reading where neither
+band's partisans win and neither complains.
+
+The lift is padding, not a translateY: an icon-less Input paints the field
+chrome itself, and a transform would drag the field along with the ink.
+padding-bottom shrinks the content box from below, and a single-line input
+re-centres its line box in what remains — the ink rises by exactly half the
+padding, the chrome doesn't move, and the caret and selection follow the
+text. In em on purpose: the correction is a fraction of the type, so it
+holds across every density and text size with one value.
 
-**Use it for:** the ink centring for a token pill — a badge, a KV value, any short caps-or-digits label in a fixed-height box; it needs no icon sibling (with one the box must stay flex, and the general trim applies).
+Declared in `index.css`.
+
+```css
+@utility era-ink-center {
+	padding-bottom: 0.08em;
+}
+```
+
+## era-token-ink
+
+**Use it for:** the ink centring for a token pill — a badge, a KV value, any short caps-or-digits label in a fixed-height box, CENTRED horizontally and with no icon sibling. For a left-aligned sentence-case label use era-label-ink; when an icon really must sit beside the text, see the note there.
 
 TOKEN INK — the ink centring for a pill whose content is a TOKEN: an id, a
 count, a status, a tag. Font-independent, unlike everything it replaces.
@@ -276,9 +338,45 @@ Declared in `index.css`.
 	line-height: 1;
 	text-box: trim-both cap alphabetic;
 }
+```
 
-@utility era-ink-center {
-	padding-bottom: 0.08em;
+## era-label-ink
+
+**Use it for:** the ink centring for a fixed-height control holding ONE line of sentence-case text and no icon — a menu item, a nav trigger, a button label. Never alongside `truncate` (the trimmed box becomes the clip).
+
+LABEL INK — era-token-ink's mixed-case sibling, and the general answer to
+"this fixed-height control holds one line of text".
+
+Same mechanism, same reason: `text-box-trim` needs a BLOCK box, so the row
+becomes one and `align-content` (block-container alignment) does the
+centring. What differs is the band and the alignment, because the content
+class differs — a label is sentence case, so the x-height band is the visual
+mass to centre (cap-band reads low on "System"), and it is laid out against
+the row's padding rather than centred in it.
+
+WHY IT EXISTS AT ALL: era's controls are flex, and a flex container's bare
+text is an ANONYMOUS flex item — a box no selector reaches and no
+non-inherited property touches. So `era-text-trim` on a flex row is inert,
+contributing only its `line-height: 1`, and the ink falls back to line-box
+centring by font metrics. era-token-ink already fixed that for centred
+tokens; this fixes it for everything else.
+
+THE ICON CASE IS NOT SOLVED, and cannot be from CSS: an icon beside the text
+needs the box to stay flex, which re-creates the anonymous item. A component
+whose children are an opaque slot therefore guards it —
+`not-has-[svg]:era-label-ink` — and ink-centres the text-only case while
+leaving the icon case on line-box centring. Splitting icon and label into
+separate slots is what would close it; typography/inert-trim reports every
+site still on the fallback.
+
+Declared in `index.css`.
+
+```css
+@utility era-label-ink {
+	display: block;
+	align-content: center;
+	line-height: 1;
+	text-box: trim-both ex alphabetic;
 }
 ```
 
@@ -392,6 +490,54 @@ Declared in `index.css`.
 }
 ```
 
+## w-icon · w-pill · w-chip · w-control · w-bar
+
+**Use it for:** a tier-sized WIDTH — the horizontal twin of the h-* ladder, for a rail or a column measured in tiers rather than in content.
+
+Declared in `index.css`.
+
+```css
+@utility w-icon {
+	width: var(--era-h-icon);
+}
+@utility w-pill {
+	width: var(--era-h-pill);
+}
+@utility w-chip {
+	width: var(--era-h-chip);
+}
+@utility w-control {
+	width: var(--era-h-control);
+}
+@utility w-bar {
+	width: var(--era-h-bar);
+}
+```
+
+## min-w-icon · min-w-pill · min-w-chip · min-w-control · min-w-bar
+
+**Use it for:** a minimum tier WIDTH — the floor that makes a single-glyph control render as a square rather than a skinny pill (min-w-control on an icon button, min-w-pill on a badge). These could not exist before the ladder was renamed: the old rungs were sm/md/lg, and Tailwind's container scale already owns min-w-md and min-w-lg, so the names collided and every call site had to write min-w-(--era-h-control) by hand. icon/pill/chip/control/bar collide with nothing.
+
+Declared in `index.css`.
+
+```css
+@utility min-w-icon {
+	min-width: var(--era-h-icon);
+}
+@utility min-w-pill {
+	min-width: var(--era-h-pill);
+}
+@utility min-w-chip {
+	min-width: var(--era-h-chip);
+}
+@utility min-w-control {
+	min-width: var(--era-h-control);
+}
+@utility min-w-bar {
+	min-width: var(--era-h-bar);
+}
+```
+
 ## size-icon · size-pill · size-chip · size-control · size-bar
 
 **Use it for:** a tier-sized square — size-icon is THE icon size (a Lucide glyph beside body text), size-control a square control face.
@@ -421,155 +567,339 @@ Declared in `index.css`.
 }
 ```
 
-## gap-gutter · p-gutter · px-gutter · py-gutter
+## px-pill · px-chip · pl-pill · pr-pill · pl-chip · pr-chip
 
-**Use it for:** the inter-element gap (sp/2) — flex/grid gap between sibling controls, and the matching gutter padding a scrollable list or rail owes its rows on all four sides (p-gutter on the rail = gap-gutter between its rows).
+**Use it for:** pill side padding — the wider-than-vertical horizontal breathing room badge/chip text wants (glyph-advance derived, ~2× the vertical inset).
 
 Declared in `index.css`.
 
 ```css
-@utility gap-gutter {
-	gap: var(--era-gap);
+@utility px-pill {
+	padding-inline: var(--era-pill-px);
+}
+@utility px-chip {
+	padding-inline: var(--era-chip-px);
+}
+@utility pl-pill {
+	padding-left: var(--era-pill-px);
 }
-@utility p-gutter {
-	padding: var(--era-gap);
+@utility pr-pill {
+	padding-right: var(--era-pill-px);
 }
-@utility px-gutter {
-	padding-inline: var(--era-gap);
+@utility pl-chip {
+	padding-left: var(--era-chip-px);
 }
-@utility py-gutter {
-	padding-block: var(--era-gap);
+@utility pr-chip {
+	padding-right: var(--era-chip-px);
 }
 ```
 
-## p-inset-pill · p-inset-chip · p-inset-control · px-inset-pill · px-inset-chip · px-inset-control · py-inset-pill · py-inset-chip · py-inset-control
+## p-section
 
-**Use it for:** text-symmetric content padding — (tier − text)/2, the inset that vertically centers body text in its tier; px-inset-control is a text button's side padding, p-inset-control a code block's.
+**Use it for:** padding for a content panel that sits UNDER a section header row — the even-padding exception, and the reason it is not called p-section: it deliberately under-pays the block start. For an evenly padded content panel use p-section, which is the plain token.
+
+A content panel always follows a section header ROW, and that row already
+contributes its own slack: the heading's text sits in an h-bar bar, so there
+is (h-bar − text)/2 of empty bar under its glyphs before the panel even
+starts. Padding the panel evenly on top of that spends the space twice — the
+header ends up floating between the section above and the paragraph it
+introduces rather than binding to it.
+
+So the block-start pays only the REMAINDER. The target is the indent: the
+space under a heading should measure the same as the space beside the text,
+which is --era-pad-content. The header row already supplies (h-bar − text)/2 of
+it, so the panel adds what's left, and heading-to-paragraph reads equal to
+the paragraph's own inset. Subtracting one --era-gap (the previous rule) left
+the header's slack unaccounted for and the heading still detached.
+
+Both terms are density-derived, so the equality holds at every mode; the
+max() is the floor for a hypothetical mode where the row's slack would
+exceed the inset outright.
 
 Declared in `index.css`.
 
 ```css
-@utility p-inset-pill {
-	padding: var(--era-inset-pill);
+@utility p-section {
+	padding: var(--era-pad-content);
+	padding-top: max(0px, calc(var(--era-pad-content) - (var(--era-h-bar) - var(--era-text)) / 2));
 }
-@utility p-inset-chip {
-	padding: var(--era-inset-chip);
-}
-@utility p-inset-control {
-	padding: var(--era-inset-control);
-}
-@utility px-inset-pill {
-	padding-inline: var(--era-inset-pill);
+```
+
+## duration-base
+
+**Use it for:** the motion axis as an explicit transition-duration — for the rare case a utility (not the transition-* default) needs to name it; 0s at data-motion="instant", longer at "extra".
+
+Declared in `index.css`.
+
+```css
+@utility duration-base {
+	transition-duration: var(--era-duration);
 }
-@utility px-inset-chip {
-	padding-inline: var(--era-inset-chip);
+```
+
+## text-body
+
+Density-derived body size: `text-body` replaces text-[length:var(--era-text)]
+
+Declared in `index.css`.
+
+```css
+@theme inline {
+	--text-body: var(--era-text);
 }
-@utility px-inset-control {
-	padding-inline: var(--era-inset-control);
+```
+
+## leading-body
+
+Prose leading — `leading-body` is the pair to `text-body`, and every piece
+of text in the library that can wrap to a second line carries it. Enforced
+at runtime by typography/prose-leading.
+
+Declared in `index.css`.
+
+```css
+@theme inline {
+	--leading-body: var(--era-leading);
 }
-@utility py-inset-pill {
-	padding-block: var(--era-inset-pill);
+```
+
+## rounded-icon · rounded-pill · rounded-chip · rounded-control · rounded-bar · rounded-menu-item
+
+Radius ladder — Tailwind's own rounded-* names now walk era's concentric
+ladder (rd-T = rd-xs + (h-T − h-icon)/2), ride the corners toggle, and
+collapse to 0 on square. rounded-menu-item is the menu-row radius
+(rd-md − panel-inset) that keeps rows concentric inside a rounded-control
+panel on every surface.
+
+Declared in `index.css`.
+
+```css
+@theme inline {
+	--radius-icon: var(--era-rd-icon);
+	--radius-pill: var(--era-rd-pill);
+	--radius-chip: var(--era-rd-chip);
+	--radius-control: var(--era-rd-control);
+	--radius-bar: var(--era-rd-bar);
+	--radius-menu-item: var(--era-item-rd);
 }
-@utility py-inset-chip {
-	padding-block: var(--era-inset-chip);
+```
+
+## shadow
+
+Surface chrome — bare `shadow` is the resting control edge, shadow-lg the
+floating panel, shadow-well the recessed container, shadow-pressed the
+active/latched face, shadow-highlight the material half of hover feedback.
+Flat renders them as none, bevel as chisels, glass as frosted rims — the
+class stays the same.
+
+Declared in `index.css`.
+
+```css
+@theme inline {
+	--shadow: var(--era-shadow);
 }
-@utility py-inset-control {
-	padding-block: var(--era-inset-control);
+```
+
+## shadow-sm · shadow-lg · shadow-well · shadow-pressed · shadow-highlight
+
+v4 marks bare `shadow` a deprecated spelling of shadow-sm, and lints
+auto-fix one to the other — alias both to the control edge so either
+spelling renders era chrome.
+
+Declared in `index.css`.
+
+```css
+@theme inline {
+	--shadow-sm: var(--era-shadow);
+	--shadow-lg: var(--era-shadow-lg);
+	--shadow-well: var(--era-shadow-well);
+	--shadow-pressed: var(--era-shadow-pressed);
+	--shadow-highlight: var(--era-highlight-shadow);
 }
 ```
 
-## px-pill · px-chip
+## bg-well · text-well · border-well · bg-elevated · text-elevated · border-elevated · bg-highlight · text-highlight · … (12 in all)
 
-**Use it for:** pill side padding — the wider-than-vertical horizontal breathing room badge/chip text wants (glyph-advance derived, ~2× the vertical inset).
+Surface fills — bg-well is the surface's own resting fill (pairs with
+shadow-well for recessed chrome), bg-elevated the raised tier (pairs with
+shadow-lg + glass-blur for floating chrome), bg-highlight the transient
+hover/focus/keyboard wash (pairs with shadow-highlight; latched states
+stay on opaque bg-hover), bg-overlay the modal scrim.
 
 Declared in `index.css`.
 
 ```css
-@utility px-pill {
-	padding-inline: var(--era-pill-px);
+@theme inline {
+	--color-well: var(--era-surface-bg);
+	--color-elevated: var(--era-surface-bg-elevated);
+	--color-highlight: var(--era-highlight);
+	--color-overlay: var(--era-overlay-bg);
 }
-@utility px-chip {
-	padding-inline: var(--era-chip-px);
+```
+
+## p-gutter · px-gutter · py-gutter · gap-gutter · p-panel · px-panel · py-panel · gap-panel · … (24 in all)
+
+THE SPACING SCALE — one entry per token, from which Tailwind derives the
+WHOLE directional family: p/px/py/pt/pr/pb/pl/ps/pe, every margin, gap and
+gap-x/y, inset/top/right/bottom/left, translate, and the sizing prefixes.
+
+These were hand-written `@utility` blocks, which could only ever cover the
+spellings someone remembered to write: `px-gutter` existed and `mt-gutter`
+did not, `p-inset-control` existed and `pl-inset-control` did not, so the
+library fell back to `mt-(--era-gap)` in exactly the places the named API
+was supposed to cover. One line here replaces twenty blocks and leaves no
+spelling missing.
+
+ONLY genuine spacing belongs here. The namespace is shared across
+h/w/p/m/gap, so a name registered here means the same length in ALL of
+them — true of a gap or an inset, false of a TIER HEIGHT. Tiers stay
+hand-written per prefix below, and the two vocabularies deliberately share
+no word: icon/pill/chip/control/bar are heights; gutter, card, panel,
+content, menu, field and the inset-* names are spacing. Registering a tier
+name here would silently make `px-control` mean 24px of side padding.
+
+Declared in `index.css`.
+
+```css
+@theme inline {
+	--spacing-gutter: var(--era-gap);
+	--spacing-panel: var(--era-pad-panel);
+	--spacing-card: var(--era-pad-card);
+	--spacing-content: var(--era-pad-content);
+	--spacing-menu: var(--era-panel-inset);
+	--spacing-field: var(--era-field-px);
 }
 ```
 
-## px-field
+## p-inset-pill · px-inset-pill · py-inset-pill · gap-inset-pill · p-inset-chip · px-inset-chip · py-inset-chip · gap-inset-chip · … (12 in all)
 
-**Use it for:** text-field side padding — where typed text starts in a control-tier input; the named form of px-(--era-field-px).
+**Use it for:** text-symmetric content padding — (tier − text)/2, the inset that vertically centres body text in its tier; px-inset-control is a text button's side padding, p-inset-control a code block's.
 
 Declared in `index.css`.
 
 ```css
-@utility px-field {
-	padding-inline: var(--era-field-px);
+@theme inline {
+	--spacing-inset-pill: var(--era-inset-pill);
+	--spacing-inset-chip: var(--era-inset-chip);
+	--spacing-inset-control: var(--era-inset-control);
 }
 ```
 
-## p-panel · p-card
+## p-icon-inset-pill · px-icon-inset-pill · py-icon-inset-pill · gap-icon-inset-pill · p-icon-inset-chip · px-icon-inset-chip · py-icon-inset-chip · gap-icon-inset-chip · … (32 in all)
 
-**Use it for:** optical padding for unbounded containers — p-panel for compact shells and menu-adjacent chrome, p-card for cards/dialogs/popovers, p-content for full content panels. Grows super-linearly with density so whitespace holds its perceived share as controls loosen.
+**Use it for:** the concentric inset for a nested pair — (h-container − h-child)/2, the gap that makes a child control sit evenly inside its container, and the radius step that keeps their corners concentric. Named for the pair it joins: gap-icon-inset-control seats an icon in a control.
 
 Declared in `index.css`.
 
 ```css
-@utility p-panel {
-	padding: var(--era-pad-panel);
+@theme inline {
+	--spacing-icon-inset-pill: var(--era-icon-inset-pill);
+	--spacing-icon-inset-chip: var(--era-icon-inset-chip);
+	--spacing-icon-inset-control: var(--era-icon-inset-control);
+	--spacing-icon-inset-bar: var(--era-icon-inset-bar);
+	--spacing-pill-inset-chip: var(--era-pill-inset-chip);
+	--spacing-pill-inset-control: var(--era-pill-inset-control);
+	--spacing-chip-inset-control: var(--era-chip-inset-control);
+	--spacing-chip-inset-bar: var(--era-chip-inset-bar);
 }
-@utility p-card {
-	padding: var(--era-pad-card);
+```
+
+## p-glyph-icon · px-glyph-icon · py-glyph-icon · gap-glyph-icon · p-glyph-pill · px-glyph-pill · py-glyph-pill · gap-glyph-pill
+
+**Use it for:** the glyph size for a tier — the INK inside the box, not the box (size-glyph-pill is the dismiss × in a pill, size-pill is the pill).
+
+Declared in `index.css`.
+
+```css
+@theme inline {
+	--spacing-glyph-icon: var(--era-glyph-icon);
+	--spacing-glyph-pill: var(--era-glyph-pill);
 }
 ```
 
-## p-content
+## bg-field · text-field · border-field · bg-field-highlight · text-field-highlight · border-field-highlight
 
-A content panel always follows a section header ROW, and that row already
-contributes its own slack: the heading's text sits in an h-bar bar, so there
-is (h-bar − text)/2 of empty bar under its glyphs before the panel even
-starts. Padding the panel evenly on top of that spends the space twice — the
-header ends up floating between the section above and the paragraph it
-introduces rather than binding to it.
+**Use it for:** the recessed field fill — bg-field is a text input's resting well, bg-field-highlight its focused/hovered face.
 
-So the block-start pays only the REMAINDER. The target is the indent: the
-space under a heading should measure the same as the space beside the text,
-which is --era-content-p. The header row already supplies (h-bar − text)/2 of
-it, so the panel adds what's left, and heading-to-paragraph reads equal to
-the paragraph's own inset. Subtracting one --era-gap (the previous rule) left
-the header's slack unaccounted for and the heading still detached.
+Declared in `index.css`.
 
-Both terms are density-derived, so the equality holds at every mode; the
-max() is the floor for a hypothetical mode where the row's slack would
-exceed the inset outright.
+```css
+@theme inline {
+	--color-field: var(--era-field-bg);
+	--color-field-highlight: var(--era-field-highlight);
+}
+```
+
+## ease-base
+
+Motion — bare transition utilities default to the motion axis, so
+`transition-colors` alone is on-design (0s at instant, longer at extra).
+ease-base/duration-base name the axis explicitly for overrides.
 
 Declared in `index.css`.
 
 ```css
-@utility p-content {
-	padding: var(--era-content-p);
-	padding-top: max(0px, calc(var(--era-content-p) - (var(--era-h-bar) - var(--era-text)) / 2));
+@theme inline {
+	--default-transition-duration: var(--era-duration);
+	--default-transition-timing-function: var(--era-ease);
+	--ease-base: var(--era-ease);
 }
 ```
 
-## p-menu
+## bg-divider · text-divider · border-divider · bg-divider-faded · text-divider-faded · border-divider-faded · bg-background · text-background · … (66 in all)
 
-**Use it for:** menu-panel padding — the surface-owned inset (0 on flat, 2px on glass/bevel) that keeps row highlights inside a floating panel's frame; pairs with rounded-menu-item on the rows.
+Surface divider colors: border-divider, bg-divider-faded, …
 
 Declared in `index.css`.
 
 ```css
-@utility p-menu {
-	padding: var(--era-panel-inset);
+@theme inline {
+	--color-divider: var(--era-divider-color);
+	--color-divider-faded: var(--era-divider-faded);
+	--color-background: var(--color-1);
+	--color-foreground: var(--color-fg);
+	--color-1: var(--color-1);
+	--color-2: var(--color-2);
+	--color-3: var(--color-3);
+	--color-4: var(--color-4);
+	--color-5: var(--color-5);
+	--color-6: var(--color-6);
+	--color-7: var(--color-7);
+	--color-8: var(--color-8);
+	--color-9: var(--color-9);
+	--color-10: var(--color-10);
+	--color-11: var(--color-11);
+	--color-12: var(--color-12);
+	--color-border: var(--color-border);
+	--color-surface: var(--color-surface);
+	--color-hover: var(--color-hover);
+	--color-fg: var(--color-fg);
+	--color-bright: var(--color-bright);
+	--color-muted: var(--color-muted);
 }
 ```
 
-## duration-base
+## bg-fill · text-fill · border-fill · bg-link · text-link · border-link · bg-primary · text-primary · … (33 in all)
 
-**Use it for:** the motion axis as an explicit transition-duration — for the rare case a utility (not the transition-* default) needs to name it; 0s at data-motion="instant", longer at "extra".
+The standing pill fill — --era-fill, the latched counterpart of the
+transient highlight. Surface-owned: a composing wash on flat/bevel, the
+opaque swatch on glass.
 
 Declared in `index.css`.
 
 ```css
-@utility duration-base {
-	transition-duration: var(--era-duration);
+@theme inline {
+	--color-fill: var(--era-fill);
+	--color-link: var(--color-link);
+	--color-primary: var(--color-primary);
+	--color-primary-fg: var(--color-primary-fg);
+	--color-primary-hover: var(--color-primary-hover);
+	--color-destructive: var(--color-destructive);
+	--color-destructive-fg: var(--color-destructive-fg);
+	--color-success: var(--color-success);
+	--color-success-fg: var(--color-success-fg);
+	--color-warning: var(--color-warning);
+	--color-warning-fg: var(--color-warning-fg);
 }
 ```