@oxyhq/bloom 0.40.0 → 0.42.0

package/src/theme/color-engine/index.ts

@@ -11,7 +11,7 @@ export { Hct } from './hct';
 export { TonalPalette } from './tonal-palette';
 export { DynamicScheme } from './dynamic-scheme';
 export { buildScheme, schemeVibrant, schemeExpressive, schemeTonalSpot, schemeNeutral } from './scheme-variants';
-export type { SchemeVariant } from './scheme-variants';
+export type { SchemeVariant, AccentSources } from './scheme-variants';
 export { Roles } from './color-roles';
 export type { RoleName } from './color-roles';
 export { ColorRole } from './color-role';
@@ -51,11 +51,27 @@ export interface GenerateOptions {
   isDark?: boolean;
   /** −1 (low) … 0 (normal) … 1 (high). */
   contrastLevel?: number;
+  /**
+   * Optional explicit secondary-accent seed, `#rrggbb`. When set, the secondary
+   * palette is pinned to THIS colour's hue + chroma (M3 role tones still apply)
+   * instead of the variant's derived hue-rotation of the primary seed. Omit for
+   * the current derived behaviour.
+   */
+  secondarySeed?: string;
+  /**
+   * Optional explicit tertiary-accent seed, `#rrggbb`. Same semantics as
+   * {@link GenerateOptions.secondarySeed} for the tertiary palette.
+   */
+  tertiarySeed?: string;
 }
 
 /**
  * Generate the full role set from ANY seed colour — the dynamic-theming entry
  * point. Presets are just fixed seeds; a user-picked colour works identically.
+ *
+ * `secondarySeed` / `tertiarySeed` optionally PIN those accent families to real
+ * brand colours (e.g. a blue-primary brand with a yellow secondary); omitted, the
+ * accents are derived as the variant's hue-rotations — byte-identical to before.
  */
 export function generateRoleColors(opts: GenerateOptions): RoleColors {
   const scheme = buildScheme(
@@ -63,6 +79,16 @@ export function generateRoleColors(opts: GenerateOptions): RoleColors {
     Hct.fromInt(argbFromHex(opts.seed)),
     opts.isDark ?? false,
     opts.contrastLevel ?? 0,
+    {
+      secondarySource:
+        opts.secondarySeed !== undefined
+          ? Hct.fromInt(argbFromHex(opts.secondarySeed))
+          : undefined,
+      tertiarySource:
+        opts.tertiarySeed !== undefined
+          ? Hct.fromInt(argbFromHex(opts.tertiarySeed))
+          : undefined,
+    },
   );
   const out = {} as RoleColors;
   for (const name of Object.keys(Roles) as RoleName[]) {

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

@@ -13,7 +13,30 @@ import { sanitizeDegreesDouble } from './math-utils';
 import { TonalPalette } from './tonal-palette';
 import { Variant } from './variant';
 
-export type SchemeVariant = 'vibrant' | 'expressive' | 'tonalSpot' | 'neutral';
+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];
@@ -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),
@@ -45,20 +77,66 @@ export function schemeVibrant(source: Hct, isDark: boolean, contrastLevel: numbe
 }
 
 /** Playful, intentionally detached from the seed hue (primary rotated 240°). */
-export function schemeExpressive(source: Hct, isDark: boolean, contrastLevel: number): DynamicScheme {
+/**
+ * Bloom's own brand-vivid scheme. Same vibrant base (max-chroma primary) but the
+ * secondary and tertiary accents keep MUCH more chroma than canonical M3 (which
+ * intentionally desaturates supporting accents). Neutrals stay low-chroma so
+ * surfaces read as clean tinted light/dark. This is what the presets use — the
+ * 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,
+  accents: AccentSources = {},
+): DynamicScheme {
+  return new DynamicScheme({
+    sourceColorArgb: source.toInt(),
+    variant: Variant.VIBRANT,
+    contrastLevel,
+    isDark,
+    primaryPalette: TonalPalette.fromHueAndChroma(source.hue, 200.0),
+    secondaryPalette: accentPalette(accents.secondarySource, () =>
+      TonalPalette.fromHueAndChroma(
+        DynamicScheme.getRotatedHue(source, VIBRANT_HUES, VIBRANT_SECONDARY_ROTATIONS),
+        64.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,
+  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),
@@ -66,48 +144,77 @@ 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,
   tonalSpot: schemeTonalSpot,
   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;
 }
 
 /**
@@ -74,17 +88,17 @@ export function hexToAppColorName(hex: string): AppColorName {
  * bold `vibrant` derivation to match the prior saturated palette.
  */
 export const APP_COLOR_PRESETS: Record<AppColorName, AppColorPreset> = {
-  teal: { name: 'teal', hex: '#005c67', variant: 'vibrant' },
-  blue: { name: 'blue', hex: '#1d9bf0', variant: 'vibrant' },
-  green: { name: 'green', hex: '#10b981', variant: 'vibrant' },
-  amber: { name: 'amber', hex: '#f59e0b', variant: 'vibrant' },
-  yellow: { name: 'yellow', hex: '#ffc300', variant: 'vibrant' },
-  red: { name: 'red', hex: '#ef4444', variant: 'vibrant' },
-  purple: { name: 'purple', hex: '#8b5cf6', variant: 'vibrant' },
-  pink: { name: 'pink', hex: '#ec4899', variant: 'vibrant' },
-  sky: { name: 'sky', hex: '#0ea5e9', variant: 'vibrant' },
-  orange: { name: 'orange', hex: '#f97316', variant: 'vibrant' },
-  mint: { name: 'mint', hex: '#14b8a6', variant: 'vibrant' },
-  oxy: { name: 'oxy', hex: '#c46ede', variant: 'vibrant' },
-  faircoin: { name: 'faircoin', hex: '#9ffb50', variant: 'vibrant' },
+  teal: { name: 'teal', hex: '#005c67', variant: 'vivid' },
+  blue: { name: 'blue', hex: '#1d9bf0', variant: 'vivid' },
+  green: { name: 'green', hex: '#10b981', variant: 'vivid' },
+  amber: { name: 'amber', hex: '#f59e0b', variant: 'vivid' },
+  yellow: { name: 'yellow', hex: '#ffc300', variant: 'vivid' },
+  red: { name: 'red', hex: '#ef4444', variant: 'vivid' },
+  purple: { name: 'purple', hex: '#8b5cf6', variant: 'vivid' },
+  pink: { name: 'pink', hex: '#ec4899', variant: 'vivid' },
+  sky: { name: 'sky', hex: '#0ea5e9', variant: 'vivid' },
+  orange: { name: 'orange', hex: '#f97316', variant: 'vivid' },
+  mint: { name: 'mint', hex: '#14b8a6', variant: 'vivid' },
+  oxy: { name: 'oxy', hex: '#c46ede', variant: 'vivid' },
+  faircoin: { name: 'faircoin', hex: '#9ffb50', variant: 'vivid' },
 };

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

@@ -65,12 +65,25 @@ export interface SeedScopeOptions {
   seed: string;
   mode: 'light' | 'dark';
   /**
-   * The tonal scheme variant. Defaults to `'vibrant'` — the same variant every
-   * named Bloom preset uses, so a preset's seed reproduces that preset exactly.
+   * The tonal scheme variant. Defaults to `'vivid'` — the same variant every
+   * named Bloom preset uses, so a preset's seed reproduces that preset exactly
+   * (and an artwork-extracted seed gets the same brand-vivid feel as the app).
    */
   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;
 }
 
 /**
@@ -88,8 +101,11 @@ export interface SeedScopeOptions {
 export function buildSeedScopeVars(options: SeedScopeOptions): Record<string, string> {
   const roles = generateRoleColors({
     seed: options.seed,
+    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;