fix(hub-ui,json-render-ui): rewire baked Wind3 colors so branding's primaryColor actually retints the UI

Both shadow-root packages compile their utility CSS with Wind3, which bakes
theme colors to literal rgb() triplets at build time instead of referencing
CSS variables. --devframe-primary (branding's primaryColor) was only ever
consumed by the unused --colors-primary-* variables in primary-ramp.css, so
overriding it never reached any actual primary/bg-primary/btn-primary utility
- the dock, its hover states, and the settings panels stayed the default
sage green regardless of branding.

Post-process the compiled Wind3 CSS to rewrite each baked primary-ramp
triplet into CSS relative-color syntax (rgb(from var(--colors-primary-<stop>,
<hex>) r g b / <alpha>)), preserving Wind3's existing opacity mechanics while
sourcing the base color from the live variable. Verified end-to-end in
Chromium that overriding --devframe-primary now retints text-primary,
bg-primary, and btn-primary (including its hover/focus-ring states).

Author: antfubot

design/uno.config.ts

@@ -123,3 +123,57 @@ export const shadowSurfaceSafelist: string[] = [
   'color-active',
   'border-base',
 ]
+
+/**
+ * The primary-ramp stops a shadow-root surface's `primary-ramp.css` exposes
+ * as overridable `--colors-primary-<stop>` custom properties (derived from
+ * `--devframe-primary`). Must match that file's declarations exactly.
+ */
+const OVERRIDABLE_PRIMARY_STOPS = ['DEFAULT', '600', '500', '400', '300'] as const
+
+function hexToRgbTriplet(hex: string): string | undefined {
+  const match = /^#([0-9a-f]{6})$/i.exec(hex)
+  if (!match)
+    return undefined
+  const int = Number.parseInt(match[1], 16)
+  return `${(int >> 16) & 255} ${(int >> 8) & 255} ${int & 255}`
+}
+
+/**
+ * Rewire a Wind3-compiled shadow-root stylesheet's baked-in `primary` theme
+ * colors into CSS relative-color syntax reading the live `--colors-primary-*`
+ * variables `primary-ramp.css` derives from `--devframe-primary`.
+ *
+ * Wind3 (unlike Wind4) resolves each theme color to a literal `rgb(r g b /
+ * <alpha>)` at compile time — the `<alpha>` slot is already dynamic (a slash
+ * literal, or the utility's own `--un-*-opacity` variable), but the base `r g
+ * b` triplet is baked in, so every `primary`-based utility (`text-primary`,
+ * `bg-primary`, `btn-primary`, `ring-primary-500`, …) ignores
+ * `--devframe-primary` entirely — only hand-written rules that already
+ * reference `--colors-primary-*` directly (the dock's glow gradient,
+ * `primary-ramp.css` itself) retint. Swapping the baked triplet for `from
+ * var(--colors-primary-<stop>, <hex>) r g b` keeps that exact alpha
+ * mechanism intact while sourcing the base color from the variable — a
+ * rebrand's `--devframe-primary` now reaches every baked utility too.
+ *
+ * Call once per generated pass, after `generator.generate(...)`, passing the
+ * resolved `generator.config.theme.colors.primary` ramp.
+ *
+ * @param css - The compiled Wind3 CSS (pre-`--un-*` namespacing).
+ * @param primaryRamp - The generator's resolved `theme.colors.primary` ramp.
+ */
+export function rewireBakedPrimaryColors(css: string, primaryRamp: Record<string, string>): string {
+  let out = css
+  for (const stop of OVERRIDABLE_PRIMARY_STOPS) {
+    const hex = primaryRamp[stop]
+    const rgb = hex && hexToRgbTriplet(hex)
+    if (!rgb)
+      continue
+    const varName = stop === 'DEFAULT' ? '--colors-primary-DEFAULT' : `--colors-primary-${stop}`
+    out = out.replace(
+      new RegExp(String.raw`rgb\(${rgb}(?!\d)`, 'g'),
+      `rgb(from var(${varName}, ${hex}) r g b`,
+    )
+  }
+  return out
+}

packages/hub-ui/scripts/build-css.ts

@@ -6,7 +6,7 @@ import { colors as c } from 'devframe/utils/colors'
 import MagicString from 'magic-string'
 import { glob } from 'tinyglobby'
 import { createGenerator } from 'unocss'
-import { namespaceShadowCssVars, shadowSurfaceSafelist } from '../../../design/uno.config'
+import { namespaceShadowCssVars, rewireBakedPrimaryColors, shadowSurfaceSafelist } from '../../../design/uno.config'
 import config from '../uno.config'
 
 // Compile the components' UnoCSS output ahead of time into a plain string
@@ -69,14 +69,22 @@ export async function buildCSS(): Promise<void> {
   // a shortcut+variant interaction. Generate the shadow-surface tokens in a
   // dedicated pass so their plain (and `.dark`) rules are always present.
   const surfaces = await generator.generate(shadowSurfaceSafelist.join(' '))
+  // Wind3 bakes the `primary` theme color to literal `rgb()` triplets at
+  // generate-time — rewire them to read the live `--colors-primary-*`
+  // variables `primary-ramp.css` derives from `--devframe-primary`, so a
+  // rebrand actually retints `text-primary`/`bg-primary`/`btn-primary`/…
+  // (see `rewireBakedPrimaryColors`'s own comment).
+  const primaryTheme = (generator.config.theme as { colors?: Record<string, Record<string, string>> }).colors?.primary ?? {}
+  const unoCss = rewireBakedPrimaryColors(unoResult.css, primaryTheme)
+  const surfacesCss = rewireBakedPrimaryColors(surfaces.css, primaryTheme)
   // Namespace Wind's `--un-*` vars (→ `--un-hub-*`) so this shadow-root
   // stylesheet is immune to a host page's Wind4 `@property` registrations
   // (see `namespaceShadowCssVars`).
   const css = namespaceShadowCssVars([
     reset,
     userStyle.toString(),
-    unoResult.css,
-    surfaces.css,
+    unoCss,
+    surfacesCss,
     primaryRamp,
   ].join('\n'), '--un-hub-')
 

packages/hub-ui/src/client/.generated/css.ts

@@ -2,11 +2,11 @@
  * Primary color as a single overridable variable: `--devframe-primary`.
  *
  * Appended AFTER the UnoCSS output (see `scripts/build-css.ts`) so this block
- * wins over Wind4's own `:root, :host` primary declarations, and imported after
+ * wins over Wind3's own `:root, :host` primary declarations, and imported after
  * `virtual:uno.css` in the Storybook preview for the same reason.
  *
- * Each Wind4 stop (`--colors-primary-*`) is derived from `--devframe-primary`
- * via `color-mix`. When `--devframe-primary` is unset, the intermediate
+ * Each stop (`--colors-primary-*`) is derived from `--devframe-primary` via
+ * `color-mix`. When `--devframe-primary` is unset, the intermediate
  * `--devframe-primary-<stop>` vars become guaranteed-invalid (their `color-mix`
  * references an unset var with no fallback), so each `--colors-primary-<stop>`
  * falls back to the exact devframe default hex - the default look is preserved,
@@ -15,6 +15,16 @@
  * everything, and setting it on a group's chrome container retints just that
  * group (the group-accent mechanism).
  *
+ * The dock's shadow root is built on Wind3, which bakes `primary`-based
+ * utilities (`text-primary`, `bg-primary`, `btn-primary`, `ring-primary-500`,
+ * …) to literal `rgb()` triplets rather than referencing these variables —
+ * `scripts/build-css.ts` rewires those baked colors into CSS relative-color
+ * syntax reading `--colors-primary-<stop>` (see `rewireBakedPrimaryColors` in
+ * `design/uno.config.ts`) so this block actually retints them, not just the
+ * handful of rules (the glow gradient below) that reference the variables
+ * directly. The stops declared here (`DEFAULT`/`600`/`500`/`400`/`300`) must
+ * match `OVERRIDABLE_PRIMARY_STOPS` there.
+ *
  * `:host` is the effective selector inside the dock's shadow root; `:root` is
  * for the light-DOM Storybook preview (it matches nothing in the shadow root).
  *

packages/hub-ui/src/client/primary-ramp.css

@@ -5,7 +5,7 @@ import { fileURLToPath } from 'node:url'
 import { colors as c } from 'devframe/utils/colors'
 import { glob } from 'tinyglobby'
 import { createGenerator } from 'unocss'
-import { namespaceShadowCssVars, shadowSurfaceSafelist } from '../../../design/uno.config'
+import { namespaceShadowCssVars, rewireBakedPrimaryColors, shadowSurfaceSafelist } from '../../../design/uno.config'
 import config from '../uno.config'
 
 // Compile the renderer's UnoCSS output ahead of time into a plain string
@@ -62,13 +62,21 @@ export async function buildCSS(): Promise<void> {
   // a shortcut+variant interaction. Generate the shadow-surface tokens in a
   // dedicated pass so their plain (and `.dark`) rules are always present.
   const surfaces = await generator.generate(shadowSurfaceSafelist.join(' '))
+  // Wind3 bakes the `primary` theme color to literal `rgb()` triplets at
+  // generate-time — rewire them to read the live `--colors-primary-*`
+  // variables `primary-ramp.css` derives from `--devframe-primary`, so a
+  // rebranded hub actually retints the rendered views (see
+  // `rewireBakedPrimaryColors`'s own comment).
+  const primaryTheme = (generator.config.theme as { colors?: Record<string, Record<string, string>> }).colors?.primary ?? {}
+  const unoCss = rewireBakedPrimaryColors(unoResult.css, primaryTheme)
+  const surfacesCss = rewireBakedPrimaryColors(surfaces.css, primaryTheme)
   // Namespace Wind's `--un-*` vars (→ `--un-jr-*`) so this shadow-root
   // stylesheet is immune to a host page's Wind4 `@property` registrations
   // (see `namespaceShadowCssVars`).
   const css = namespaceShadowCssVars([
     reset,
-    unoResult.css,
-    surfaces.css,
+    unoCss,
+    surfacesCss,
     primaryRamp,
   ].join('\n'), '--un-jr-')
 

packages/json-render-ui/scripts/build-css.ts

@@ -2,16 +2,24 @@
  * Primary color as a single overridable variable: `--devframe-primary`.
  *
  * Mirrors `@devframes/hub-ui`'s ramp (see its `src/client/primary-ramp.css`
- * for the full derivation notes): each Wind4 stop (`--colors-primary-*`) is
+ * for the full derivation notes): each stop (`--colors-primary-*`) is
  * derived from `--devframe-primary` via `color-mix`, falling back to the
  * devframe default sage green when it is unset.
  *
  * Appended AFTER the UnoCSS output (see `scripts/build-css.ts`) so this block
- * wins over Wind4's own `:root, :host` primary declarations. `:host` is the
+ * wins over Wind3's own `:root, :host` primary declarations. `:host` is the
  * effective selector inside the renderer module's shadow root — its host is
  * the viewer-owned mount container, and `--devframe-primary` (set by a
  * viewer's branding on any ancestor) inherits across the shadow boundary onto
  * it, so a rebranded hub retints the rendered views too.
+ *
+ * The renderer module's shadow root is built on Wind3, which bakes
+ * `primary`-based utilities to literal `rgb()` triplets rather than
+ * referencing these variables — `scripts/build-css.ts` rewires those baked
+ * colors into CSS relative-color syntax reading `--colors-primary-<stop>`
+ * (see `rewireBakedPrimaryColors` in `design/uno.config.ts`) so this block
+ * actually retints them. The stops declared here (`DEFAULT`/`600`/`500`/
+ * `400`/`300`) must match `OVERRIDABLE_PRIMARY_STOPS` there.
  */
 :root,
 :host {