@oxyhq/bloom 0.41.0 → 0.42.1

package/src/theme/__tests__/explicit-accents.test.ts

@@ -0,0 +1,129 @@
+/**
+ * Explicit secondary/tertiary accent pinning.
+ *
+ * A brand with a distinct accent (e.g. blue primary + yellow secondary) can PIN
+ * its real accent colours instead of the engine deriving secondary/tertiary as
+ * hue-rotations of the primary seed. These tests assert:
+ *   1. pinning shifts the secondary/tertiary family HUE toward the pinned colour
+ *      (and away from the derived one), and
+ *   2. omitting the seeds is byte-identical to the pre-feature derived output.
+ */
+import {
+  argbFromHex,
+  generateRoleColors,
+  type RoleColors,
+} from '../color-engine';
+import { Hct } from '../color-engine/hct';
+import { buildSeedScopeVars } from '../color-scope/seed-scope';
+
+/** Hue (deg) of an `rgb(r g b)` engine output string. */
+function hueOf(rgb: string): number {
+  const m = rgb.match(/rgb\((\d+) (\d+) (\d+)\)/);
+  if (!m) throw new Error(`expected "rgb(r g b)", got: ${rgb}`);
+  const argb = (0xff << 24) | (Number(m[1]) << 16) | (Number(m[2]) << 8) | Number(m[3]);
+  return Hct.fromInt(argb >>> 0).hue;
+}
+
+/** Smallest absolute angular distance between two hues, in degrees (0–180). */
+function hueDistance(a: number, b: number): number {
+  const d = Math.abs(a - b) % 360;
+  return d > 180 ? 360 - d : d;
+}
+
+const BLUE = '#1d9bf0';
+const YELLOW = '#ffc300';
+const PINK = '#ec4899';
+
+describe('explicit accent pinning — generateRoleColors', () => {
+  const derived: RoleColors = generateRoleColors({ seed: BLUE, variant: 'vivid', isDark: false });
+
+  it('pins the secondary family to the supplied colour hue', () => {
+    const pinned = generateRoleColors({
+      seed: BLUE,
+      variant: 'vivid',
+      isDark: false,
+      secondarySeed: YELLOW,
+    });
+
+    const yellowHue = Hct.fromInt(argbFromHex(YELLOW)).hue;
+    // The pinned secondary family reads at the yellow hue…
+    expect(hueDistance(hueOf(pinned.secondary), yellowHue)).toBeLessThan(20);
+    // …and its container / on-colour roles share that hue family too.
+    expect(hueDistance(hueOf(pinned.secondaryContainer), yellowHue)).toBeLessThan(20);
+    expect(hueDistance(hueOf(pinned.onSecondaryContainer), yellowHue)).toBeLessThan(20);
+    // …which differs materially from the derived (blue-rotation) secondary.
+    expect(hueDistance(hueOf(pinned.secondary), hueOf(derived.secondary))).toBeGreaterThan(30);
+  });
+
+  it('pins the tertiary family independently of the secondary', () => {
+    const pinned = generateRoleColors({
+      seed: BLUE,
+      variant: 'vivid',
+      isDark: false,
+      tertiarySeed: PINK,
+    });
+
+    const pinkHue = Hct.fromInt(argbFromHex(PINK)).hue;
+    expect(hueDistance(hueOf(pinned.tertiary), pinkHue)).toBeLessThan(20);
+    expect(hueDistance(hueOf(pinned.tertiary), hueOf(derived.tertiary))).toBeGreaterThan(20);
+    // Secondary is untouched when only tertiary is pinned.
+    expect(pinned.secondary).toBe(derived.secondary);
+  });
+
+  it('pins both accents at once, leaving primary + neutrals unchanged', () => {
+    const pinned = generateRoleColors({
+      seed: BLUE,
+      variant: 'vivid',
+      isDark: false,
+      secondarySeed: YELLOW,
+      tertiarySeed: PINK,
+    });
+
+    expect(hueDistance(hueOf(pinned.secondary), Hct.fromInt(argbFromHex(YELLOW)).hue)).toBeLessThan(20);
+    expect(hueDistance(hueOf(pinned.tertiary), Hct.fromInt(argbFromHex(PINK)).hue)).toBeLessThan(20);
+    // Primary + surfaces are seed-driven and must not move.
+    expect(pinned.primary).toBe(derived.primary);
+    expect(pinned.background).toBe(derived.background);
+    expect(pinned.surfaceContainerLowest).toBe(derived.surfaceContainerLowest);
+  });
+
+  it('is byte-identical to the derived output when no accents are supplied', () => {
+    const again = generateRoleColors({ seed: BLUE, variant: 'vivid', isDark: false });
+    expect(again).toEqual(derived);
+  });
+
+  it('applies pinned accents in dark mode too', () => {
+    const pinnedDark = generateRoleColors({
+      seed: BLUE,
+      variant: 'vivid',
+      isDark: true,
+      secondarySeed: YELLOW,
+    });
+    expect(hueDistance(hueOf(pinnedDark.secondary), Hct.fromInt(argbFromHex(YELLOW)).hue)).toBeLessThan(20);
+  });
+});
+
+describe('explicit accent pinning — arbitrary-seed scope path', () => {
+  it('threads pinned accents through buildSeedScopeVars', () => {
+    const derivedVars = buildSeedScopeVars({ seed: BLUE, mode: 'light' });
+    const pinnedVars = buildSeedScopeVars({
+      seed: BLUE,
+      mode: 'light',
+      secondarySeed: YELLOW,
+      tertiarySeed: PINK,
+    });
+
+    const yellowHue = Hct.fromInt(argbFromHex(YELLOW)).hue;
+    const pinkHue = Hct.fromInt(argbFromHex(PINK)).hue;
+
+    expect(pinnedVars['--secondary']).toBeDefined();
+    expect(hueDistance(hueOf(pinnedVars['--secondary'] ?? ''), yellowHue)).toBeLessThan(20);
+    expect(hueDistance(hueOf(pinnedVars['--tertiary'] ?? ''), pinkHue)).toBeLessThan(20);
+    // The scoped `--color-*` alias tracks the pinned value too (web utility contract).
+    expect(pinnedVars['--color-secondary']).toBe(pinnedVars['--secondary']);
+    // Primary token is unchanged vs the derived scope.
+    expect(pinnedVars['--primary']).toBe(derivedVars['--primary']);
+    // Derived secondary differs from the pinned one.
+    expect(pinnedVars['--secondary']).not.toBe(derivedVars['--secondary']);
+  });
+});

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

@@ -1,5 +1,6 @@
 import { Platform } from 'react-native';
 import { APP_COLOR_PRESETS, type AppColorName } from './color-presets';
+import type { ExplicitAccents } from './preset-vars';
 import { getResolvedTokens } from './token-registry';
 
 export function applyDarkClass(resolved: 'light' | 'dark') {
@@ -25,11 +26,15 @@ export function applyDarkClass(resolved: 'light' | 'dark') {
  * Includes extended tokens (card, chart-*, content-area, sidebar-*) so consumer
  * apps don't need to synthesize them.
  */
-export function applyColorPresetVars(preset: AppColorName, resolved: 'light' | 'dark') {
+export function applyColorPresetVars(
+  preset: AppColorName,
+  resolved: 'light' | 'dark',
+  accents?: ExplicitAccents,
+) {
   if (Platform.OS !== 'web' || typeof document === 'undefined') return;
   if (!APP_COLOR_PRESETS[preset]) return;
 
-  const vars = getResolvedTokens(preset, resolved);
+  const vars = getResolvedTokens(preset, resolved, accents);
   const root = document.documentElement.style;
 
   for (const [key, value] of Object.entries(vars)) {

package/src/theme/build-theme-from-seed.ts

@@ -4,6 +4,18 @@ import { STATUS_COLORS } from './build-theme';
 import { THEME_GRADIENTS } from './gradients';
 import type { Theme, ThemeColors } from './types';
 
+/**
+ * Optional explicit accent seeds for the arbitrary-seed theme path. Pinning a
+ * `secondarySeed` / `tertiarySeed` (`#rrggbb`) forces that accent family to the
+ * given brand colour instead of the derived hue-rotation — mirroring
+ * {@link GenerateOptions.secondarySeed}. For an artwork-derived theme, pass the
+ * ranked `seedsFromImagePixels` results (`seeds[1]` / `seeds[2]`).
+ */
+export interface SeedAccents {
+  secondarySeed?: string;
+  tertiarySeed?: string;
+}
+
 /**
  * Build the JS `theme.colors` object from an ARBITRARY seed colour — the dynamic
  * counterpart of `buildTheme(preset, …)`.
@@ -22,8 +34,16 @@ export function buildColorsFromSeed(
   resolved: 'light' | 'dark',
   variant?: SchemeVariant,
   contrastLevel?: number,
+  accents?: SeedAccents,
 ): ThemeColors {
-  const t = buildSeedScopeVars({ seed, mode: resolved, variant, contrastLevel });
+  const t = buildSeedScopeVars({
+    seed,
+    mode: resolved,
+    variant,
+    contrastLevel,
+    secondarySeed: accents?.secondarySeed,
+    tertiarySeed: accents?.tertiarySeed,
+  });
   const isDark = resolved === 'dark';
 
   // Read a resolved `rgb(...)` token by its bare name (no leading `--`).
@@ -34,6 +54,8 @@ export function buildColorsFromSeed(
     variant,
     isDark,
     contrastLevel,
+    secondarySeed: accents?.secondarySeed,
+    tertiarySeed: accents?.tertiarySeed,
   });
 
   return {
@@ -88,10 +110,11 @@ export function buildThemeFromSeed(
   resolved: 'light' | 'dark',
   variant?: SchemeVariant,
   contrastLevel?: number,
+  accents?: SeedAccents,
 ): Theme {
   return {
     mode: resolved,
-    colors: buildColorsFromSeed(seed, resolved, variant, contrastLevel),
+    colors: buildColorsFromSeed(seed, resolved, variant, contrastLevel, accents),
     gradients: THEME_GRADIENTS,
     isDark: resolved === 'dark',
     isLight: resolved === 'light',

package/src/theme/build-theme.ts

@@ -1,6 +1,7 @@
 import { Platform } from 'react-native';
 import { APP_COLOR_PRESETS, type AppColorName } from './color-presets';
 import { generateRoleColors, type RoleColors } from './color-engine';
+import type { ExplicitAccents } from './preset-vars';
 import { getAdaptiveColors } from './adaptive-colors';
 import { getResolvedTokens } from './token-registry';
 import { THEME_GRADIENTS } from './gradients';
@@ -32,20 +33,24 @@ export const STATUS_COLORS = {
 function buildColorsFromPreset(
   preset: AppColorName,
   resolved: 'light' | 'dark',
+  accents?: ExplicitAccents,
 ): ThemeColors {
-  const t = getResolvedTokens(preset, resolved);
+  const t = getResolvedTokens(preset, resolved, accents);
   const isDark = resolved === 'dark';
 
   // Read a resolved `rgb(...)` token by its bare name (no leading `--`).
   const g = (k: string): string => t[`--${k}`] ?? 'rgb(0 0 0)';
 
   // The full engine role set — for fields that map to roles Bloom's canonical
-  // token set does not surface (containers, error family).
+  // token set does not surface (containers, error family). An app-wide accent
+  // override wins over the preset's own declared accent (else derived).
   const config = APP_COLOR_PRESETS[preset];
   const r: RoleColors = generateRoleColors({
     seed: config.hex,
     variant: config.variant,
     isDark,
+    secondarySeed: accents?.secondaryHex ?? config.secondaryHex,
+    tertiarySeed: accents?.tertiaryHex ?? config.tertiaryHex,
   });
 
   return {
@@ -105,9 +110,10 @@ export function buildTheme(
   preset: AppColorName,
   resolved: 'light' | 'dark',
   isAdaptive: boolean = false,
+  accents?: ExplicitAccents,
 ): Theme {
   const adaptive = isAdaptive && Platform.OS !== 'web' ? getAdaptiveColors() : undefined;
-  const colors = adaptive ?? buildColorsFromPreset(preset, resolved);
+  const colors = adaptive ?? buildColorsFromPreset(preset, resolved, accents);
 
   return {
     mode: resolved,

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

@@ -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';