@signal9/era-ui 2.26.0 → 2.27.0

package/dist/styles/index.css

@@ -36,7 +36,10 @@
 }
 
 /* Shared interactive-state recipe: quiet focus, disabled affordance.
- * Equivalent to `focus:outline-none disabled:cursor-not-allowed disabled:opacity-50`. */
+ * 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;
@@ -54,7 +57,11 @@
  * "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. */
+ * 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 half-strength-muted
@@ -71,7 +78,10 @@
 }
 
 /* Scrollable but chromeless — hides the scrollbar while keeping wheel / touch /
- * drag scrolling (e.g. an overflowing tab strip in a small pane handle). */
+ * 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 {
@@ -101,6 +111,10 @@
  * 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.
+ *
+ * @use 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.
  */
 @utility era-text-trim {
 	line-height: 1;
@@ -108,7 +122,10 @@
 }
 
 /* ALL-CAPS single-line text (kbd hints, acronym badges): the x-height band
- * misjudges caps-only strings — cap/alphabetic edges are the right box. */
+ * 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 use it for mixed-case text. */
 @utility era-text-trim-caps {
 	line-height: 1;
 	text-box: trim-both cap alphabetic;
@@ -118,7 +135,10 @@
  * "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. */
+ * 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,

package/dist/styles/surfaces/glass.css

@@ -118,7 +118,11 @@
 }
 
 /* Tailwind v4 cannot resolve var() inside backdrop-blur-[], so the filter
- * is a registered utility, gated to glass subtrees. */
+ * is a registered utility, gated to glass subtrees.
+ *
+ * @use 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. */
 @utility glass-blur {
 	[data-surface='glass'] & {
 		backdrop-filter: blur(var(--era-blur)) saturate(var(--era-saturate));

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@signal9/era-ui",
-	"version": "2.26.0",
+	"version": "2.27.0",
 	"scripts": {
 		"dev": "vite dev --host",
 		"build": "vite build && npm run prepack",
@@ -65,7 +65,8 @@
 		},
 		"./css": "./dist/era-ui.css",
 		"./styles/raw": "./dist/styles/index.css",
-		"./styles/themes": "./dist/styles/themes.css"
+		"./styles/themes": "./dist/styles/themes.css",
+		"./utilities.json": "./dist/generated-docs/utilities.json"
 	},
 	"peerDependencies": {
 		"svelte": "^5.0.0",

package/skill/SKILL.md

@@ -115,6 +115,23 @@ motion-axis-aware for free.
 - Headings balance and prose wraps pretty automatically — don't re-add
   `text-balance`/`text-pretty` except on non-semantic prose elements.
 
+## CSS utilities (classes, not components)
+
+Not everything era exposes is a component — these ride along with the stylesheet
+and need no import. Reach for one before hand-rolling the same styling or bending
+a component into the role. Full reference: `/utilities.md`; machine-readable list:
+`/utilities.json` (or `@sig-nine/era-ui/utilities.json`).
+
+| Class                | Use it for                                                                                                             |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `era-link`           | inline text link in body copy/prose — NOT `Button variant="link"` (that's a control) and never a hand-rolled underline |
+| `era-interactive`    | the focus/disabled recipe on a custom control (every era wrapper carries it)                                           |
+| `era-text-trim`      | ink-centering single-line control text beside an icon; fixed-height elements only                                      |
+| `era-text-trim-caps` | the same for ALL-CAPS strings (kbd hints, acronym badges)                                                              |
+| `era-shimmer`        | a "working…" / streaming label — motion-aware, dies at `instant` and under reduced-motion                              |
+| `scrollbar-none`     | an overflowing strip that scrolls with no visible bar (ScrollArea is for when the bar IS the design)                   |
+| `glass-blur`         | backdrop blur on a floating panel; inert outside a `data-surface="glass"` subtree                                      |
+
 ## Composing the library
 
 ```svelte