@signal9/era-ui 32.0.0 → 33.0.0

package/dist/styles/typography.css

@@ -71,7 +71,7 @@
  * is read where --era-font-stack is declared, which is the [data-font] element.
  * Re-point a stack AT or ABOVE the element that carries the axis. Setting
  * --era-font-mono on a descendant of it does nothing — the pointer was already
- * resolved higher up. (That is why /audit re-asserts the shipped stacks on
+ * resolved higher up. (That is why the private audit harness re-asserts the shipped stacks on
  * :root rather than on its own <main>.)
  */
 [data-font='mono'] {

package/dist/styles/utilities/geometry.css

@@ -0,0 +1,188 @@
+/* BOUNDED GEOMETRY — height and radius are one decision.
+ *
+ * A tier is a geometric type, not two classes a caller must remember to keep in
+ * sync. `tier-control` establishes h-control AND rd-control; the radius ladder
+ * then guarantees rd_outer − rd_inner = (h_outer − h_inner)/2 for every pair.
+ * Width remains the component's decision: a row stretches, a button adds
+ * min-w-control, and a square control adds w-control. */
+@utility tier-icon {
+	height: var(--era-h-icon);
+	border-radius: var(--era-rd-icon);
+}
+
+@utility tier-pill {
+	height: var(--era-h-pill);
+	border-radius: var(--era-rd-pill);
+}
+
+@utility tier-chip {
+	height: var(--era-h-chip);
+	border-radius: var(--era-rd-chip);
+}
+
+@utility tier-control {
+	height: var(--era-h-control);
+	border-radius: var(--era-rd-control);
+}
+
+@utility tier-bar {
+	height: var(--era-h-bar);
+	border-radius: var(--era-rd-bar);
+}
+
+/* One LINE BOX tall — the height of the text this stands in for.
+ *
+ * Skeleton's `line` used h-(--era-text), which is the body FONT SIZE: never the
+ * height of a rendered line (that is font-size x leading), and wrong again by
+ * the ladder's ratio for any rung other than body. `1lh` resolves against the
+ * element's OWN computed line-height, so putting a text-* class on the skeleton
+ * makes it match that tier exactly, at every density, and it follows a leading
+ * change for free.
+ *
+ * @use the height of one line of the element's own text — a skeleton standing in
+ * for a line, a spacer that must match a line box. */
+@utility h-line {
+	height: 1lh;
+}
+
+/* A WELL THAT SURVIVES BEING FILLED.
+ *
+ * `shadow-well` is an INSET shadow, and an inset shadow belongs to the
+ * element's background layer — it paints under the element's own descendants.
+ * That is invisible on a well holding text (a checkbox, a code block: the
+ * chrome runs around the content) and wrong the moment something paints the
+ * whole box. Meter, Progress and the Slider track all do exactly that: an
+ * opaque child, `translateX`-ed to the value. So the well survived only where
+ * the track was EMPTY — a half-full meter on bevel had a chisel to the right
+ * of the value and none to the left, which reads as a hole with a sticker
+ * over it rather than a level inside a well.
+ *
+ * The fix is painting order, not geometry: the same `--era-shadow-well` on a
+ * pseudo-element that is the element's LAST child, so it lands above the fill.
+ * The fill still spans the full box — nothing is inset, no radius is
+ * re-derived, and 0% and 100% keep their exact ends. The `position: relative`
+ * is load-bearing (the overlay resolves against this box) and `inherit` on the
+ * radius keeps it honest under `data-corners="square"`.
+ *
+ * Surface-agnostic on purpose. It reads the same token every well reads, so
+ * glass's hairline rim is restored by the same line that restores bevel's
+ * chisel, and flat — where the token is `none` — renders exactly as before.
+ * Reported against bevel by a consumer; it was never a bevel bug.
+ *
+ * @use instead of `shadow-well` on a track whose value is painted by a child
+ * that covers the box — a progress/meter/slider track, a custom gauge. For a
+ * well holding ordinary content, `shadow-well` is still right. */
+@utility era-track-well {
+	position: relative;
+	&::after {
+		content: '';
+		position: absolute;
+		inset: 0;
+		border-radius: inherit;
+		box-shadow: var(--era-shadow-well);
+		pointer-events: none;
+	}
+}
+
+/* Skeleton's pulse, on the MOTION AXIS.
+ *
+ * It used to be a literal `2s ease-in-out` on the component, so it neither died
+ * at data-motion="instant" nor honoured prefers-reduced-motion — on the one
+ * component most likely to be on screen in bulk, and animating. That is an
+ * accessibility defect rather than a preference: a page of pulsing blocks is
+ * exactly what someone with a vestibular disorder turns motion off to avoid.
+ *
+ * Same derivation as era-shimmer: 10x the axis duration, so it is a slow pulse
+ * at normal, slower at extra, and at instant the duration resolves to 0s and it
+ * freezes on its base frame — full opacity, a plain filled block. */
+@utility era-skeleton-pulse {
+	animation: era-skeleton-pulse calc(var(--era-duration) * 10) var(--era-ease) infinite;
+}
+
+@keyframes era-skeleton-pulse {
+	0%,
+	100% {
+		opacity: 1;
+	}
+	50% {
+		opacity: 0.4;
+	}
+}
+
+/* In-progress text shimmer — a bright sweep through muted text (the standard
+ * "working…" label treatment in streaming UIs). Timing derives from the motion
+ * axis (10× --era-duration ≈ 1.5s at normal, 2.6s at extra); at instant the
+ * duration is 0s and the sweep freezes on its base frame — plain muted text —
+ * so reduced-motion and data-motion="instant" both kill it for free.
+ *
+ * @use the in-progress text treatment — put it on a "working…" / "thinking…"
+ * label while a task streams, instead of a spinner beside the text. */
+@utility era-shimmer {
+	background: linear-gradient(
+		110deg,
+		var(--color-muted) 0% 43%,
+		var(--color-bright) 50%,
+		var(--color-muted) 57% 100%
+	);
+	background-size: 200% 100%;
+	background-clip: text;
+	-webkit-text-fill-color: transparent;
+	animation: era-shimmer calc(var(--era-duration) * 10) cubic-bezier(0.7, 0, 1, 0.4) infinite;
+}
+@keyframes era-shimmer {
+	0% {
+		background-position: 100% 0;
+	}
+	100% {
+		background-position: -100% 0;
+	}
+}
+
+/* The open/close animation for a bits-ui Collapsible.Content — the height
+ * sweep every disclosure in the library uses (a Step's body, an error panel's
+ * detail, a swarm node's children).
+ *
+ * It has to be a keyframe animation rather than a transition because the
+ * natural height is only knowable at open time: bits measures the content and
+ * publishes `--bits-collapsible-content-height`, which the `to` frame reads.
+ * The class also owns `overflow: hidden` — animating height without it just
+ * spills the content out of the shrinking box.
+ *
+ * Timing rides the motion axis, so `instant` collapses it to a cut (0s) and
+ * `extra` stretches it, for free. Two components carried a byte-identical copy of
+ * these keyframes under two different names before this existed (a Step's body
+ * and the error panel's detail), and the swarm tree would have made a third; the
+ * panel that needs different motion should override `animation`, not re-declare
+ * it.
+ *
+ * @use the height sweep for a bits-ui Collapsible.Content — put it on the
+ * Content element itself (it carries its own overflow: hidden). */
+@utility era-collapse {
+	overflow: hidden;
+	&[data-state='open'] {
+		animation: era-collapse-open var(--era-duration) var(--era-ease);
+	}
+	&[data-state='closed'] {
+		animation: era-collapse-close var(--era-duration) var(--era-ease);
+	}
+}
+@keyframes era-collapse-open {
+	from {
+		height: 0;
+		opacity: 0;
+	}
+	to {
+		height: var(--bits-collapsible-content-height);
+		opacity: 1;
+	}
+}
+@keyframes era-collapse-close {
+	from {
+		height: var(--bits-collapsible-content-height);
+		opacity: 1;
+	}
+	to {
+		height: 0;
+		opacity: 0;
+	}
+}

package/dist/styles/utilities/interaction.css

@@ -0,0 +1,334 @@
+/* Shared interactive-state recipe: quiet focus, disabled affordance.
+ * Equivalent to `focus:outline-none disabled:cursor-not-allowed disabled:opacity-50`.
+ *
+ * @use the focus/disabled recipe every era control carries — put it on a custom
+ * interactive element instead of hand-writing focus/disabled variants. */
+@utility era-interactive {
+	&:focus {
+		outline: none;
+	}
+	&:disabled {
+		cursor: not-allowed;
+		opacity: 0.5;
+	}
+}
+
+/* Inline text link. An understated, permanent underline that darkens from
+ * muted to the text colour on hover — no layout shift, no appearing/vanishing
+ * underline. The colour fade rides the MOTION axis (--era-duration/-ease), so
+ * it snaps at data-motion="instant", eases at "normal", and sweeps longer at
+ * "extra" — matching every other era transition. Font-agnostic: it styles
+ * decoration + colour only, so it reads correctly in mono, sans, or serif, and
+ * the 0.2em offset scales with the type size. Keyboard focus mirrors hover so
+ * the affordance is reachable without a pointer.
+ *
+ * @use understated, motion-aware inline text link — the canonical style for a
+ * link in body copy or prose; prefer it over a hand-rolled underline or
+ * `Button variant="link"` (which is a control, not running text). */
+@utility era-link {
+	/* The text is bright at rest and never changes — the link reads as a link
+	 * before you touch it. Only the UNDERLINE reacts: a faint hint at rest —
+	 * the link's own ink knocked back to 30% so it barely whispers — that
+	 * resolves to the full ink on hover.
+	 *
+	 * currentColor, not --color-muted/--color-fg: the underline belongs to the
+	 * TEXT it underlines. On themes whose link ink is a colour (signalnine's
+	 * navy, an accent-tinted bright), the neutral tokens drew a whitish line
+	 * under coloured text — a second hue where there should be one. Derived
+	 * from currentColor, the underline tracks whatever the link resolves to,
+	 * in every theme, including a caller overriding `color` locally. */
+	color: var(--color-link);
+	text-decoration-line: underline;
+	text-decoration-color: color-mix(in oklch, currentColor 30%, transparent);
+	text-underline-offset: 0.2em;
+	transition: text-decoration-color var(--era-duration) var(--era-ease);
+	&:hover,
+	&:focus-visible {
+		text-decoration-color: currentColor;
+	}
+}
+
+/* Scrollable but chromeless — hides the scrollbar while keeping wheel / touch /
+ * drag scrolling (e.g. an overflowing tab strip in a small pane handle).
+ *
+ * @use hide the scrollbar on an overflowing strip or rail while keeping it
+ * scrollable — for a scroll region that should show its bar, use ScrollArea. */
+@utility scrollbar-none {
+	scrollbar-width: none;
+	&::-webkit-scrollbar {
+		display: none;
+	}
+}
+
+/* Font-agnostic vertical ink-centering for single-line control text.
+ * Measured verdict (4 fonts x 2 dpr, ink from device-pixel screenshots):
+ * the offset has TWO causes — a fractional line box (14px x 1.5lh = 21px in
+ * a 24px row places ink on a half pixel, ~1px error) and font ascent/descent
+ * asymmetry (+-1px, sign flips per font). line-height: 1 fixes the first and
+ * is the Firefox fallback; text-box ex/alphabetic fixes the second by
+ * centering the x-height band — the visual mass of MIXED-CASE text (caps and
+ * descenders cancel above/below). cap alphabetic is the spec-example recipe
+ * but is descender-blind (reads high; CSSWG #9148) — measured 4x worse here.
+ * Where text-box is supported it fully determines the box, so the two
+ * declarations never fight. Worst-case residual: 0.44px (measured at 14px; the
+ * mechanism is font-relative, so dense's 12px inherits the same guarantee with
+ * a proportionally smaller residual).
+ *
+ * The hard rules concern overflow clipping, and there are TWO of them.
+ *
+ * 1. NEVER on a NATIVE EDITABLE — <input>, <textarea>, <select>. These clip to
+ *    a UA-owned inner editor box that IS the trimmed line box, so a fixed
+ *    height does NOT hold it open: whatever you type gets its ascenders and
+ *    descenders sliced off (a "d" renders as an "o"). This rule used to read
+ *    the other way round — it claimed a fixed-height <input> was the trim's
+ *    intended home — and the Input component shipped chopped text as a result.
+ *    A tier-height input centres its own text; it needs no trim.
+ *
+ * 2. NEVER on an AUTO-height element that clips — a `truncate` child, an
+ *    auto-height box with overflow-hidden. With no height to hold it open the
+ *    box collapses to the x-height band (~7.5px at 14px) and the clip chops the
+ *    glyphs into a middle stripe. Put the trim on the fixed-height ROW instead
+ *    and let the child centre via the row's items-center.
+ *
+ * A fixed-height NON-editable element is the safe home: the ink overflows the
+ * trimmed LINE box but stays inside the padding box, which is what actually
+ * clips. Both rules are enforced at runtime by typography/collapsed-text-trim.
+ *
+ * @use 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.
+ */
+@utility era-text-trim {
+	line-height: 1;
+	text-box: trim-both ex alphabetic;
+}
+
+/* Tailwind's `truncate`, with the vertical clip fixed at the source.
+ *
+ * truncate is overflow:hidden, and overflow clips in BOTH axes — so whatever
+ * line box the element ends up with is also its ink clip. Era rows put
+ * era-text-trim on the fixed-height row (a Bar, a list row), and its
+ * `line-height: 1` INHERITS into the truncating child, which then has no fixed
+ * height of its own: the child's box collapses to 1em while the font's real ink
+ * extent is ~1.15-1.2em, and the descenders (the "g" hook, the "y" tail) get
+ * sliced off at the box edge. Same bug on any `leading-none` + `truncate` pair.
+ *
+ * The fix belongs here rather than at each call site: a horizontally-truncating
+ * element must never be the thing that clips vertically. `line-height: normal`
+ * restores the font's own ascent+descent box — exactly the ink extent — and
+ * `text-box: normal` cancels a trim if one is set alongside. Rows stay the same
+ * height (they are tier-fixed and centre the child), and the child now has room
+ * for its own glyphs.
+ *
+ * @use 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. */
+@utility truncate {
+	overflow: hidden;
+	text-overflow: ellipsis;
+	white-space: nowrap;
+	line-height: normal;
+	text-box: normal;
+}
+
+/* THE COLLISION GUARD — `truncate` and `era-text-trim` on the SAME element.
+ *
+ * Two utilities, same specificity, opposite intents: the trim collapses the box
+ * to the x-height band, and truncate clips to whatever box it lands on. Class
+ * ORDER in the attribute cannot break the tie — CSS resolves same-specificity
+ * conflicts by stylesheet order, and Tailwind emits era-text-trim last, so the
+ * trim silently won and the clip chopped the glyphs into a middle stripe
+ * (measured: an 8.58px box holding 16px of ink). Writing the classes the other
+ * way round changed nothing, which is what made it so hard to see.
+ *
+ * A real consumer hit exactly this. So the pairing is now DEFINED rather than
+ * accidental, with a compound selector that outranks both single-class
+ * utilities: truncate wins the vertical, the glyphs stay whole, and the
+ * element centres the way the docs say it should anyway — via its
+ * fixed-height parent's items-center.
+ *
+ * This is a safety net, not a blessing: the correct authoring is still trim on
+ * the ROW, truncate on the CHILD (typography/collapsed-text-trim still reports
+ * the pair so the runtime audit can point at it). It exists so the failure mode
+ * is a no-op instead of unreadable text. */
+.era-text-trim.truncate,
+.era-text-trim-caps.truncate,
+.era-label-ink.truncate,
+.era-token-ink.truncate {
+	line-height: normal;
+	text-box: normal;
+}
+
+/* ALL-CAPS single-line text (kbd hints, acronym badges): the x-height band
+ * misjudges caps-only strings — cap/alphabetic edges are the right box.
+ *
+ * @use 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`. */
+@utility era-text-trim-caps {
+	line-height: 1;
+	text-box: trim-both cap alphabetic;
+}
+
+/* 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; the general form of that offset,
+ * and why era-label-ink's note about "System" is not a contradiction of it,
+ * is derived at era-label-ink below). 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.
+ *
+ * WHEN SOMEONE REPORTS A CORRECTLY-CENTRED FIELD AS "TOO HIGH", check the
+ * STRING before the geometry. A placeholder like "Filter…" has no descender and
+ * no cap, so its ink occupies only the x-height band — and a box that centres
+ * that band exactly still reads high, because the eye centres on the mass it
+ * can see and expects the space a descender would have filled. Measured at the
+ * pill tier on the shipped mono stack, "Filter…" sits within half a pixel of
+ * centre while looking a little high; the pill suite documents the same effect
+ * from the other side (see OFF_BAND_LOW in ink-centering.spec.ts, where "soon"
+ * cannot be symmetric and is bounded by sign instead of magnitude).
+ *
+ * That is not a licence to ignore the report — era-ink-center IS wrong by
+ * 1.5–2px on the sans and serif stacks (pinned in FIELD_KNOWN_SKEW) — only a
+ * reason to measure the ink before touching the constant.
+ *
+ * @use on a native single-line <input> (or the text layer that must mirror
+ * one) inside a fixed-height field — never alongside era-text-trim. */
+@utility era-ink-center {
+	padding-bottom: 0.08em;
+}
+
+/* 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.
+ *
+ * THE BUG IT FIXES, which had been shipping library-wide and invisibly:
+ * `text-box-trim` DOES NOTHING ON A FLEX CONTAINER. Era's controls are all
+ * flex, and a flex container's bare text becomes an ANONYMOUS flex item — a box
+ * no selector can reach and no non-inherited property can touch. So
+ * `era-text-trim` on a Badge, a Chip, a Button or a Bar contributed exactly one
+ * thing: `line-height: 1`. The ink was then centred by `align-items: center`
+ * on the LINE BOX, which is precisely the font-metric-dependent centring the
+ * trim exists to eliminate. Measured on the shipped mono stack: a badge reading
+ * "AC-2.1" sat 2px high in an 18px pill, and no amount of tuning the trim's
+ * BAND changed it, because the trim was never running.
+ *
+ * The mechanism here restores it: a BLOCK box (where text-box-trim does apply)
+ * whose trimmed line box is then centred by `align-content` — block-container
+ * alignment, so no flex formatting context and no anonymous item. The browser
+ * computes the band from the font's own metrics, which is what makes it hold
+ * across ui-monospace, system-ui and ui-serif instead of needing a constant
+ * per stack.
+ *
+ * CAP band, not the x-height band the general trim uses, because the content
+ * class is different: a token is caps and digits (both cap-height), and
+ * centring the x-band parks them high by (cap − x)/2. Measured on the shipped
+ * stacks, cap-band centring takes an id/count/status from −2.0px to 0.0.
+ * Prose and sentence-case labels keep era-text-trim; this is for tokens.
+ *
+ * @use 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. */
+@utility era-token-ink {
+	display: block;
+	align-content: center;
+	text-align: center;
+	line-height: 1;
+	text-box: trim-both cap alphabetic;
+}
+
+/* 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.
+ *
+ * THAT PARENTHESIS AND era-ink-center's "x-band centring parks ~2px high" READ
+ * AS A CONTRADICTION AND ARE NOT. Both are true, of their own example string,
+ * and each was generalised one step too far. Under an ex band the ink offset is
+ *
+ *     (xh − ascent + descent) / 2
+ *
+ * which predicts a controlled A/B — one real button, one class set, only the
+ * STRING changing — within 0.3px:
+ *
+ *     Save  asc 9 desc 0   1.28px high     SAVE  asc 9 desc 0   1.28px high
+ *     Savg  asc 9 desc 3   0.22px low      savg  asc 7 desc 3   1.22px low
+ *
+ * "System" has a descender and reads low under the cap band; "Save" has none
+ * and reads high under the ex band. Case is not the variable — "Save" and
+ * "SAVE" are identical to the hundredth of a pixel. No fixed band centres both
+ * a descender-less and a descender-bearing label, because they differ by ~1.5px
+ * in the same box.
+ *
+ * WHICH IS WHY THE BAND IS FIXED ANYWAY, and this is the part that decides it.
+ * A band gives every label the SAME baseline whatever it spells — measured
+ * spread across Save/Savg/save/savg/SAVE/PDF/Cancel/"Copy page" is 0.00px —
+ * while ink-extent centring would move each label independently and leave a bar
+ * of buttons visibly ragged. A uniform offset the eye cannot see beats a local
+ * misalignment it can. So the offset is accepted, not corrected, and the only
+ * escape is per-label and opt-in (Button's `caps`), which buys optical centring
+ * for a lone label at the cost of ~1.06px against its neighbours.
+ *
+ * AND THE GUARANTEE SPANS BOTH INK PATHS. This utility and era-text-trim are
+ * two mechanisms — block+align-content here, a blockified flex item there — and
+ * every measurement above was taken on the trim path. Measured since: the
+ * text-only path holds the same 0.00px spread AND lands on the same baseline,
+ * 15.22px from the button top at control tier. So an icon button and a text
+ * button put their labels on one line, and `not-has-[svg]` costs nothing but
+ * which element carries the trim.
+ *
+ * Measured by signalnine.org and reproduced here; see label-band.spec.ts, which
+ * pins the 0.00px spread, the cost of breaking it, and the agreement between
+ * the two paths.
+ *
+ * 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.
+ *
+ * @use 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). */
+@utility era-label-ink {
+	display: block;
+	align-content: center;
+	line-height: 1;
+	text-box: trim-both ex alphabetic;
+}

package/dist/styles/utilities/materials.css

@@ -0,0 +1,39 @@
+/* MATERIAL ROLES — components choose meaning; surfaces choose appearance. */
+/* @use the surface-aware backdrop treatment without choosing a fill or relief.
+ * Prefer material-popover/material-panel when the element is a complete surface. */
+@utility surface-backdrop {
+	backdrop-filter: var(--era-backdrop-filter);
+	-webkit-backdrop-filter: var(--era-backdrop-filter);
+}
+
+/* @use a floating transient surface: menus, popovers, tooltips, pickers, toasts.
+ * Binds its raised fill, floating relief, and backdrop treatment atomically. */
+@utility material-popover {
+	background-color: var(--era-surface-bg-elevated);
+	box-shadow: var(--era-shadow-lg);
+	backdrop-filter: var(--era-backdrop-filter);
+	-webkit-backdrop-filter: var(--era-backdrop-filter);
+}
+
+/* @use a floating persistent surface: dialogs, sheets, panes, inspectors.
+ * Binds its resting fill, floating relief, and backdrop treatment atomically. */
+@utility material-panel {
+	background-color: var(--era-surface-bg);
+	box-shadow: var(--era-shadow-lg);
+	backdrop-filter: var(--era-backdrop-filter);
+	-webkit-backdrop-filter: var(--era-backdrop-filter);
+}
+
+/* @use the physical press contract on a control whose direct content plane is
+ * marked data-era-press-content. The surface owns relief/travel; compact
+ * components select the compact travel primitives as their effective values. */
+@utility pressable {
+	&:active {
+		box-shadow: var(--era-shadow-pressed);
+	}
+
+	&:active > [data-era-press-content] {
+		translate: var(--era-press-effective-x, var(--era-press-sink-x))
+			var(--era-press-effective-y, var(--era-press-sink-y));
+	}
+}