@jdcpuwiz/homelab-ui 0.7.1 → 0.9.0

package/globals.css

@@ -13,6 +13,21 @@
  *
  * Override any token at `:root` in your own CSS to re-skin a project
  * without forking the package.
+ *
+ * THE RULE FOR (1) — a component must reference a token as
+ * `bg-[var(--hl-card)]`, NEVER as the literal `bg-[#1e1e1e]`. Both compile
+ * to the same pixels for a default-palette app, which is exactly why the
+ * literal form went unnoticed: until 0.8.0 the components hardcoded
+ * #ff9900 / #111111 / #1e1e1e / #252525 / #2a2620 / #f0f1f4, so a project
+ * that overrode those vars STILL rendered the fleet palette and had no
+ * error to go on. zoo-genes (green brand, warm near-blacks) shipped a
+ * scoped CSS override to claw its own theme back. Prefer the arbitrary
+ * `var()` form over the preset's `bg-card` shorthand inside this package:
+ * it keeps property (1) — a consumer who skips the preset still gets the
+ * color, which the shorthand cannot give them.
+ *
+ * Status colors (#b91c1c danger etc.) are deliberately NOT tokens — they
+ * are a fixed fleet semantic, identical in every app.
  */
 
 :root {
@@ -23,8 +38,40 @@
      single shade. Hierarchy comes from size/weight, never from a dimmer
      grey. zoo-vet's render became canonical; the fleet moves brighter
      from the old #e2e4e9/#ededed. The text-white/60·/40·/30 opacity ramp
-     is dead. */
+     is dead AS A HIERARCHY DEVICE — what survives it is the two dimmed
+     chrome steps immediately below, which are tokens, not literals. */
   --hl-foreground: #f0f1f4;
+  /* The two dimmed steps, and the ONLY two (C461). Until 0.9.0 the
+     components wrote a literal `text-white/45 · /40 · /30 · /20 · /60`
+     ramp with no token behind any of it, so a re-skinned app (zoo-genes:
+     warm near-blacks, warm off-white foreground) got COLD grey chrome —
+     inactive nav rows, breadcrumbs, close buttons — against a warm
+     palette, with nothing to override.
+
+     Two steps, not five. BP #57 killed the ramp as a hierarchy device
+     (hierarchy is size/weight on the one flat --hl-foreground), so these
+     exist for the two jobs that survive it:
+
+       MUTED  text you can still read but that is deliberately secondary
+              and usually interactive — an inactive nav row, a breadcrumb
+              you can click, a back link, a close button, a tertiary
+              button, a "Loading…" line. Hovering one takes it to the
+              full --hl-foreground.
+       FAINT  chrome you do NOT read — breadcrumb chevrons, an empty-state
+              icon, the dashed placeholder art, the footer version stamp.
+              Never put a sentence in this.
+
+     Defaults are white-alpha so a default-palette (fleet orange) app is
+     visually unchanged; override them with your OWN foreground at any
+     alpha to keep the chrome in your palette, e.g.
+       :root { --hl-foreground-muted: rgba(216, 208, 200, 0.55); }
+     Do NOT add a third step to reintroduce the ramp. */
+  --hl-foreground-muted: rgba(255, 255, 255, 0.45);
+  --hl-foreground-faint: rgba(255, 255, 255, 0.3);
+  /* The wash under a hovered nav row / ghost control. Same story: it was
+     a literal `hover:bg-white/5`, which lightens a warm surface toward
+     cold grey. Override with your own tint. */
+  --hl-hover-overlay: rgba(255, 255, 255, 0.05);
   --hl-sidebar: #111111;
   --hl-content: #0d0d0d;
   --hl-card: #1e1e1e;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jdcpuwiz/homelab-ui",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "description": "Shared dark-theme UI primitives for the JdCpuWiz homelab \u2014 Sidebar, Button, Modal, PageHeader, TagChips, plus the canonical Tailwind preset, CSS vars, and the sanctioned three-face typography (Poppins / Orbitron / JetBrains Mono) on one flat #f0f1f4 text color.",
   "license": "MIT",
   "author": "Wiz <shad@deckerzoo.com>",

package/tailwind-preset.cjs

@@ -19,7 +19,8 @@
  *   bg-status-success / bg-status-info / bg-status-warning / bg-status-danger /
  *     bg-status-special / bg-status-neutral / bg-status-empty / bg-status-primary
  *   border-border / border-input / border-input-hover
- *   bg-overlay / bg-overlay-chip
+ *   bg-overlay / bg-overlay-chip / bg-overlay-hover
+ *   text-foreground / text-foreground-muted / text-foreground-faint
  *   text-title / text-ink-primary / text-ink-secondary / text-ink-tertiary
  *   accent-upload / accent-download / accent-error-text / accent-live
  *   rounded-widget / rounded-row / rounded-chip / rounded-panel
@@ -41,7 +42,15 @@ module.exports = {
     extend: {
       colors: {
         background: "var(--hl-background)",
-        foreground: "var(--hl-foreground)",
+        // `foreground` alone is unchanged (`text-foreground` still resolves
+        // to the one flat reading colour). `-muted` / `-faint` are the two
+        // dimmed CHROME steps added in 0.9.0 — see globals.css for which is
+        // which and why there are only two.
+        foreground: {
+          DEFAULT: "var(--hl-foreground)",
+          muted: "var(--hl-foreground-muted)",
+          faint: "var(--hl-foreground-faint)",
+        },
         sidebar: "var(--hl-sidebar)",
         content: "var(--hl-content)",
         card: {
@@ -81,6 +90,10 @@ module.exports = {
         overlay: {
           DEFAULT: "rgba(0,0,0,0.9)",
           chip: "rgba(0,0,0,0.6)",
+          // The wash under a hovered nav row / ghost control (0.9.0).
+          // `hover:bg-overlay-hover` — themeable, unlike the old literal
+          // `hover:bg-white/5` it replaces.
+          hover: "var(--hl-hover-overlay)",
         },
         // Reading text is ONE flat shade (BP #57). The old /60·/40·/30
         // opacity ramp is dead — hierarchy comes from size/weight, not a
@@ -88,12 +101,15 @@ module.exports = {
         // back-compat aliases but now ALL resolve to the one flat
         // foreground, so a consumer still on `text-ink-secondary` renders
         // the standard automatically. `disabled` stays a genuine dim — it
-        // marks a disabled affordance, not reading text.
+        // marks a disabled affordance, not reading text — and as of 0.9.0
+        // it reads the `--hl-foreground-faint` token rather than repeating
+        // that literal rgba, so a re-skinned app themes it with everything
+        // else.
         ink: {
           primary: "var(--hl-foreground)",
           secondary: "var(--hl-foreground)",
           tertiary: "var(--hl-foreground)",
-          disabled: "rgba(255,255,255,0.30)",
+          disabled: "var(--hl-foreground-faint)",
         },
       },
       // Typography — three self-hosted faces by job (Wiz ruling 2026-07-24,