@signal9/era-ui 2.26.0 → 2.27.0

package/dist/generated-docs/llms-full.txt

@@ -29,7 +29,21 @@ Every component has a passive markdown doc at `/<slug>.md`.
 Examples: `/button.md`, `/select.md`, `/table.md`.
 Full concatenated reference: `/llms-full.txt`.
 
-<!-- Full component documentation, concatenated. -->
+## CSS utilities
+
+Classes, not components — they need no import beyond the stylesheet. Reach for one of these before hand-rolling the same styling or bending a component into the role.
+
+- `era-interactive` — the focus/disabled recipe every era control carries — put it on a custom interactive element instead of hand-writing focus/disabled variants.
+- `era-link` — 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).
+- `scrollbar-none` — hide the scrollbar on an overflowing strip or rail while keeping it scrollable — for a scroll region that should show its bar, use ScrollArea.
+- `era-text-trim` — vertically center single-line control text (a label beside an icon, an input's own text) without a translateY nudge — fixed-height elements only; see era-text-trim-caps for ALL-CAPS strings.
+- `era-text-trim-caps` — the era-text-trim variant for ALL-CAPS single-line strings (kbd hints, acronym badges) — never use it for mixed-case text.
+- `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.
+- `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.
+
+Full reference (what each emits, when to use it): `/utilities.md`. Machine-readable list: `/utilities.json`.
+
+<!-- Full component documentation, concatenated. The utilities page below carries the CSS each utility emits. -->
 
 <!-- begin: about -->
 
@@ -71,6 +85,206 @@ Copy-paste text styling — headings, prose, emphasis, and motion-aware links.
 
 <!-- end: text -->
 
+<!-- begin: utilities -->
+
+# Utilities
+
+The CSS classes era ships alongside the components — links, ink-centred text, shimmer, hidden scrollbars.
+
+## Overview
+
+era ships a handful of Tailwind v4 `@utility` classes for the patterns that are
+styling, not components — an inline link, ink-centred control text, a hidden
+scrollbar. They need no import: they ride along with the stylesheet.
+
+```ts
+import "@sig-nine/era-ui/css";
+```
+
+```svelte
+<a class="era-link" href="/spacing">the spacing ladder</a>
+```
+
+| Utility | Use it for |
+|---|---|
+| `era-interactive` | the focus/disabled recipe every era control carries — put it on a custom interactive element instead of hand-writing focus/disabled variants. |
+| `era-link` | 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). |
+| `scrollbar-none` | hide the scrollbar on an overflowing strip or rail while keeping it scrollable — for a scroll region that should show its bar, use ScrollArea. |
+| `era-text-trim` | vertically center single-line control text (a label beside an icon, an input's own text) without a translateY nudge — fixed-height elements only; see era-text-trim-caps for ALL-CAPS strings. |
+| `era-text-trim-caps` | the era-text-trim variant for ALL-CAPS single-line strings (kbd hints, acronym badges) — never use it for mixed-case text. |
+| `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. |
+| `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
+
+**Use it for:** the focus/disabled recipe every era control carries — put it on a custom interactive element instead of hand-writing focus/disabled variants.
+
+Shared interactive-state recipe: quiet focus, disabled affordance.
+Equivalent to `focus:outline-none disabled:cursor-not-allowed disabled:opacity-50`.
+
+Declared in `index.css`.
+
+```css
+@utility era-interactive {
+	&:focus {
+		outline: none;
+	}
+	&:disabled {
+		cursor: not-allowed;
+		opacity: 0.5;
+	}
+}
+```
+
+## era-link
+
+**Use it for:** 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).
+
+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.
+
+Declared in `index.css`.
+
+```css
+@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 half-strength-muted
+	 * hint at rest that resolves to the full text colour on hover. */
+	color: var(--color-bright);
+	text-decoration-line: underline;
+	text-decoration-color: color-mix(in oklch, var(--color-muted) 50%, transparent);
+	text-underline-offset: 0.2em;
+	transition: text-decoration-color var(--era-duration) var(--era-ease);
+	&:hover,
+	&:focus-visible {
+		text-decoration-color: var(--color-fg);
+	}
+}
+```
+
+## scrollbar-none
+
+**Use it for:** hide the scrollbar on an overflowing strip or rail while keeping it scrollable — for a scroll region that should show its bar, use ScrollArea.
+
+Scrollable but chromeless — hides the scrollbar while keeping wheel / touch /
+drag scrolling (e.g. an overflowing tab strip in a small pane handle).
+
+Declared in `index.css`.
+
+```css
+@utility scrollbar-none {
+	scrollbar-width: none;
+	&::-webkit-scrollbar {
+		display: none;
+	}
+}
+```
+
+## era-text-trim
+
+**Use it for:** vertically center single-line control text (a label beside an icon, an input's own text) without a translateY nudge — fixed-height elements only; see era-text-trim-caps for ALL-CAPS strings.
+
+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.
+
+The one hard rule concerns overflow clipping, and it is HEIGHT-conditional.
+On an AUTO-height element that also clips — a `truncate` child, a
+<textarea>, an auto-height <input> — trim-both collapses the box to the
+x-height band (~7.5px at 14px) and the clip slices off every ascender, cap,
+and descender (text renders as a chopped middle stripe): NEVER do that.
+A FIXED-height control is the intended home, and is safe: the explicit
+`h-(--era-*)` overrides the collapse, so a single-line <input> (Input,
+command-input) and clipping display tokens (KV) correctly carry it. For
+truncating text, put the trim on the fixed-height ROW and let the child
+center via the row's items-center.
+
+Declared in `index.css`.
+
+```css
+@utility era-text-trim {
+	line-height: 1;
+	text-box: trim-both ex alphabetic;
+}
+```
+
+## era-text-trim-caps
+
+**Use it for:** the era-text-trim variant for ALL-CAPS single-line strings (kbd hints, acronym badges) — never use it for mixed-case text.
+
+ALL-CAPS single-line text (kbd hints, acronym badges): the x-height band
+misjudges caps-only strings — cap/alphabetic edges are the right box.
+
+Declared in `index.css`.
+
+```css
+@utility era-text-trim-caps {
+	line-height: 1;
+	text-box: trim-both cap alphabetic;
+}
+```
+
+## era-shimmer
+
+**Use it for:** the in-progress text treatment — put it on a "working…" / "thinking…" label while a task streams, instead of a spinner beside the text.
+
+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.
+
+Declared in `index.css`.
+
+```css
+@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;
+}
+```
+
+## glass-blur
+
+**Use it for:** 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.
+
+Tailwind v4 cannot resolve var() inside backdrop-blur-[], so the filter
+is a registered utility, gated to glass subtrees.
+
+Declared in `surfaces/glass.css`.
+
+```css
+@utility glass-blur {
+	[data-surface='glass'] & {
+		backdrop-filter: blur(var(--era-blur)) saturate(var(--era-saturate));
+		-webkit-backdrop-filter: blur(var(--era-blur)) saturate(var(--era-saturate));
+	}
+}
+```
+
+<!-- end: utilities -->
+
 <!-- begin: draggable -->
 
 # Draggable
@@ -275,6 +489,7 @@ and screen-reader accessible names don't change shape mid-flight. |
 
 - Heights, radii, paddings, and gaps come from density tokens — never hard-code px.
 - `link` variant intentionally does not change color on hover (underline only) so it reads as static prose until confirmed interactive.
+- `variant="link"` is for a _control_ that should look like a link (a button that reveals a panel, a destructive action in a row). For a link in body copy or prose, use the `era-link` CSS utility on an `<a>` instead — see [Utilities](/utilities.md).
 - For a segmented row of buttons, use `ButtonGroup`.
 
 <!-- end: button -->
@@ -2137,6 +2352,14 @@ Inherits all props from `ScrollArea.CornerProps`.
 |------|------|---------|-------|
 | `ref?` | `(forwarded)` | `null` | bindable |
 
+## Notes
+
+- For a region that should scroll but show no scrollbar at all — an overflowing
+  tab strip, a chip rail, a small pane handle — you don't need ScrollArea: put
+  the `scrollbar-none` CSS utility on the overflowing element. See
+  [Utilities](/utilities.md). ScrollArea is for the case where the bar itself is
+  part of the design.
+
 <!-- end: scroll-area -->
 
 <!-- begin: input -->

package/dist/generated-docs/llms.txt

@@ -31,4 +31,18 @@ Full concatenated reference: `{{ORIGIN}}/llms-full.txt`.
 
 ## Components
 
-about, spacing, surfaces, measurements, text, draggable, llm-shell, os, aspect-ratio, badge, avatar, bar, button, button-group, pane, card, chip, code-block, copy-button, cycle, kv, separator, sheet, skeleton, switch, toggle, accordion, alert-dialog, calendar, checkbox, collapsible, combobox, command, command-bar, step, context-menu, date-field, date-picker, date-range-field, date-range-picker, dialog, dropdown-menu, file-upload, scroll-area, input, link-preview, label, menu, menubar, meter, navigation-menu, mode, pagination, pin-input, popover, progress, range-calendar, radio-group, rating-group, select, slider, table, tabs, time-field, time-range-field, toggle-group, toolbar, video-player, tooltip
+about, spacing, surfaces, measurements, text, utilities, draggable, llm-shell, os, aspect-ratio, badge, avatar, bar, button, button-group, pane, card, chip, code-block, copy-button, cycle, kv, separator, sheet, skeleton, switch, toggle, accordion, alert-dialog, calendar, checkbox, collapsible, combobox, command, command-bar, step, context-menu, date-field, date-picker, date-range-field, date-range-picker, dialog, dropdown-menu, file-upload, scroll-area, input, link-preview, label, menu, menubar, meter, navigation-menu, mode, pagination, pin-input, popover, progress, range-calendar, radio-group, rating-group, select, slider, table, tabs, time-field, time-range-field, toggle-group, toolbar, video-player, tooltip
+
+## CSS utilities
+
+Classes, not components — they need no import beyond the stylesheet. Reach for one of these before hand-rolling the same styling or bending a component into the role.
+
+- `era-interactive` — the focus/disabled recipe every era control carries — put it on a custom interactive element instead of hand-writing focus/disabled variants.
+- `era-link` — 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).
+- `scrollbar-none` — hide the scrollbar on an overflowing strip or rail while keeping it scrollable — for a scroll region that should show its bar, use ScrollArea.
+- `era-text-trim` — vertically center single-line control text (a label beside an icon, an input's own text) without a translateY nudge — fixed-height elements only; see era-text-trim-caps for ALL-CAPS strings.
+- `era-text-trim-caps` — the era-text-trim variant for ALL-CAPS single-line strings (kbd hints, acronym badges) — never use it for mixed-case text.
+- `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.
+- `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.
+
+Full reference (what each emits, when to use it): `{{ORIGIN}}/utilities.md`. Machine-readable list: `{{ORIGIN}}/utilities.json`.

package/dist/generated-docs/manifest.json

@@ -40,6 +40,23 @@
       "sections": [],
       "file": "text.md"
     },
+    {
+      "slug": "utilities",
+      "title": "Utilities",
+      "summary": "The CSS classes era ships alongside the components — links, ink-centred text, shimmer, hidden scrollbars.",
+      "tokenEstimate": 1989,
+      "sections": [
+        "Overview",
+        "era-interactive",
+        "era-link",
+        "scrollbar-none",
+        "era-text-trim",
+        "era-text-trim-caps",
+        "era-shimmer",
+        "glass-blur"
+      ],
+      "file": "utilities.md"
+    },
     {
       "slug": "draggable",
       "title": "Draggable",
@@ -116,7 +133,7 @@
       "slug": "button",
       "title": "Button",
       "summary": "A flexible button or link element.",
-      "tokenEstimate": 390,
+      "tokenEstimate": 453,
       "sections": [
         "Import",
         "Props",
@@ -564,14 +581,15 @@
       "slug": "scroll-area",
       "title": "Scroll Area",
       "summary": "A cross-platform scroll container.",
-      "tokenEstimate": 314,
+      "tokenEstimate": 399,
       "sections": [
         "Import",
         "ScrollArea.Root",
         "ScrollArea.Viewport",
         "ScrollArea.Scrollbar",
         "ScrollArea.Thumb",
-        "ScrollArea.Corner"
+        "ScrollArea.Corner",
+        "Notes"
       ],
       "file": "scroll-area.md"
     },
@@ -892,5 +910,56 @@
       ],
       "file": "tooltip.md"
     }
+  ],
+  "utilities": [
+    {
+      "name": "era-interactive",
+      "file": "index.css",
+      "useCase": "the focus/disabled recipe every era control carries — put it on a custom interactive element instead of hand-writing focus/disabled variants.",
+      "description": "Shared interactive-state recipe: quiet focus, disabled affordance.\nEquivalent to `focus:outline-none disabled:cursor-not-allowed disabled:opacity-50`.",
+      "css": "@utility era-interactive {\n\t&:focus {\n\t\toutline: none;\n\t}\n\t&:disabled {\n\t\tcursor: not-allowed;\n\t\topacity: 0.5;\n\t}\n}"
+    },
+    {
+      "name": "era-link",
+      "file": "index.css",
+      "useCase": "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).",
+      "description": "Inline text link. An understated, permanent underline that darkens from\nmuted to the text colour on hover — no layout shift, no appearing/vanishing\nunderline. The colour fade rides the MOTION axis (--era-duration/-ease), so\nit snaps at data-motion=\"instant\", eases at \"normal\", and sweeps longer at\n\"extra\" — matching every other era transition. Font-agnostic: it styles\ndecoration + colour only, so it reads correctly in mono, sans, or serif, and\nthe 0.2em offset scales with the type size. Keyboard focus mirrors hover so\nthe affordance is reachable without a pointer.",
+      "css": "@utility era-link {\n\t/* The text is bright at rest and never changes — the link reads as a link\n\t * before you touch it. Only the UNDERLINE reacts: a faint half-strength-muted\n\t * hint at rest that resolves to the full text colour on hover. */\n\tcolor: var(--color-bright);\n\ttext-decoration-line: underline;\n\ttext-decoration-color: color-mix(in oklch, var(--color-muted) 50%, transparent);\n\ttext-underline-offset: 0.2em;\n\ttransition: text-decoration-color var(--era-duration) var(--era-ease);\n\t&:hover,\n\t&:focus-visible {\n\t\ttext-decoration-color: var(--color-fg);\n\t}\n}"
+    },
+    {
+      "name": "scrollbar-none",
+      "file": "index.css",
+      "useCase": "hide the scrollbar on an overflowing strip or rail while keeping it scrollable — for a scroll region that should show its bar, use ScrollArea.",
+      "description": "Scrollable but chromeless — hides the scrollbar while keeping wheel / touch /\ndrag scrolling (e.g. an overflowing tab strip in a small pane handle).",
+      "css": "@utility scrollbar-none {\n\tscrollbar-width: none;\n\t&::-webkit-scrollbar {\n\t\tdisplay: none;\n\t}\n}"
+    },
+    {
+      "name": "era-text-trim",
+      "file": "index.css",
+      "useCase": "vertically center single-line control text (a label beside an icon, an input's own text) without a translateY nudge — fixed-height elements only; see era-text-trim-caps for ALL-CAPS strings.",
+      "description": "Font-agnostic vertical ink-centering for single-line control text.\nMeasured verdict (4 fonts x 2 dpr, ink from device-pixel screenshots):\nthe offset has TWO causes — a fractional line box (14px x 1.5lh = 21px in\na 24px row places ink on a half pixel, ~1px error) and font ascent/descent\nasymmetry (+-1px, sign flips per font). line-height: 1 fixes the first and\nis the Firefox fallback; text-box ex/alphabetic fixes the second by\ncentering the x-height band — the visual mass of MIXED-CASE text (caps and\ndescenders cancel above/below). cap alphabetic is the spec-example recipe\nbut is descender-blind (reads high; CSSWG #9148) — measured 4x worse here.\nWhere text-box is supported it fully determines the box, so the two\ndeclarations never fight. Worst-case residual: 0.44px.\n\nThe one hard rule concerns overflow clipping, and it is HEIGHT-conditional.\nOn an AUTO-height element that also clips — a `truncate` child, a\n<textarea>, an auto-height <input> — trim-both collapses the box to the\nx-height band (~7.5px at 14px) and the clip slices off every ascender, cap,\nand descender (text renders as a chopped middle stripe): NEVER do that.\nA FIXED-height control is the intended home, and is safe: the explicit\n`h-(--era-*)` overrides the collapse, so a single-line <input> (Input,\ncommand-input) and clipping display tokens (KV) correctly carry it. For\ntruncating text, put the trim on the fixed-height ROW and let the child\ncenter via the row's items-center.",
+      "css": "@utility era-text-trim {\n\tline-height: 1;\n\ttext-box: trim-both ex alphabetic;\n}"
+    },
+    {
+      "name": "era-text-trim-caps",
+      "file": "index.css",
+      "useCase": "the era-text-trim variant for ALL-CAPS single-line strings (kbd hints, acronym badges) — never use it for mixed-case text.",
+      "description": "ALL-CAPS single-line text (kbd hints, acronym badges): the x-height band\nmisjudges caps-only strings — cap/alphabetic edges are the right box.",
+      "css": "@utility era-text-trim-caps {\n\tline-height: 1;\n\ttext-box: trim-both cap alphabetic;\n}"
+    },
+    {
+      "name": "era-shimmer",
+      "file": "index.css",
+      "useCase": "the in-progress text treatment — put it on a \"working…\" / \"thinking…\" label while a task streams, instead of a spinner beside the text.",
+      "description": "In-progress text shimmer — a bright sweep through muted text (the standard\n\"working…\" label treatment in streaming UIs). Timing derives from the motion\naxis (10× --era-duration ≈ 1.5s at normal, 2.6s at extra); at instant the\nduration is 0s and the sweep freezes on its base frame — plain muted text —\nso reduced-motion and data-motion=\"instant\" both kill it for free.",
+      "css": "@utility era-shimmer {\n\tbackground: linear-gradient(\n\t\t110deg,\n\t\tvar(--color-muted) 0% 43%,\n\t\tvar(--color-bright) 50%,\n\t\tvar(--color-muted) 57% 100%\n\t);\n\tbackground-size: 200% 100%;\n\tbackground-clip: text;\n\t-webkit-text-fill-color: transparent;\n\tanimation: era-shimmer calc(var(--era-duration) * 10) cubic-bezier(0.7, 0, 1, 0.4) infinite;\n}"
+    },
+    {
+      "name": "glass-blur",
+      "file": "surfaces/glass.css",
+      "useCase": "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.",
+      "description": "Tailwind v4 cannot resolve var() inside backdrop-blur-[], so the filter\nis a registered utility, gated to glass subtrees.",
+      "css": "@utility glass-blur {\n\t[data-surface='glass'] & {\n\t\tbackdrop-filter: blur(var(--era-blur)) saturate(var(--era-saturate));\n\t\t-webkit-backdrop-filter: blur(var(--era-blur)) saturate(var(--era-saturate));\n\t}\n}"
+    }
   ]
 }

package/dist/generated-docs/scroll-area.md

@@ -55,3 +55,11 @@ Inherits all props from `ScrollArea.CornerProps`.
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | `ref?` | `(forwarded)` | `null` | bindable |
+
+## Notes
+
+- For a region that should scroll but show no scrollbar at all — an overflowing
+  tab strip, a chip rail, a small pane handle — you don't need ScrollArea: put
+  the `scrollbar-none` CSS utility on the overflowing element. See
+  [Utilities](/utilities.md). ScrollArea is for the case where the bar itself is
+  part of the design.

package/dist/generated-docs/utilities.json

@@ -0,0 +1,53 @@
+{
+  "utilities": [
+    {
+      "name": "era-interactive",
+      "file": "index.css",
+      "useCase": "the focus/disabled recipe every era control carries — put it on a custom interactive element instead of hand-writing focus/disabled variants.",
+      "description": "Shared interactive-state recipe: quiet focus, disabled affordance.\nEquivalent to `focus:outline-none disabled:cursor-not-allowed disabled:opacity-50`.",
+      "css": "@utility era-interactive {\n\t&:focus {\n\t\toutline: none;\n\t}\n\t&:disabled {\n\t\tcursor: not-allowed;\n\t\topacity: 0.5;\n\t}\n}"
+    },
+    {
+      "name": "era-link",
+      "file": "index.css",
+      "useCase": "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).",
+      "description": "Inline text link. An understated, permanent underline that darkens from\nmuted to the text colour on hover — no layout shift, no appearing/vanishing\nunderline. The colour fade rides the MOTION axis (--era-duration/-ease), so\nit snaps at data-motion=\"instant\", eases at \"normal\", and sweeps longer at\n\"extra\" — matching every other era transition. Font-agnostic: it styles\ndecoration + colour only, so it reads correctly in mono, sans, or serif, and\nthe 0.2em offset scales with the type size. Keyboard focus mirrors hover so\nthe affordance is reachable without a pointer.",
+      "css": "@utility era-link {\n\t/* The text is bright at rest and never changes — the link reads as a link\n\t * before you touch it. Only the UNDERLINE reacts: a faint half-strength-muted\n\t * hint at rest that resolves to the full text colour on hover. */\n\tcolor: var(--color-bright);\n\ttext-decoration-line: underline;\n\ttext-decoration-color: color-mix(in oklch, var(--color-muted) 50%, transparent);\n\ttext-underline-offset: 0.2em;\n\ttransition: text-decoration-color var(--era-duration) var(--era-ease);\n\t&:hover,\n\t&:focus-visible {\n\t\ttext-decoration-color: var(--color-fg);\n\t}\n}"
+    },
+    {
+      "name": "scrollbar-none",
+      "file": "index.css",
+      "useCase": "hide the scrollbar on an overflowing strip or rail while keeping it scrollable — for a scroll region that should show its bar, use ScrollArea.",
+      "description": "Scrollable but chromeless — hides the scrollbar while keeping wheel / touch /\ndrag scrolling (e.g. an overflowing tab strip in a small pane handle).",
+      "css": "@utility scrollbar-none {\n\tscrollbar-width: none;\n\t&::-webkit-scrollbar {\n\t\tdisplay: none;\n\t}\n}"
+    },
+    {
+      "name": "era-text-trim",
+      "file": "index.css",
+      "useCase": "vertically center single-line control text (a label beside an icon, an input's own text) without a translateY nudge — fixed-height elements only; see era-text-trim-caps for ALL-CAPS strings.",
+      "description": "Font-agnostic vertical ink-centering for single-line control text.\nMeasured verdict (4 fonts x 2 dpr, ink from device-pixel screenshots):\nthe offset has TWO causes — a fractional line box (14px x 1.5lh = 21px in\na 24px row places ink on a half pixel, ~1px error) and font ascent/descent\nasymmetry (+-1px, sign flips per font). line-height: 1 fixes the first and\nis the Firefox fallback; text-box ex/alphabetic fixes the second by\ncentering the x-height band — the visual mass of MIXED-CASE text (caps and\ndescenders cancel above/below). cap alphabetic is the spec-example recipe\nbut is descender-blind (reads high; CSSWG #9148) — measured 4x worse here.\nWhere text-box is supported it fully determines the box, so the two\ndeclarations never fight. Worst-case residual: 0.44px.\n\nThe one hard rule concerns overflow clipping, and it is HEIGHT-conditional.\nOn an AUTO-height element that also clips — a `truncate` child, a\n<textarea>, an auto-height <input> — trim-both collapses the box to the\nx-height band (~7.5px at 14px) and the clip slices off every ascender, cap,\nand descender (text renders as a chopped middle stripe): NEVER do that.\nA FIXED-height control is the intended home, and is safe: the explicit\n`h-(--era-*)` overrides the collapse, so a single-line <input> (Input,\ncommand-input) and clipping display tokens (KV) correctly carry it. For\ntruncating text, put the trim on the fixed-height ROW and let the child\ncenter via the row's items-center.",
+      "css": "@utility era-text-trim {\n\tline-height: 1;\n\ttext-box: trim-both ex alphabetic;\n}"
+    },
+    {
+      "name": "era-text-trim-caps",
+      "file": "index.css",
+      "useCase": "the era-text-trim variant for ALL-CAPS single-line strings (kbd hints, acronym badges) — never use it for mixed-case text.",
+      "description": "ALL-CAPS single-line text (kbd hints, acronym badges): the x-height band\nmisjudges caps-only strings — cap/alphabetic edges are the right box.",
+      "css": "@utility era-text-trim-caps {\n\tline-height: 1;\n\ttext-box: trim-both cap alphabetic;\n}"
+    },
+    {
+      "name": "era-shimmer",
+      "file": "index.css",
+      "useCase": "the in-progress text treatment — put it on a \"working…\" / \"thinking…\" label while a task streams, instead of a spinner beside the text.",
+      "description": "In-progress text shimmer — a bright sweep through muted text (the standard\n\"working…\" label treatment in streaming UIs). Timing derives from the motion\naxis (10× --era-duration ≈ 1.5s at normal, 2.6s at extra); at instant the\nduration is 0s and the sweep freezes on its base frame — plain muted text —\nso reduced-motion and data-motion=\"instant\" both kill it for free.",
+      "css": "@utility era-shimmer {\n\tbackground: linear-gradient(\n\t\t110deg,\n\t\tvar(--color-muted) 0% 43%,\n\t\tvar(--color-bright) 50%,\n\t\tvar(--color-muted) 57% 100%\n\t);\n\tbackground-size: 200% 100%;\n\tbackground-clip: text;\n\t-webkit-text-fill-color: transparent;\n\tanimation: era-shimmer calc(var(--era-duration) * 10) cubic-bezier(0.7, 0, 1, 0.4) infinite;\n}"
+    },
+    {
+      "name": "glass-blur",
+      "file": "surfaces/glass.css",
+      "useCase": "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.",
+      "description": "Tailwind v4 cannot resolve var() inside backdrop-blur-[], so the filter\nis a registered utility, gated to glass subtrees.",
+      "css": "@utility glass-blur {\n\t[data-surface='glass'] & {\n\t\tbackdrop-filter: blur(var(--era-blur)) saturate(var(--era-saturate));\n\t\t-webkit-backdrop-filter: blur(var(--era-blur)) saturate(var(--era-saturate));\n\t}\n}"
+    }
+  ]
+}

package/dist/generated-docs/utilities.md

@@ -0,0 +1,195 @@
+# Utilities
+
+The CSS classes era ships alongside the components — links, ink-centred text, shimmer, hidden scrollbars.
+
+## Overview
+
+era ships a handful of Tailwind v4 `@utility` classes for the patterns that are
+styling, not components — an inline link, ink-centred control text, a hidden
+scrollbar. They need no import: they ride along with the stylesheet.
+
+```ts
+import "@sig-nine/era-ui/css";
+```
+
+```svelte
+<a class="era-link" href="/spacing">the spacing ladder</a>
+```
+
+| Utility | Use it for |
+|---|---|
+| `era-interactive` | the focus/disabled recipe every era control carries — put it on a custom interactive element instead of hand-writing focus/disabled variants. |
+| `era-link` | 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). |
+| `scrollbar-none` | hide the scrollbar on an overflowing strip or rail while keeping it scrollable — for a scroll region that should show its bar, use ScrollArea. |
+| `era-text-trim` | vertically center single-line control text (a label beside an icon, an input's own text) without a translateY nudge — fixed-height elements only; see era-text-trim-caps for ALL-CAPS strings. |
+| `era-text-trim-caps` | the era-text-trim variant for ALL-CAPS single-line strings (kbd hints, acronym badges) — never use it for mixed-case text. |
+| `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. |
+| `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
+
+**Use it for:** the focus/disabled recipe every era control carries — put it on a custom interactive element instead of hand-writing focus/disabled variants.
+
+Shared interactive-state recipe: quiet focus, disabled affordance.
+Equivalent to `focus:outline-none disabled:cursor-not-allowed disabled:opacity-50`.
+
+Declared in `index.css`.
+
+```css
+@utility era-interactive {
+	&:focus {
+		outline: none;
+	}
+	&:disabled {
+		cursor: not-allowed;
+		opacity: 0.5;
+	}
+}
+```
+
+## era-link
+
+**Use it for:** 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).
+
+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.
+
+Declared in `index.css`.
+
+```css
+@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 half-strength-muted
+	 * hint at rest that resolves to the full text colour on hover. */
+	color: var(--color-bright);
+	text-decoration-line: underline;
+	text-decoration-color: color-mix(in oklch, var(--color-muted) 50%, transparent);
+	text-underline-offset: 0.2em;
+	transition: text-decoration-color var(--era-duration) var(--era-ease);
+	&:hover,
+	&:focus-visible {
+		text-decoration-color: var(--color-fg);
+	}
+}
+```
+
+## scrollbar-none
+
+**Use it for:** hide the scrollbar on an overflowing strip or rail while keeping it scrollable — for a scroll region that should show its bar, use ScrollArea.
+
+Scrollable but chromeless — hides the scrollbar while keeping wheel / touch /
+drag scrolling (e.g. an overflowing tab strip in a small pane handle).
+
+Declared in `index.css`.
+
+```css
+@utility scrollbar-none {
+	scrollbar-width: none;
+	&::-webkit-scrollbar {
+		display: none;
+	}
+}
+```
+
+## era-text-trim
+
+**Use it for:** vertically center single-line control text (a label beside an icon, an input's own text) without a translateY nudge — fixed-height elements only; see era-text-trim-caps for ALL-CAPS strings.
+
+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.
+
+The one hard rule concerns overflow clipping, and it is HEIGHT-conditional.
+On an AUTO-height element that also clips — a `truncate` child, a
+<textarea>, an auto-height <input> — trim-both collapses the box to the
+x-height band (~7.5px at 14px) and the clip slices off every ascender, cap,
+and descender (text renders as a chopped middle stripe): NEVER do that.
+A FIXED-height control is the intended home, and is safe: the explicit
+`h-(--era-*)` overrides the collapse, so a single-line <input> (Input,
+command-input) and clipping display tokens (KV) correctly carry it. For
+truncating text, put the trim on the fixed-height ROW and let the child
+center via the row's items-center.
+
+Declared in `index.css`.
+
+```css
+@utility era-text-trim {
+	line-height: 1;
+	text-box: trim-both ex alphabetic;
+}
+```
+
+## era-text-trim-caps
+
+**Use it for:** the era-text-trim variant for ALL-CAPS single-line strings (kbd hints, acronym badges) — never use it for mixed-case text.
+
+ALL-CAPS single-line text (kbd hints, acronym badges): the x-height band
+misjudges caps-only strings — cap/alphabetic edges are the right box.
+
+Declared in `index.css`.
+
+```css
+@utility era-text-trim-caps {
+	line-height: 1;
+	text-box: trim-both cap alphabetic;
+}
+```
+
+## era-shimmer
+
+**Use it for:** the in-progress text treatment — put it on a "working…" / "thinking…" label while a task streams, instead of a spinner beside the text.
+
+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.
+
+Declared in `index.css`.
+
+```css
+@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;
+}
+```
+
+## glass-blur
+
+**Use it for:** 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.
+
+Tailwind v4 cannot resolve var() inside backdrop-blur-[], so the filter
+is a registered utility, gated to glass subtrees.
+
+Declared in `surfaces/glass.css`.
+
+```css
+@utility glass-blur {
+	[data-surface='glass'] & {
+		backdrop-filter: blur(var(--era-blur)) saturate(var(--era-saturate));
+		-webkit-backdrop-filter: blur(var(--era-blur)) saturate(var(--era-saturate));
+	}
+}
+```