@oxyhq/bloom 0.41.0 → 0.42.0

package/src/theme/color-engine/scheme-variants.ts

@@ -15,6 +15,29 @@ import { Variant } from './variant';
 
 export type SchemeVariant = 'vivid' | 'vibrant' | 'expressive' | 'tonalSpot' | 'neutral';
 
+/**
+ * Optional explicit accent seeds for a scheme. When a source HCT is supplied, its
+ * palette is built from that colour itself (keeping the brand hue + chroma) instead
+ * of the derived hue-rotation — so a brand with a distinct secondary/tertiary accent
+ * (e.g. blue primary + yellow secondary) can PIN its real accent family. The M3 role
+ * tones still apply on top (a pinned yellow yields a yellow-hued secondary family:
+ * light container, dark on-colour) — that is correct M3 behaviour.
+ */
+export interface AccentSources {
+  secondarySource?: Hct;
+  tertiarySource?: Hct;
+}
+
+/**
+ * Build the accent tonal palette for a role: from the pinned brand colour when a
+ * `source` is provided (preserving its hue + chroma), otherwise from the caller's
+ * derived rotation. Uses `TonalPalette.fromInt` so the palette keeps the exact
+ * brand key colour; the role tones apply the same way for both.
+ */
+function accentPalette(source: Hct | undefined, derived: () => TonalPalette): TonalPalette {
+  return source !== undefined ? TonalPalette.fromInt(source.toInt()) : derived();
+}
+
 const VIBRANT_HUES = [0.0, 41.0, 61.0, 101.0, 131.0, 181.0, 251.0, 301.0, 360.0];
 const VIBRANT_SECONDARY_ROTATIONS = [18.0, 15.0, 10.0, 12.0, 15.0, 18.0, 15.0, 12.0, 12.0];
 const VIBRANT_TERTIARY_ROTATIONS = [35.0, 30.0, 20.0, 25.0, 30.0, 35.0, 30.0, 25.0, 25.0];
@@ -24,20 +47,29 @@ const EXPRESSIVE_SECONDARY_ROTATIONS = [45.0, 95.0, 45.0, 20.0, 45.0, 90.0, 45.0
 const EXPRESSIVE_TERTIARY_ROTATIONS = [120.0, 120.0, 20.0, 45.0, 20.0, 15.0, 20.0, 120.0, 120.0];
 
 /** Maxed-out colourfulness at each position of the primary palette. */
-export function schemeVibrant(source: Hct, isDark: boolean, contrastLevel: number): DynamicScheme {
+export function schemeVibrant(
+  source: Hct,
+  isDark: boolean,
+  contrastLevel: number,
+  accents: AccentSources = {},
+): DynamicScheme {
   return new DynamicScheme({
     sourceColorArgb: source.toInt(),
     variant: Variant.VIBRANT,
     contrastLevel,
     isDark,
     primaryPalette: TonalPalette.fromHueAndChroma(source.hue, 200.0),
-    secondaryPalette: TonalPalette.fromHueAndChroma(
-      DynamicScheme.getRotatedHue(source, VIBRANT_HUES, VIBRANT_SECONDARY_ROTATIONS),
-      24.0,
+    secondaryPalette: accentPalette(accents.secondarySource, () =>
+      TonalPalette.fromHueAndChroma(
+        DynamicScheme.getRotatedHue(source, VIBRANT_HUES, VIBRANT_SECONDARY_ROTATIONS),
+        24.0,
+      ),
     ),
-    tertiaryPalette: TonalPalette.fromHueAndChroma(
-      DynamicScheme.getRotatedHue(source, VIBRANT_HUES, VIBRANT_TERTIARY_ROTATIONS),
-      32.0,
+    tertiaryPalette: accentPalette(accents.tertiarySource, () =>
+      TonalPalette.fromHueAndChroma(
+        DynamicScheme.getRotatedHue(source, VIBRANT_HUES, VIBRANT_TERTIARY_ROTATIONS),
+        32.0,
+      ),
     ),
     neutralPalette: TonalPalette.fromHueAndChroma(source.hue, 10.0),
     neutralVariantPalette: TonalPalette.fromHueAndChroma(source.hue, 12.0),
@@ -53,40 +85,58 @@ export function schemeVibrant(source: Hct, isDark: boolean, contrastLevel: numbe
  * old hand-authored palette felt more vivid than pure M3, and this restores that
  * across the whole primary/secondary/tertiary trio.
  */
-export function schemeVivid(source: Hct, isDark: boolean, contrastLevel: number): DynamicScheme {
+export function schemeVivid(
+  source: Hct,
+  isDark: boolean,
+  contrastLevel: number,
+  accents: AccentSources = {},
+): DynamicScheme {
   return new DynamicScheme({
     sourceColorArgb: source.toInt(),
     variant: Variant.VIBRANT,
     contrastLevel,
     isDark,
     primaryPalette: TonalPalette.fromHueAndChroma(source.hue, 200.0),
-    secondaryPalette: TonalPalette.fromHueAndChroma(
-      DynamicScheme.getRotatedHue(source, VIBRANT_HUES, VIBRANT_SECONDARY_ROTATIONS),
-      64.0,
+    secondaryPalette: accentPalette(accents.secondarySource, () =>
+      TonalPalette.fromHueAndChroma(
+        DynamicScheme.getRotatedHue(source, VIBRANT_HUES, VIBRANT_SECONDARY_ROTATIONS),
+        64.0,
+      ),
     ),
-    tertiaryPalette: TonalPalette.fromHueAndChroma(
-      DynamicScheme.getRotatedHue(source, VIBRANT_HUES, VIBRANT_TERTIARY_ROTATIONS),
-      72.0,
+    tertiaryPalette: accentPalette(accents.tertiarySource, () =>
+      TonalPalette.fromHueAndChroma(
+        DynamicScheme.getRotatedHue(source, VIBRANT_HUES, VIBRANT_TERTIARY_ROTATIONS),
+        72.0,
+      ),
     ),
     neutralPalette: TonalPalette.fromHueAndChroma(source.hue, 10.0),
     neutralVariantPalette: TonalPalette.fromHueAndChroma(source.hue, 12.0),
   });
 }
 
-export function schemeExpressive(source: Hct, isDark: boolean, contrastLevel: number): DynamicScheme {
+export function schemeExpressive(
+  source: Hct,
+  isDark: boolean,
+  contrastLevel: number,
+  accents: AccentSources = {},
+): DynamicScheme {
   return new DynamicScheme({
     sourceColorArgb: source.toInt(),
     variant: Variant.EXPRESSIVE,
     contrastLevel,
     isDark,
     primaryPalette: TonalPalette.fromHueAndChroma(sanitizeDegreesDouble(source.hue + 240.0), 40.0),
-    secondaryPalette: TonalPalette.fromHueAndChroma(
-      DynamicScheme.getRotatedHue(source, EXPRESSIVE_HUES, EXPRESSIVE_SECONDARY_ROTATIONS),
-      24.0,
+    secondaryPalette: accentPalette(accents.secondarySource, () =>
+      TonalPalette.fromHueAndChroma(
+        DynamicScheme.getRotatedHue(source, EXPRESSIVE_HUES, EXPRESSIVE_SECONDARY_ROTATIONS),
+        24.0,
+      ),
     ),
-    tertiaryPalette: TonalPalette.fromHueAndChroma(
-      DynamicScheme.getRotatedHue(source, EXPRESSIVE_HUES, EXPRESSIVE_TERTIARY_ROTATIONS),
-      32.0,
+    tertiaryPalette: accentPalette(accents.tertiarySource, () =>
+      TonalPalette.fromHueAndChroma(
+        DynamicScheme.getRotatedHue(source, EXPRESSIVE_HUES, EXPRESSIVE_TERTIARY_ROTATIONS),
+        32.0,
+      ),
     ),
     neutralPalette: TonalPalette.fromHueAndChroma(source.hue + 15, 8.0),
     neutralVariantPalette: TonalPalette.fromHueAndChroma(source.hue + 15, 12.0),
@@ -94,36 +144,57 @@ export function schemeExpressive(source: Hct, isDark: boolean, contrastLevel: nu
 }
 
 /** The Material You default — a calm, balanced treatment of the seed. */
-export function schemeTonalSpot(source: Hct, isDark: boolean, contrastLevel: number): DynamicScheme {
+export function schemeTonalSpot(
+  source: Hct,
+  isDark: boolean,
+  contrastLevel: number,
+  accents: AccentSources = {},
+): DynamicScheme {
   return new DynamicScheme({
     sourceColorArgb: source.toInt(),
     variant: Variant.TONAL_SPOT,
     contrastLevel,
     isDark,
     primaryPalette: TonalPalette.fromHueAndChroma(source.hue, 36.0),
-    secondaryPalette: TonalPalette.fromHueAndChroma(source.hue, 16.0),
-    tertiaryPalette: TonalPalette.fromHueAndChroma(sanitizeDegreesDouble(source.hue + 60.0), 24.0),
+    secondaryPalette: accentPalette(accents.secondarySource, () =>
+      TonalPalette.fromHueAndChroma(source.hue, 16.0),
+    ),
+    tertiaryPalette: accentPalette(accents.tertiarySource, () =>
+      TonalPalette.fromHueAndChroma(sanitizeDegreesDouble(source.hue + 60.0), 24.0),
+    ),
     neutralPalette: TonalPalette.fromHueAndChroma(source.hue, 6.0),
     neutralVariantPalette: TonalPalette.fromHueAndChroma(source.hue, 8.0),
   });
 }
 
 /** Near-greyscale — the seed hue is present only as a whisper. */
-export function schemeNeutral(source: Hct, isDark: boolean, contrastLevel: number): DynamicScheme {
+export function schemeNeutral(
+  source: Hct,
+  isDark: boolean,
+  contrastLevel: number,
+  accents: AccentSources = {},
+): DynamicScheme {
   return new DynamicScheme({
     sourceColorArgb: source.toInt(),
     variant: Variant.NEUTRAL,
     contrastLevel,
     isDark,
     primaryPalette: TonalPalette.fromHueAndChroma(source.hue, 12.0),
-    secondaryPalette: TonalPalette.fromHueAndChroma(source.hue, 8.0),
-    tertiaryPalette: TonalPalette.fromHueAndChroma(source.hue, 16.0),
+    secondaryPalette: accentPalette(accents.secondarySource, () =>
+      TonalPalette.fromHueAndChroma(source.hue, 8.0),
+    ),
+    tertiaryPalette: accentPalette(accents.tertiarySource, () =>
+      TonalPalette.fromHueAndChroma(source.hue, 16.0),
+    ),
     neutralPalette: TonalPalette.fromHueAndChroma(source.hue, 2.0),
     neutralVariantPalette: TonalPalette.fromHueAndChroma(source.hue, 2.0),
   });
 }
 
-const BUILDERS: Record<SchemeVariant, (s: Hct, d: boolean, c: number) => DynamicScheme> = {
+const BUILDERS: Record<
+  SchemeVariant,
+  (s: Hct, d: boolean, c: number, accents: AccentSources) => DynamicScheme
+> = {
   vivid: schemeVivid,
   vibrant: schemeVibrant,
   expressive: schemeExpressive,
@@ -131,12 +202,19 @@ const BUILDERS: Record<SchemeVariant, (s: Hct, d: boolean, c: number) => Dynamic
   neutral: schemeNeutral,
 };
 
-/** Build a scheme by variant name. */
+/**
+ * Build a scheme by variant name.
+ *
+ * `accents` optionally pins the secondary and/or tertiary palette to an explicit
+ * brand colour (see {@link AccentSources}); omitted accents keep the variant's
+ * derived hue-rotation, so existing callers get byte-identical output.
+ */
 export function buildScheme(
   variant: SchemeVariant,
   source: Hct,
   isDark: boolean,
   contrastLevel = 0,
+  accents: AccentSources = {},
 ): DynamicScheme {
-  return BUILDERS[variant](source, isDark, contrastLevel);
+  return BUILDERS[variant](source, isDark, contrastLevel, accents);
 }

package/src/theme/color-engine/seed-from-image.ts

@@ -51,7 +51,17 @@ export function quantizeImage(pixels: number[], maxColors = 128): Map<number, nu
   return result;
 }
 
-/** Ranked seed candidates (best first) extracted from an image's pixels (ARGB). */
+/**
+ * Ranked seed candidates (best first) extracted from an image's pixels (ARGB).
+ *
+ * The top result (`seeds[0]`) is the primary seed for `generateRoleColors({ seed })`.
+ * To derive a richer, brand-accurate theme from artwork, a caller can additionally
+ * pin distinct accents from the ranked list: pass `hexFromArgb(seeds[1])` as
+ * `secondarySeed` and `hexFromArgb(seeds[2])` as `tertiarySeed` to
+ * `generateRoleColors` / `buildSeedScopeVars` / `buildThemeFromSeed` so the
+ * secondary and tertiary families reflect the artwork's real supporting colours
+ * instead of hue-rotations of the primary.
+ */
 export function seedsFromImagePixels(pixels: number[], options?: ScoreOptions): number[] {
   return score(quantizeImage(pixels), options);
 }

package/src/theme/color-presets.ts

@@ -32,6 +32,20 @@ export interface AppColorPreset {
   hex: string;
   /** The tonal scheme variant the engine derives roles with. */
   variant: SchemeVariant;
+  /**
+   * Optional explicit secondary-accent seed, `#rrggbb`. When set, the secondary
+   * palette is PINNED to this brand colour (hue + chroma preserved; M3 role tones
+   * still apply) instead of the derived hue-rotation of {@link AppColorPreset.hex}.
+   * Bloom's built-in presets do NOT set this, so their generated output is
+   * unchanged; a consumer brand with a distinct accent (blue primary + yellow
+   * secondary) sets it to pin its real accent family.
+   */
+  secondaryHex?: string;
+  /**
+   * Optional explicit tertiary-accent seed, `#rrggbb`. Same semantics as
+   * {@link AppColorPreset.secondaryHex} for the tertiary palette.
+   */
+  tertiaryHex?: string;
 }
 
 /**

package/src/theme/color-scope/seed-scope.ts

@@ -72,6 +72,18 @@ export interface SeedScopeOptions {
   variant?: SchemeVariant;
   /** −1 (low) … 0 (normal) … 1 (high). Defaults to 0. */
   contrastLevel?: number;
+  /**
+   * Optional explicit secondary-accent seed, `#rrggbb`. Pins the secondary palette
+   * to this brand colour instead of the derived rotation (M3 role tones still
+   * apply). Handy for an artwork-extracted theme: pass the second-ranked seed from
+   * `seedsFromImagePixels` (`seeds[1]`) as a distinct secondary accent.
+   */
+  secondarySeed?: string;
+  /**
+   * Optional explicit tertiary-accent seed, `#rrggbb`. Same semantics; pass
+   * `seedsFromImagePixels`' `seeds[2]` for a third artwork-derived accent.
+   */
+  tertiarySeed?: string;
 }
 
 /**
@@ -92,6 +104,8 @@ export function buildSeedScopeVars(options: SeedScopeOptions): Record<string, st
     variant: options.variant ?? 'vivid',
     isDark: options.mode === 'dark',
     contrastLevel: options.contrastLevel ?? 0,
+    secondarySeed: options.secondarySeed,
+    tertiarySeed: options.tertiarySeed,
   });
   const tokens = roleColorsToPresetTokens(roles);
   const vars: Record<string, string> = { ...tokens };

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

@@ -3,6 +3,7 @@ import { Platform, type StyleProp, type ViewStyle } from 'react-native';
 
 import { CANONICAL_TOKENS, getResolvedTokens } from '../token-registry';
 import type { AppColorName } from '../color-presets';
+import type { ExplicitAccents } from '../preset-vars';
 import { lazyRequire } from '../../utils/lazy-require';
 
 /**
@@ -36,8 +37,9 @@ const getNativeWindVars = lazyRequire<NativeWindVarsModule>('nativewind');
 export function buildScopeVars(
   colorPreset: AppColorName,
   mode: 'light' | 'dark',
+  accents?: ExplicitAccents,
 ): Record<string, string> {
-  const tokens = getResolvedTokens(colorPreset, mode);
+  const tokens = getResolvedTokens(colorPreset, mode, accents);
   const vars: Record<string, string> = { ...tokens };
 
   for (const token of CANONICAL_TOKENS) {

package/src/theme/index.ts

@@ -24,9 +24,10 @@ export {
   greenFromArgb,
   blueFromArgb,
 } from './color-engine';
-export type { RoleColors, GenerateOptions, RoleName, SchemeVariant } from './color-engine';
+export type { RoleColors, GenerateOptions, RoleName, SchemeVariant, AccentSources } from './color-engine';
 export { buildTheme, STATUS_COLORS } from './build-theme';
 export { buildThemeFromSeed, buildColorsFromSeed } from './build-theme-from-seed';
+export type { SeedAccents } from './build-theme-from-seed';
 export { THEME_GRADIENTS } from './gradients';
 export { useTheme, useThemeColor, useBloomTheme } from './use-theme';
 export { useNavigationTheme } from './use-navigation-theme';
@@ -43,6 +44,7 @@ export {
 export { parseRgb, withAlpha } from './color-utils';
 export type { RgbChannels } from './color-utils';
 export { getPresetVars, applyPresetVarsToDocument } from './preset-vars';
+export type { ExplicitAccents } from './preset-vars';
 export { applyDarkClass } from './apply-dark-class';
 export { setColorSchemeSafe } from './set-color-scheme-safe';
 export { initCssInteropDarkMode } from './init-css-interop';

package/src/theme/native-root-vars.native.ts

@@ -17,6 +17,7 @@
 import { rootVariables } from 'react-native-css/native-internal';
 
 import { type AppColorName } from './color-presets';
+import type { ExplicitAccents } from './preset-vars';
 import { getResolvedTokens } from './token-registry';
 
 /**
@@ -121,10 +122,14 @@ import { getResolvedTokens } from './token-registry';
  * Defensive guard: if a host ships a react-native-css build that doesn't expose
  * `rootVariables` as a callable (it always does on @3), we bail rather than throw.
  */
-export function applyNativeRootVars(colorPreset: AppColorName, mode: 'light' | 'dark'): void {
+export function applyNativeRootVars(
+  colorPreset: AppColorName,
+  mode: 'light' | 'dark',
+  accents?: ExplicitAccents,
+): void {
   if (typeof rootVariables !== 'function') return;
 
-  const vars = getResolvedTokens(colorPreset, mode);
+  const vars = getResolvedTokens(colorPreset, mode, accents);
   for (const [key, value] of Object.entries(vars)) {
     // The family is keyed by the bare name; `getResolvedTokens` keys include `--`.
     const name = key.startsWith('--') ? key.slice(2) : key;

package/src/theme/native-root-vars.ts

@@ -1,4 +1,5 @@
 import { type AppColorName } from './color-presets';
+import type { ExplicitAccents } from './preset-vars';
 
 /**
  * Platform-neutral DEFAULT variant of `applyNativeRootVars` — a no-op.
@@ -30,7 +31,11 @@ import { type AppColorName } from './color-presets';
  * The signature is intentionally identical to those variants so the import site in
  * `BloomThemeProvider` is platform-agnostic.
  */
-export function applyNativeRootVars(_colorPreset: AppColorName, _mode: 'light' | 'dark'): void {
+export function applyNativeRootVars(
+  _colorPreset: AppColorName,
+  _mode: 'light' | 'dark',
+  _accents?: ExplicitAccents,
+): void {
   // Intentionally empty — the native variant (`native-root-vars.native.ts`) does
   // the real work; this neutral default and the web fork are inert.
 }

package/src/theme/native-root-vars.web.ts

@@ -1,4 +1,5 @@
 import { type AppColorName } from './color-presets';
+import type { ExplicitAccents } from './preset-vars';
 
 /**
  * Web fork of `applyNativeRootVars` — a no-op.
@@ -17,6 +18,10 @@ import { type AppColorName } from './color-presets';
  * The signature is intentionally identical to the plain variant so the import
  * site in `BloomThemeProvider` is platform-agnostic.
  */
-export function applyNativeRootVars(_colorPreset: AppColorName, _mode: 'light' | 'dark'): void {
+export function applyNativeRootVars(
+  _colorPreset: AppColorName,
+  _mode: 'light' | 'dark',
+  _accents?: ExplicitAccents,
+): void {
   // Intentionally empty — web applies preset vars to `document.documentElement`.
 }

package/src/theme/preset-vars.ts

@@ -1,5 +1,17 @@
 import { APP_COLOR_PRESETS, type AppColorName, type PresetTokens } from './color-presets';
 import { generateRoleColors, type RoleColors } from './color-engine';
+
+/**
+ * Optional explicit accent-colour overrides (`#rrggbb`) that PIN the secondary
+ * and/or tertiary palette app-wide, regardless of the active preset's own seed.
+ * Threaded from `BloomThemeProvider`'s `secondaryColor` / `tertiaryColor` props
+ * down through the whole token pipeline. When both are omitted, the preset's own
+ * (usually derived) accents are used — output is unchanged.
+ */
+export interface ExplicitAccents {
+  secondaryHex?: string;
+  tertiaryHex?: string;
+}
 // Circular at the module graph level (`token-registry` imports `getPresetVars`
 // from here), but safe: `getResolvedTokens` is only referenced inside the
 // `applyPresetVarsToDocument` function body — i.e. at call time, after both
@@ -26,12 +38,19 @@ import { getResolvedTokens } from './token-registry';
 export function getPresetVars(
   colorName: AppColorName,
   mode: 'light' | 'dark',
+  accents?: ExplicitAccents,
 ): PresetTokens {
   const preset = APP_COLOR_PRESETS[colorName];
   const r: RoleColors = generateRoleColors({
     seed: preset.hex,
     variant: preset.variant,
     isDark: mode === 'dark',
+    // Pinned accents: an explicit app-wide override (from the provider) wins,
+    // else the preset's own declared accent, else undefined → derived rotation.
+    // The built-in presets declare none, so with no override their generated
+    // tokens stay byte-identical.
+    secondarySeed: accents?.secondaryHex ?? preset.secondaryHex,
+    tertiarySeed: accents?.tertiaryHex ?? preset.tertiaryHex,
   });
 
   return {

package/src/theme/token-registry.ts

@@ -1,5 +1,5 @@
 import { APP_COLOR_NAMES, type AppColorName } from './color-presets';
-import { getPresetVars } from './preset-vars';
+import { getPresetVars, type ExplicitAccents } from './preset-vars';
 
 /**
  * The canonical set of Bloom theme token names — WITHOUT the leading `--`.
@@ -149,8 +149,9 @@ export function hslToSrgb(triple: string): string {
 export function getResolvedTokens(
   preset: AppColorName,
   mode: 'light' | 'dark',
+  accents?: ExplicitAccents,
 ): Record<string, string> {
-  const raw = getPresetVars(preset, mode);
+  const raw = getPresetVars(preset, mode, accents);
   const resolved: Record<string, string> = {};
   for (const [key, value] of Object.entries(raw)) {
     resolved[key] = RAW_HSL_TRIPLE.test(value) ? hslToSrgb(value) : value;