@signal9/era-ui 2.25.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/bevel.css

@@ -91,9 +91,64 @@
 	 * the icon/label depresses like a Win95 keycap pushed in from the top-left. */
 	--era-press-sink-x: 1px;
 	--era-press-sink-y: 1px;
+	/* Angle of the shade a pressed face sits under, DERIVED from the one light
+	 * knob rather than picked by eye: the shadow runs along the light's own
+	 * direction vector (side, 1), so relighting the surface relights it too.
+	 * side=1 → 135deg (the classic corner-lit diagonal); side=0.6 → ~149deg, the
+	 * light rotated toward straight-above. Falls from the TOP-LEFT because that is
+	 * the corner a well leaves in shade (see --era-shadow-well: dark chisel on
+	 * top/left, lit chisel on bottom/right — the exact inverse of a raised face). */
+	--era-bevel-press-angle: calc(180deg - atan2(var(--era-bevel-side), 1));
+	--era-bevel-press-shade: light-dark(oklch(0 0 0 / 0.2), oklch(0 0 0 / 0.28));
 	/* Floating panels wear a 2-layer chisel frame; row highlights inset past
 	 * it with a concentric radius (square under data-corners="square", as
 	 * the era had it — Win95 drew its selection bar inside the border). */
 	--era-panel-inset: 2px;
 	--era-item-rd-scale: 1;
 }
+
+/*
+ * PRESS SHADE — the shadow a sunken face sits under (icon buttons).
+ *
+ * Pressing a bevel button turns its face into a well, and the frame's lit edge
+ * then casts a shade down into it. The chisel alone can't express that: it draws
+ * the WALLS of the well but leaves the floor evenly lit, so a pressed icon looked
+ * exactly as bright as a raised one — the glyph read as floating above the recess
+ * instead of sitting in it.
+ *
+ * The film lies ABOVE the content, not under it, and that is the whole point: a
+ * shadow cast into a well falls across whatever is in the well, glyph included.
+ * The icon darkens WITH the face it sits on rather than hovering over it,
+ * untouched. It rides the frame, not the content — `[&:active>*]` sinks the
+ * icon 1px, but the shade holds still, because the frame is what casts it.
+ *
+ * The overlay is always mounted at opacity 0 so the fade can ride the motion
+ * axis (0s at instant → it snaps; longer at extra). A pseudo-element that only
+ * came into being on :active would have nothing to transition FROM.
+ *
+ * `link` buttons are excluded: they are chromeless tinted text with no face, and
+ * a film laid over prose is just dirt. Bevel is the only surface that does this —
+ * flat and glass express press as tone, and cartoon flattens the sticker.
+ */
+[data-surface='bevel'] button:not([data-variant='link']):has(svg) {
+	position: relative;
+}
+
+[data-surface='bevel'] button:not([data-variant='link']):has(svg)::after {
+	content: '';
+	position: absolute;
+	inset: 0;
+	border-radius: inherit;
+	pointer-events: none;
+	opacity: 0;
+	background-image: linear-gradient(
+		var(--era-bevel-press-angle),
+		var(--era-bevel-press-shade),
+		transparent 70%
+	);
+	transition: opacity var(--era-duration) var(--era-ease);
+}
+
+[data-surface='bevel'] button:not([data-variant='link']):has(svg):active::after {
+	opacity: 1;
+}

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/dist/ui/button/button.svelte

@@ -46,12 +46,18 @@
 	hover sweep is what surfaced this — a latched button correctly shows no hover
 	delta (it must keep its pressed face), but with no attribute to read, that is
 	indistinguishable from a control with no hover state at all.
+
+	`variant` is exposed for the same reason: a surface has to be able to tell a
+	chromed button from a chromeless `link` one. bevel's press shade is a film laid
+	over the button's face, which a link button does not have — and a class is not
+	something CSS can ask about.
 -->
 <Button.Root
 	bind:ref
 	disabled={effectiveDisabled}
 	aria-busy={loading || undefined}
 	data-state={active ? 'on' : undefined}
+	data-variant={variant}
 	class={cn(buttonVariants({ variant, tone, size, icon, active }), className)}
 	{...restProps}
 >

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@signal9/era-ui",
-	"version": "2.25.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