@oxyhq/bloom 0.7.7 → 0.8.1

package/src/theme/__tests__/color-space.test.ts

@@ -0,0 +1,28 @@
+import { oklchToSrgb, srgbToRgbString, parseRgbString, deltaE } from '../color-space';
+
+describe('color-space', () => {
+  it('converts oklch white/black correctly', () => {
+    expect(oklchToSrgb({ l: 1, c: 0, h: 0 })).toEqual({ r: 255, g: 255, b: 255 });
+    expect(oklchToSrgb({ l: 0, c: 0, h: 0 })).toEqual({ r: 0, g: 0, b: 0 });
+  });
+  it('round-trips a known oxy purple within ΔE 1', () => {
+    // hsl(277 66% 56%) === rgb(160 69 217) (current oracle)
+    const rgb = oklchToSrgb({ l: 0.5783, c: 0.22, h: 309.31 });
+    expect(deltaE(rgb, { r: 160, g: 69, b: 217 })).toBeLessThanOrEqual(1.0);
+  });
+  it('formats rgb as space-separated modern syntax', () => {
+    expect(srgbToRgbString({ r: 31, g: 153, b: 239 })).toBe('rgb(31 153 239)');
+    expect(srgbToRgbString({ r: 31, g: 153, b: 239 }, 0.1)).toBe('rgb(31 153 239 / 0.1)');
+  });
+  it('parses modern + legacy rgb strings', () => {
+    expect(parseRgbString('rgb(31 153 239)')).toEqual({ r: 31, g: 153, b: 239 });
+    expect(parseRgbString('rgb(31, 153, 239)')).toEqual({ r: 31, g: 153, b: 239 });
+  });
+  it('throws loudly on non-rgb input instead of silently returning black', () => {
+    expect(() => parseRgbString('277 50% 5%')).toThrow(
+      'parseRgbString: expected an rgb() string, got: 277 50% 5%',
+    );
+    expect(() => parseRgbString('hsl(277 50% 5%)')).toThrow(/expected an rgb\(\) string/);
+    expect(() => parseRgbString('')).toThrow(/expected an rgb\(\) string/);
+  });
+});

package/src/theme/__tests__/golden-tokens.test.ts

@@ -0,0 +1,33 @@
+import goldenResolvedTokens from './__fixtures__/golden-resolved-tokens.json';
+import { APP_COLOR_NAMES } from '../color-presets';
+import { getResolvedTokens } from '../token-registry';
+
+// `golden-resolved-tokens.json` is the FROZEN parity oracle: the exact resolved
+// rgb for every preset×mode×token that the legacy resolved-color pipeline
+// produced (captured once, each resolved-color key remapped to its base `--X`).
+// It is IMMUTABLE — never regenerate it to chase new output. These tests prove
+// the canonical `getResolvedTokens` pipeline reproduces that palette EXACTLY
+// (byte-for-byte rgb), so the refactor to a single rgb token pipeline does not
+// shift a single color.
+const fixture = goldenResolvedTokens as Record<string, Record<string, string>>;
+
+describe('golden token parity (frozen oracle)', () => {
+  for (const name of APP_COLOR_NAMES) {
+    for (const mode of ['light', 'dark'] as const) {
+      it(`${name}/${mode} resolves to the frozen rgb palette exactly`, () => {
+        const expected = fixture[`${name}/${mode}`];
+        expect(expected).toBeDefined();
+
+        const resolved = getResolvedTokens(name, mode);
+        // For every token the oracle ever resolved, the canonical pipeline must
+        // produce the identical rgb string. (The fixture covers exactly the keys
+        // that had a resolved-color companion; extended-only tokens —
+        // chart-*/sidebar-*/content-area — were never in the rgb oracle and are
+        // covered by the canonical-token coverage test instead.)
+        const actual: Record<string, string | undefined> = {};
+        for (const key of Object.keys(expected ?? {})) actual[key] = resolved[key];
+        expect(actual).toEqual(expected);
+      });
+    }
+  }
+});

package/src/theme/__tests__/runtime-contract.test.ts

@@ -0,0 +1,63 @@
+/**
+ * @jest-environment jsdom
+ */
+
+import normalizeColor from '@react-native/normalize-colors';
+import { Platform } from 'react-native';
+
+import { buildTheme } from '../build-theme';
+import { applyColorPresetVars } from '../apply-dark-class';
+import { getResolvedTokens } from '../token-registry';
+
+// `@react-native/normalize-colors` is the exact parser React Native (native) and
+// react-native-web use behind `StyleSheet`/`processColor`. If it returns `null`
+// for a value, that color is UNPARSEABLE and the element renders nothing. These
+// tests pin the runtime contract for the canonical rgb token pipeline: every
+// JS `theme.colors` value must parse, the web document vars must be full colors
+// (not bare HSL triples), and the historically mislabeled aliases must be fixed.
+
+it('every theme.colors value parses via normalize-colors (native/RNW StyleSheet)', () => {
+  const { colors } = buildTheme('oxy', 'dark');
+  for (const v of Object.values(colors)) {
+    expect(normalizeColor(v)).not.toBeNull(); // null = unparseable -> renders nothing
+  }
+});
+
+describe('web var(--primary) resolves to a real color (not a bare triple)', () => {
+  const originalOS = Platform.OS;
+
+  beforeEach(() => {
+    Platform.OS = 'web';
+    document.documentElement.removeAttribute('style');
+  });
+
+  afterEach(() => {
+    Platform.OS = originalOS;
+    document.documentElement.removeAttribute('style');
+  });
+
+  it('writes --primary as a resolved rgb() color', () => {
+    applyColorPresetVars('oxy', 'dark');
+    const v = document.documentElement.style.getPropertyValue('--primary').trim();
+    expect(v).toMatch(/^rgb\(/);
+    expect(normalizeColor(v)).not.toBeNull();
+  });
+});
+
+it('restored legacy alias invariants hold', () => {
+  // Pre-0.8.0 semantics, restored in 0.8.1: `secondary` mirrors `primary`,
+  // `card` and `primaryLight` are the page surface, `primaryDark` is the page
+  // background. All read straight from the same resolved rgb token map, so the
+  // alias values are byte-identical to their source tokens.
+  for (const preset of ['oxy', 'blue'] as const) {
+    for (const mode of ['light', 'dark'] as const) {
+      const { colors } = buildTheme(preset, mode);
+      const t = getResolvedTokens(preset, mode);
+      expect(colors.secondary).toBe(colors.primary);
+      expect(colors.secondary).toBe(t['--primary']);
+      expect(colors.card).toBe(t['--surface']);
+      expect(colors.primaryLight).toBe(t['--surface']);
+      expect(colors.primaryDark).toBe(t['--background']);
+    }
+  }
+});

package/src/theme/__tests__/theme-colors-parity.test.ts

@@ -0,0 +1,115 @@
+/**
+ * @jest-environment node
+ */
+
+import normalizeColor from '@react-native/normalize-colors';
+
+import { buildTheme } from '../build-theme';
+import type { AppColorName } from '../color-presets';
+import type { ThemeColors } from '../types';
+
+// Parity guard for the 0.8.1 restoration of the pre-0.8.0 `theme.colors`
+// derived/alias values. 0.8.0 changed several derived/alias mappings, visibly
+// altering dark (and light) mode for consuming components. 0.8.1 restores the
+// EXACT pre-0.8.0 colors while keeping the single rgb pipeline (the old logic
+// emitted `hsl(h,s%,l%)` strings; the new logic emits the `rgb(...)` of the same
+// color). These oracles are the VERBATIM pre-0.8.0 outputs (commit 00a4cf3:
+// `git show 00a4cf3:src/theme/build-theme.ts`). We assert visual equality via
+// ΔE on the parsed sRGB — `hsl(...)` and the matching `rgb(...)` parse to the
+// same bytes under the RN/RNW/browser `normalizeColor`, so ΔE is 0.
+
+type Rgb = { r: number; g: number; b: number };
+
+function parse(color: string): Rgb {
+  const n = normalizeColor(color);
+  if (n === null || n === undefined) {
+    throw new Error(`unparseable color: ${color}`);
+  }
+  // normalizeColor returns 0xRRGGBBAA.
+  return { r: (n >>> 24) & 0xff, g: (n >>> 16) & 0xff, b: (n >>> 8) & 0xff };
+}
+
+function deltaE(a: Rgb, b: Rgb): number {
+  return Math.sqrt((a.r - b.r) ** 2 + (a.g - b.g) ** 2 + (a.b - b.b) ** 2) / Math.sqrt(3);
+}
+
+/**
+ * The pre-0.8.0 `theme.colors` for a (preset, mode) pair, expressed in the EXACT
+ * source forms commit 00a4cf3 produced — token-backed values as `hsl(H, S%, L%)`
+ * (from the preset's raw triples) and computed tints via `hsl(hue, s%, l%)`.
+ *
+ * We only assert the fields the restoration touches plus the load-bearing
+ * aliases (primaryLight/primaryDark/secondary/card). Status colors and
+ * shadow/overlay were never changed, so they are intentionally omitted.
+ */
+type Oracle = Partial<Record<keyof ThemeColors, string>>;
+
+const ORACLES: Array<{ preset: AppColorName; mode: 'light' | 'dark'; old: Oracle }> = [
+  {
+    // blue: primary 205 87% 53%, surface dark 205 20% 18%, background dark 205 50% 5%, destructive hue 0.
+    preset: 'blue',
+    mode: 'dark',
+    old: {
+      secondary: 'hsl(205, 87%, 53%)', // == primary
+      primary: 'hsl(205, 87%, 53%)',
+      card: 'hsl(205, 20%, 18%)', // == surface
+      primaryLight: 'hsl(205, 20%, 18%)', // == surface
+      primaryDark: 'hsl(205, 50%, 5%)', // == background
+      primarySubtle: 'hsl(205, 50%, 10%)',
+      primarySubtleForeground: 'hsl(205, 70%, 65%)',
+      negative: 'hsl(0, 84%, 45%)',
+      negativeForeground: '#FFFFFF',
+      negativeSubtle: 'hsl(0, 50%, 10%)',
+      negativeSubtleForeground: 'hsl(0, 70%, 65%)',
+      contrast50: 'hsl(205, 15%, 12%)',
+    },
+  },
+  {
+    // oxy: primary 277 66% 56%, surface dark 277 20% 18%, background dark 277 50% 5%, destructive hue 0.
+    preset: 'oxy',
+    mode: 'dark',
+    old: {
+      secondary: 'hsl(277, 66%, 56%)',
+      primary: 'hsl(277, 66%, 56%)',
+      card: 'hsl(277, 20%, 18%)',
+      primaryLight: 'hsl(277, 20%, 18%)',
+      primaryDark: 'hsl(277, 50%, 5%)',
+      primarySubtle: 'hsl(277, 50%, 10%)',
+      primarySubtleForeground: 'hsl(277, 70%, 65%)',
+      negative: 'hsl(0, 84%, 45%)',
+      negativeForeground: '#FFFFFF',
+      negativeSubtle: 'hsl(0, 50%, 10%)',
+      negativeSubtleForeground: 'hsl(0, 70%, 65%)',
+      contrast50: 'hsl(277, 15%, 12%)',
+    },
+  },
+  {
+    // blue light: surface 205 58% 94%, background 205 55% 96%.
+    preset: 'blue',
+    mode: 'light',
+    old: {
+      secondary: 'hsl(205, 87%, 53%)',
+      primary: 'hsl(205, 87%, 53%)',
+      card: 'hsl(205, 58%, 94%)',
+      primaryLight: 'hsl(205, 58%, 94%)',
+      primaryDark: 'hsl(205, 55%, 96%)',
+      primarySubtle: 'hsl(205, 70%, 93%)',
+      primarySubtleForeground: 'hsl(205, 90%, 25%)',
+      negative: 'hsl(0, 84%, 45%)',
+      negativeForeground: '#FFFFFF',
+      negativeSubtle: 'hsl(0, 90%, 95%)',
+      negativeSubtleForeground: 'hsl(0, 80%, 40%)',
+      contrast50: 'hsl(205, 10%, 93%)',
+    },
+  },
+];
+
+describe.each(ORACLES)('theme.colors parity with pre-0.8.0 ($preset/$mode)', ({ preset, mode, old }) => {
+  const { colors } = buildTheme(preset, mode);
+
+  it.each(Object.entries(old))('%s matches the pre-0.8.0 color (ΔE ≤ 1)', (key, oldColor) => {
+    const newColor = colors[key as keyof ThemeColors];
+    const dE = deltaE(parse(oldColor), parse(newColor));
+    expect(dE).toBeLessThanOrEqual(1);
+  });
+});

package/src/theme/__tests__/token-registry.test.ts

@@ -0,0 +1,30 @@
+import goldenResolvedTokens from './__fixtures__/golden-resolved-tokens.json';
+import { CANONICAL_TOKENS, getResolvedTokens } from '../token-registry';
+import { APP_COLOR_NAMES } from '../color-presets';
+import { getPresetVars } from '../preset-vars';
+
+const fixture = goldenResolvedTokens as Record<string, Record<string, string>>;
+
+it('canonical token list covers every base+extended preset var', () => {
+  const fromPreset = Object.keys(getPresetVars('oxy', 'light'));
+  for (const k of fromPreset) expect(CANONICAL_TOKENS).toContain(k.replace(/^--/, ''));
+});
+
+describe('getResolvedTokens parity vs frozen oracle (exact rgb)', () => {
+  for (const name of APP_COLOR_NAMES) {
+    for (const mode of ['light', 'dark'] as const) {
+      it(`${name}/${mode}`, () => {
+        const oracle = fixture[`${name}/${mode}`];
+        expect(oracle).toBeDefined();
+
+        const resolved = getResolvedTokens(name, mode); // Record<'--x','rgb(...)'>
+        for (const [base, oracleRgb] of Object.entries(oracle ?? {})) {
+          expect(resolved[base]).toBeDefined();
+          // Exact match — the canonical pipeline reproduces the legacy
+          // resolved-color rgb byte-for-byte, so there is no palette drift.
+          expect(resolved[base]).toBe(oracleRgb);
+        }
+      });
+    }
+  }
+});

package/src/theme/__tests__/visual-gallery.test.tsx

@@ -0,0 +1,10 @@
+import { buildTheme } from '../build-theme';
+import { APP_COLOR_NAMES } from '../color-presets';
+
+it('theme.colors snapshot for all presets (catches unintended palette shifts)', () => {
+  const all = Object.fromEntries(
+    APP_COLOR_NAMES.flatMap((n) => (['light', 'dark'] as const).map(
+      (m) => [`${n}/${m}`, buildTheme(n, m).colors] as const)),
+  );
+  expect(all).toMatchSnapshot();
+});

package/src/theme/apply-dark-class.ts

@@ -1,11 +1,6 @@
 import { Platform } from 'react-native';
 import { APP_COLOR_PRESETS, type AppColorName } from './color-presets';
-import { getPresetVars, toWebColorValue } from './preset-vars';
-
-// Re-exported so the web var-contract helper is reachable from this file (the
-// home of the web write path). Defined in `preset-vars.ts` next to the related
-// HSL parsing so native (which never imports this module) doesn't pull it in.
-export { toWebColorValue } from './preset-vars';
+import { getResolvedTokens } from './token-registry';
 
 export function applyDarkClass(resolved: 'light' | 'dark') {
   if (Platform.OS === 'web' && typeof document !== 'undefined') {
@@ -21,16 +16,12 @@ export function applyDarkClass(resolved: 'light' | 'dark') {
  * -------------------------------------------------------------------
  * The shadcn/Tailwind-v4 web apps compile their color utilities to reference the
  * BASE token directly (`.bg-background { background-color: var(--background) }`),
- * so on web the base `--x` tokens MUST be FULL CSS colors. We therefore write
- * them as `hsl(...)` (e.g. `--primary: hsl(185 100% 20%)`) — `var(--primary)`
- * then resolves to a valid color. The resolved `--color-*` vars are written
- * verbatim as `rgb(...)` (already full colors, used by native `color-mix` alpha
- * utilities; harmless on web). Non-color tokens (`--radius`, etc.) pass through
- * unchanged. See `toWebColorValue`.
+ * so on web the base `--x` tokens MUST be FULL CSS colors. `getResolvedTokens`
+ * returns every canonical token already resolved to an sRGB `rgb(...)` string,
+ * so `var(--x)` resolves to a valid color directly — no per-value wrapping. The
+ * same rgb values feed native (`color-mix` alpha utilities resolve on sRGB), so
+ * web and native share one canonical token pipeline.
  *
- * NATIVE writes the SAME tokens as RAW HSL triples (no `hsl()` wrapper) via
- * `rootVariables` (`native-root-vars.native.ts`), consumed through bloom's
- * native `global.css` `hsl(var(--x))` indirection — that path is untouched here.
  * Includes extended tokens (card, chart-*, content-area, sidebar-*) so consumer
  * apps don't need to synthesize them.
  */
@@ -38,10 +29,10 @@ export function applyColorPresetVars(preset: AppColorName, resolved: 'light' | '
   if (Platform.OS !== 'web' || typeof document === 'undefined') return;
   if (!APP_COLOR_PRESETS[preset]) return;
 
-  const vars = getPresetVars(preset, resolved, { includeResolvedColorVars: true });
+  const vars = getResolvedTokens(preset, resolved);
   const root = document.documentElement.style;
 
   for (const [key, value] of Object.entries(vars)) {
-    root.setProperty(key, toWebColorValue(key, value));
+    root.setProperty(key, value);
   }
 }

package/src/theme/build-theme.ts

@@ -1,6 +1,7 @@
 import { Platform } from 'react-native';
-import { APP_COLOR_PRESETS, type AppColorName, type PresetTokens } from './color-presets';
+import { APP_COLOR_PRESETS, type AppColorName } from './color-presets';
 import { getAdaptiveColors } from './adaptive-colors';
+import { getResolvedTokens, hslToSrgb } from './token-registry';
 import type { Theme, ThemeColors } from './types';
 
 /**
@@ -15,91 +16,87 @@ export const STATUS_COLORS = {
 } as const;
 
 /**
- * Convert a shadcn-style HSL CSS variable (`'H S% L%'` or `'H S% L% / A'`)
- * into a fully-resolved `hsl()` / `hsla()` color string consumable by both
- * web `style` and React Native.
+ * Extract the integer hue from a shadcn-style raw HSL triple (`'H S% L%'`,
+ * optionally with an alpha tail). Used to seed the computed brand tints below
+ * from the preset's primary/destructive hue, exactly as pre-0.8.0.
  */
-function hslVarToColor(hslVar: string): string {
-  const parts = hslVar.split('/').map((p) => p.trim());
-  const triple = parts[0] ?? '0 0% 0%';
-  const components = triple.replace(/\s+/g, ', ');
-
-  if (parts.length === 2) {
-    const alpha = parseFloat(parts[1] ?? '100') / 100;
-    return `hsla(${components}, ${alpha})`;
-  }
-  return `hsl(${components})`;
-}
-
-function extractHue(hslVar: string): number {
-  const first = hslVar.split(/\s+/)[0] ?? '0';
+function extractHue(triple: string): number {
+  const first = (triple.split(/\s+/)[0] ?? '0').replace(/deg$/i, '');
   const hue = parseInt(first, 10);
   return Number.isFinite(hue) ? hue : 0;
 }
 
-function hsl(h: number, s: number, l: number): string {
-  return `hsl(${h}, ${s}%, ${l}%)`;
-}
-
-function readToken(tokens: PresetTokens, key: string, fallback = '0 0% 0%'): string {
-  return hslVarToColor(tokens[key] ?? fallback);
-}
-
+/**
+ * Build the JS `theme.colors` object from the SAME canonical rgb token source
+ * the web/native CSS-var writes use (`getResolvedTokens`). JS styles and the
+ * `var(--x)` document tokens therefore share one rgb pipeline — no second,
+ * drift-prone HSL conversion lives here.
+ *
+ * Token-backed values read straight from the resolved rgb map via `g(...)`.
+ * The brand tints (primarySubtle/negative/contrast50/...) reproduce the EXACT
+ * pre-0.8.0 colors — computed from the preset's primary/destructive HUE with
+ * the historical `hsl(h, s%, l%)` math — but are emitted as `rgb(...)` by
+ * routing the triple through the registry's `hslToSrgb`, so the single-format
+ * pipeline is preserved. (`hsl(h,s%,l%)` and the `rgb(...)` of the same color
+ * are byte-identical under the RN/RNW/browser parser.)
+ */
 function buildColorsFromPreset(
   preset: AppColorName,
   resolved: 'light' | 'dark',
 ): ThemeColors {
-  const config = APP_COLOR_PRESETS[preset];
-  const tokens = resolved === 'dark' ? config.dark : config.light;
+  const t = getResolvedTokens(preset, resolved);
   const isDark = resolved === 'dark';
 
-  const primaryHue = extractHue(tokens['--primary'] ?? '0 0% 50%');
-  const destructiveHue = extractHue(tokens['--destructive'] ?? '0 0% 0%');
+  // Read a resolved `rgb(...)` token by its bare name (no leading `--`).
+  const g = (k: string): string => t[`--${k}`] ?? 'rgb(0 0 0)';
+
+  // Convert a computed `H S% L%` triple to the canonical `rgb(...)` via the
+  // registry's single HSL→sRGB conversion (matches the old `hsl(h,s%,l%)`).
+  const hslRgb = (h: number, s: number, l: number): string => hslToSrgb(`${h} ${s}% ${l}%`);
 
-  const background = readToken(tokens, '--background');
-  const surface = readToken(tokens, '--surface');
-  const mutedForeground = readToken(tokens, '--muted-foreground', '0 0% 50%');
-  const primaryColor = readToken(tokens, '--primary', '0 0% 50%');
-  const primaryForeground = readToken(tokens, '--primary-foreground', '0 0% 100%');
+  // Brand hues seed the computed tints from the preset's raw HSL triples,
+  // exactly as the pre-0.8.0 logic did.
+  const presetTokens = isDark ? APP_COLOR_PRESETS[preset].dark : APP_COLOR_PRESETS[preset].light;
+  const pHue = extractHue(presetTokens['--primary'] ?? '0 0% 50%');
+  const dHue = extractHue(presetTokens['--destructive'] ?? '0 0% 0%');
 
   return {
-    background,
-    backgroundSecondary: surface,
-    backgroundTertiary: readToken(tokens, '--muted'),
+    background: g('background'),
+    backgroundSecondary: g('surface'),
+    backgroundTertiary: g('muted'),
 
-    text: readToken(tokens, '--foreground', '0 0% 100%'),
-    textSecondary: mutedForeground,
-    textTertiary: mutedForeground,
+    text: g('foreground'),
+    textSecondary: g('muted-foreground'),
+    textTertiary: g('muted-foreground'),
 
-    border: readToken(tokens, '--border', '0 0% 20%'),
-    borderLight: readToken(tokens, '--input', '0 0% 20%'),
+    border: g('border'),
+    borderLight: g('input'),
 
-    primary: primaryColor,
-    primaryForeground,
-    // Legacy aliases retained for backwards compatibility with downstream
-    // consumers. `primaryLight` should be a brand tint, not the surface, but
-    // changing this is a breaking change handled in a separate major.
-    primaryLight: surface,
-    primaryDark: background,
+    primary: g('primary'),
+    primaryForeground: g('primary-foreground'),
+    // Legacy aliases (see types.ts): `primaryLight` is the page surface tint,
+    // `primaryDark` is the page background — retained for downstream consumers.
+    primaryLight: g('surface'),
+    primaryDark: g('background'),
 
-    // `secondary` historically mirrored `primary`. Retained for compatibility.
-    secondary: primaryColor,
+    // `secondary` historically mirrors `primary`. Retained for compatibility.
+    secondary: g('primary'),
 
-    tint: primaryColor,
-    icon: mutedForeground,
-    iconActive: primaryColor,
+    tint: g('primary'),
+    icon: g('muted-foreground'),
+    iconActive: g('primary'),
 
     ...STATUS_COLORS,
 
-    primarySubtle: isDark ? hsl(primaryHue, 50, 10) : hsl(primaryHue, 70, 93),
-    primarySubtleForeground: isDark ? hsl(primaryHue, 70, 65) : hsl(primaryHue, 90, 25),
-    negative: hsl(destructiveHue, 84, 45),
+    primarySubtle: isDark ? hslRgb(pHue, 50, 10) : hslRgb(pHue, 70, 93),
+    primarySubtleForeground: isDark ? hslRgb(pHue, 70, 65) : hslRgb(pHue, 90, 25),
+    negative: hslRgb(dHue, 84, 45),
     negativeForeground: '#FFFFFF',
-    negativeSubtle: isDark ? hsl(destructiveHue, 50, 10) : hsl(destructiveHue, 90, 95),
-    negativeSubtleForeground: isDark ? hsl(destructiveHue, 70, 65) : hsl(destructiveHue, 80, 40),
-    contrast50: isDark ? hsl(primaryHue, 15, 12) : hsl(primaryHue, 10, 93),
+    negativeSubtle: isDark ? hslRgb(dHue, 50, 10) : hslRgb(dHue, 90, 95),
+    negativeSubtleForeground: isDark ? hslRgb(dHue, 70, 65) : hslRgb(dHue, 80, 40),
+    contrast50: isDark ? hslRgb(pHue, 15, 12) : hslRgb(pHue, 10, 93),
 
-    card: surface,
+    card: g('surface'),
     shadow: isDark ? 'rgba(0, 0, 0, 0.3)' : 'rgba(0, 0, 0, 0.1)',
     overlay: 'rgba(0, 0, 0, 0.5)',
   };

package/src/theme/color-presets.ts

@@ -6,17 +6,17 @@ export type AppColorName = 'teal' | 'blue' | 'green' | 'amber' | 'yellow' | 'red
  * Keys carry a leading `--` for historical reasons (shadcn-style CSS variable
  * names) — keep in mind the values are platform-agnostic **raw HSL triples**
  * (e.g. `'185 100% 20%'` or `'185 100% 20% / 0.5'`), not CSS-resolved colors.
- * The same map drives both:
- *   - the web layer: the base `--x` tokens are wrapped to full `hsl(...)` colors
- *     (via `toWebColorValue`) before being written to `document.documentElement`
- *     / a `BloomColorScope` element, so `var(--x)` — the form Tailwind v4
- *     `@theme inline` compiles its color utilities to — resolves to a valid
- *     color directly; the resolved `--color-*` companions are written as
- *     `rgb(...)`, and
+ * The single canonical resolver `getResolvedTokens` (in `token-registry.ts`)
+ * converts this raw map to sRGB `rgb(...)` for every runtime write — the same
+ * values drive BOTH layers:
+ *   - the web layer: `getResolvedTokens`'s `rgb(...)` strings are written to
+ *     `document.documentElement` / a `BloomColorScope` element, so `var(--x)` —
+ *     the form Tailwind v4 `@theme inline` compiles its color utilities to —
+ *     resolves to a valid color directly, and
  *   - the native layer (`buildTheme` resolves the raw triples into `hsl(...)`
  *     strings consumable by React Native styles; `native-root-vars.native.ts`
- *     writes the raw triples through bloom's `hsl(var(--x))` `global.css`
- *     indirection).
+ *     writes the same canonical `rgb(...)` values into react-native-css's
+ *     `rootVariables` family).
  *
  * The `--` prefix is an implementation detail we will drop in a future major.
  */

package/src/theme/color-scope/index.web.tsx

@@ -3,27 +3,20 @@ import React, { Children, cloneElement, isValidElement, useContext, useMemo } fr
 import { BloomThemeContext, type BloomThemeContextValue } from '../BloomThemeProvider';
 import { buildTheme } from '../build-theme';
 import type { AppColorName } from '../color-presets';
-import { toWebColorValue } from '../preset-vars';
-import { buildScopeVars } from './style-builder';
+import { getResolvedTokens } from '../token-registry';
 
 /**
- * `buildScopeVars` returns the preset's tokens as platform-agnostic raw HSL
- * triples (shared with the native write path). On web they are scoped onto an
- * element's inline `style`, where Tailwind v4's compiled utilities read them as
- * `var(--x)` directly — so the base tokens MUST be full CSS colors. Wrap each
- * raw triple in `hsl(...)` via `toWebColorValue`; `--color-*` rgb vars and
- * non-color tokens pass through. See `toWebColorValue` in `../preset-vars`.
+ * `getResolvedTokens` returns every canonical token already resolved to an sRGB
+ * `rgb(...)` string — the SAME pipeline the document-root web writer and the
+ * native writer use. Scoped onto an element's inline `style`, Tailwind v4's
+ * compiled utilities read these as `var(--x)` directly, so each base token is a
+ * full CSS color with no per-value wrapping needed.
  */
 function buildWebScopeVars(
   colorPreset: AppColorName,
   mode: 'light' | 'dark',
 ): React.CSSProperties {
-  const raw = buildScopeVars(colorPreset, mode);
-  const out: Record<string, string> = {};
-  for (const [key, value] of Object.entries(raw)) {
-    out[key] = toWebColorValue(key, value);
-  }
-  return out as React.CSSProperties;
+  return getResolvedTokens(colorPreset, mode) as React.CSSProperties;
 }
 
 export interface BloomColorScopeProps {

package/src/theme/color-scope/style-builder.ts

@@ -1,7 +1,7 @@
 import type React from 'react';
 import { Platform, type StyleProp, type ViewStyle } from 'react-native';
 
-import { getPresetVars } from '../preset-vars';
+import { getResolvedTokens } from '../token-registry';
 import type { AppColorName } from '../color-presets';
 import { lazyRequire } from '../../utils/lazy-require';
 
@@ -25,14 +25,17 @@ const getNativeWindVars = lazyRequire<NativeWindVarsModule>('nativewind');
 
 /**
  * Build the CSS custom-property map for a preset, ready to be applied to a
- * subtree. Always includes the resolved `--color-*` vars so Tailwind v4
- * `@theme` utilities (e.g. `bg-background`) honour the scope.
+ * subtree. Every token is resolved to an sRGB `rgb(...)` string via
+ * `getResolvedTokens` — the single canonical token pipeline shared by web and
+ * native — so Tailwind v4 `@theme` utilities (e.g. `bg-background`) and
+ * `color-mix`-based alpha utilities (`bg-primary/10`) both resolve against the
+ * same color values. Keys retain the leading `--`.
  */
 export function buildScopeVars(
   colorPreset: AppColorName,
   mode: 'light' | 'dark',
 ): Record<string, string> {
-  return getPresetVars(colorPreset, mode, { includeResolvedColorVars: true });
+  return getResolvedTokens(colorPreset, mode);
 }
 
 /**

package/src/theme/color-space.ts

@@ -0,0 +1,56 @@
+export interface Oklch { l: number; c: number; h: number } // l 0..1, c 0..~0.4, h deg
+export interface Rgb { r: number; g: number; b: number }   // 0..255 integers
+
+const clamp = (n: number, lo: number, hi: number) => Math.min(hi, Math.max(lo, n));
+const srgbGamma = (x: number) =>
+  x <= 0.0031308 ? 12.92 * x : 1.055 * Math.pow(x, 1 / 2.4) - 0.055;
+
+/** OKLCH → linear OKLab → linear sRGB → gamma sRGB → 0..255. Pure. */
+export function oklchToSrgb({ l, c, h }: Oklch): Rgb {
+  const hr = (h * Math.PI) / 180;
+  const a = c * Math.cos(hr);
+  const b2 = c * Math.sin(hr);
+  const l_ = l + 0.3963377774 * a + 0.2158037573 * b2;
+  const m_ = l - 0.1055613458 * a - 0.0638541728 * b2;
+  const s_ = l - 0.0894841775 * a - 1.291485548 * b2;
+  const lc = l_ ** 3, mc = m_ ** 3, sc = s_ ** 3;
+  const lr = +4.0767416621 * lc - 3.3077115913 * mc + 0.2309699292 * sc;
+  const lg = -1.2684380046 * lc + 2.6097574011 * mc - 0.3413193965 * sc;
+  const lb = -0.0041960863 * lc - 0.7034186147 * mc + 1.707614701 * sc;
+  return {
+    r: Math.round(clamp(srgbGamma(lr), 0, 1) * 255),
+    g: Math.round(clamp(srgbGamma(lg), 0, 1) * 255),
+    b: Math.round(clamp(srgbGamma(lb), 0, 1) * 255),
+  };
+}
+
+export function srgbToRgbString({ r, g, b }: Rgb, alpha?: number): string {
+  return alpha === undefined || alpha >= 1
+    ? `rgb(${r} ${g} ${b})`
+    : `rgb(${r} ${g} ${b} / ${alpha})`;
+}
+
+/**
+ * Parse an `rgb(...)` / `rgba(...)` string into an {@link Rgb}.
+ *
+ * Contract: input MUST be an `rgb(...)` / `rgba(...)` string (e.g. a resolved
+ * token from `getResolvedTokens`). Both modern (`rgb(r g b)`) and legacy
+ * (`rgb(r, g, b)`) syntaxes are accepted. Anything else throws — this is a
+ * canonical-pipeline primitive and a non-rgb input signals a real bug at the
+ * call site, never a value to silently coerce to black.
+ *
+ * @throws {Error} if `s` is not an `rgb()` / `rgba()` string.
+ */
+export function parseRgbString(s: string): Rgb {
+  const inner = s.match(/rgba?\(([^)]+)\)/i)?.[1];
+  if (inner === undefined) {
+    throw new Error(`parseRgbString: expected an rgb() string, got: ${s}`);
+  }
+  const [r, g, b] = inner.split(/[ ,/]+/).map((n) => parseInt(n, 10));
+  return { r: r ?? 0, g: g ?? 0, b: b ?? 0 };
+}
+
+/** Cheap perceptual-ish distance in sRGB (sufficient for a ≤1 rounding gate). */
+export function deltaE(a: Rgb, b: Rgb): number {
+  return Math.sqrt((a.r - b.r) ** 2 + (a.g - b.g) ** 2 + (a.b - b.b) ** 2) / Math.sqrt(3);
+}