@oxyhq/bloom 0.80.0 → 0.81.0

package/src/theme/__tests__/__fixtures__/golden-resolved-tokens.json

@@ -1558,5 +1558,125 @@
     "--info-foreground": "rgb(255 255 255)",
     "--info-text": "rgb(173 198 255)",
     "--info-subtle": "rgba(59, 130, 246, 0.24)"
+  },
+  "mono/light": {
+    "--background": "rgb(243 243 243)",
+    "--foreground": "rgb(27 27 27)",
+    "--surface": "rgb(243 243 243)",
+    "--surface-foreground": "rgb(27 27 27)",
+    "--popover": "rgb(238 238 238)",
+    "--popover-foreground": "rgb(27 27 27)",
+    "--primary": "rgb(31 31 31)",
+    "--primary-foreground": "rgb(255 255 255)",
+    "--secondary": "rgb(85 85 85)",
+    "--secondary-foreground": "rgb(255 255 255)",
+    "--tertiary": "rgb(31 31 31)",
+    "--tertiary-foreground": "rgb(255 255 255)",
+    "--muted": "rgb(232 232 232)",
+    "--muted-foreground": "rgb(71 71 71)",
+    "--accent": "rgb(232 232 232)",
+    "--accent-foreground": "rgb(71 71 71)",
+    "--destructive": "rgb(186 26 26)",
+    "--border": "rgb(198 198 198)",
+    "--input": "rgb(198 198 198)",
+    "--ring": "rgb(0 0 0)",
+    "--sidebar": "rgb(243 243 243)",
+    "--card": "rgb(255 255 255)",
+    "--card-foreground": "rgb(27 27 27)",
+    "--chart-1": "rgb(193 193 193)",
+    "--chart-2": "rgb(158 158 158)",
+    "--chart-3": "rgb(124 124 124)",
+    "--chart-4": "rgb(92 92 92)",
+    "--chart-5": "rgb(62 62 62)",
+    "--content-area": "rgb(249 249 249)",
+    "--sidebar-foreground": "rgb(27 27 27)",
+    "--sidebar-primary": "rgb(0 0 0)",
+    "--sidebar-primary-foreground": "rgb(226 226 226)",
+    "--sidebar-accent": "rgb(212 212 212)",
+    "--sidebar-accent-foreground": "rgb(27 27 27)",
+    "--sidebar-border": "rgb(198 198 198)",
+    "--sidebar-ring": "rgb(0 0 0)",
+    "--primary-text": "rgb(0 0 0)",
+    "--primary-subtle": "rgba(145, 145, 145, 0.13)",
+    "--secondary-text": "rgb(94 94 94)",
+    "--secondary-subtle": "rgba(145, 145, 145, 0.13)",
+    "--tertiary-text": "rgb(94 94 94)",
+    "--tertiary-subtle": "rgba(145, 145, 145, 0.13)",
+    "--success": "rgb(0 122 83)",
+    "--success-foreground": "rgb(255 255 255)",
+    "--success-text": "rgb(0 108 73)",
+    "--success-subtle": "rgba(16, 185, 129, 0.13)",
+    "--error": "rgb(203 41 46)",
+    "--error-foreground": "rgb(255 255 255)",
+    "--error-text": "rgb(167 55 53)",
+    "--error-subtle": "rgba(239, 68, 68, 0.13)",
+    "--warning": "rgb(150 94 0)",
+    "--warning-foreground": "rgb(255 255 255)",
+    "--warning-text": "rgb(133 83 0)",
+    "--warning-subtle": "rgba(245, 158, 11, 0.13)",
+    "--info": "rgb(5 102 217)",
+    "--info-foreground": "rgb(255 255 255)",
+    "--info-text": "rgb(1 90 194)",
+    "--info-subtle": "rgba(59, 130, 246, 0.13)"
+  },
+  "mono/dark": {
+    "--background": "rgb(14 14 14)",
+    "--foreground": "rgb(226 226 226)",
+    "--surface": "rgb(27 27 27)",
+    "--surface-foreground": "rgb(226 226 226)",
+    "--popover": "rgb(31 31 31)",
+    "--popover-foreground": "rgb(226 226 226)",
+    "--primary": "rgb(238 238 238)",
+    "--primary-foreground": "rgb(0 0 0)",
+    "--secondary": "rgb(176 176 176)",
+    "--secondary-foreground": "rgb(0 0 0)",
+    "--tertiary": "rgb(238 238 238)",
+    "--tertiary-foreground": "rgb(0 0 0)",
+    "--muted": "rgb(42 42 42)",
+    "--muted-foreground": "rgb(198 198 198)",
+    "--accent": "rgb(42 42 42)",
+    "--accent-foreground": "rgb(198 198 198)",
+    "--destructive": "rgb(255 180 171)",
+    "--border": "rgb(71 71 71)",
+    "--input": "rgb(71 71 71)",
+    "--ring": "rgb(255 255 255)",
+    "--sidebar": "rgb(27 27 27)",
+    "--card": "rgb(31 31 31)",
+    "--card-foreground": "rgb(226 226 226)",
+    "--chart-1": "rgb(94 94 94)",
+    "--chart-2": "rgb(127 127 127)",
+    "--chart-3": "rgb(160 160 160)",
+    "--chart-4": "rgb(196 196 196)",
+    "--chart-5": "rgb(232 232 232)",
+    "--content-area": "rgb(19 19 19)",
+    "--sidebar-foreground": "rgb(226 226 226)",
+    "--sidebar-primary": "rgb(255 255 255)",
+    "--sidebar-primary-foreground": "rgb(27 27 27)",
+    "--sidebar-accent": "rgb(71 71 71)",
+    "--sidebar-accent-foreground": "rgb(226 226 226)",
+    "--sidebar-border": "rgb(71 71 71)",
+    "--sidebar-ring": "rgb(255 255 255)",
+    "--primary-text": "rgb(255 255 255)",
+    "--primary-subtle": "rgba(145, 145, 145, 0.24)",
+    "--secondary-text": "rgb(198 198 198)",
+    "--secondary-subtle": "rgba(145, 145, 145, 0.24)",
+    "--tertiary-text": "rgb(198 198 198)",
+    "--tertiary-subtle": "rgba(145, 145, 145, 0.24)",
+    "--success": "rgb(0 133 91)",
+    "--success-foreground": "rgb(255 255 255)",
+    "--success-text": "rgb(59 224 161)",
+    "--success-subtle": "rgba(16, 185, 129, 0.24)",
+    "--error": "rgb(218 52 55)",
+    "--error-foreground": "rgb(255 255 255)",
+    "--error-text": "rgb(255 179 173)",
+    "--error-subtle": "rgba(239, 68, 68, 0.24)",
+    "--warning": "rgb(163 103 0)",
+    "--warning-foreground": "rgb(255 255 255)",
+    "--warning-text": "rgb(255 185 95)",
+    "--warning-subtle": "rgba(245, 158, 11, 0.24)",
+    "--info": "rgb(33 112 228)",
+    "--info-foreground": "rgb(255 255 255)",
+    "--info-text": "rgb(173 198 255)",
+    "--info-subtle": "rgba(59, 130, 246, 0.24)"
   }
 }

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

@@ -352,6 +352,76 @@ exports[`theme.colors snapshot for all presets (catches unintended palette shift
     "tint": "rgb(0 120 108)",
     "warning": "rgb(150 94 0)",
   },
+  "mono/dark": {
+    "background": "rgb(14 14 14)",
+    "backgroundSecondary": "rgb(27 27 27)",
+    "backgroundTertiary": "rgb(31 31 31)",
+    "border": "rgb(71 71 71)",
+    "borderLight": "rgb(71 71 71)",
+    "card": "rgb(31 31 31)",
+    "contrast50": "rgb(42 42 42)",
+    "error": "rgb(218 52 55)",
+    "icon": "rgb(198 198 198)",
+    "iconActive": "rgb(238 238 238)",
+    "info": "rgb(33 112 228)",
+    "negative": "rgb(255 180 171)",
+    "negativeForeground": "rgb(105 0 5)",
+    "negativeSubtle": "rgba(239, 68, 68, 0.24)",
+    "negativeSubtleForeground": "rgb(255 179 173)",
+    "overlay": "rgba(0, 0, 0, 0.5)",
+    "primary": "rgb(238 238 238)",
+    "primaryDark": "rgb(14 14 14)",
+    "primaryForeground": "rgb(0 0 0)",
+    "primaryLight": "rgb(27 27 27)",
+    "primarySubtle": "rgba(145, 145, 145, 0.24)",
+    "primarySubtleForeground": "rgb(0 0 0)",
+    "secondary": "rgb(176 176 176)",
+    "secondaryForeground": "rgb(0 0 0)",
+    "shadow": "rgba(0, 0, 0, 0.3)",
+    "success": "rgb(0 133 91)",
+    "tertiary": "rgb(238 238 238)",
+    "tertiaryForeground": "rgb(0 0 0)",
+    "text": "rgb(226 226 226)",
+    "textSecondary": "rgb(198 198 198)",
+    "textTertiary": "rgb(145 145 145)",
+    "tint": "rgb(238 238 238)",
+    "warning": "rgb(163 103 0)",
+  },
+  "mono/light": {
+    "background": "rgb(243 243 243)",
+    "backgroundSecondary": "rgb(243 243 243)",
+    "backgroundTertiary": "rgb(238 238 238)",
+    "border": "rgb(198 198 198)",
+    "borderLight": "rgb(198 198 198)",
+    "card": "rgb(255 255 255)",
+    "contrast50": "rgb(232 232 232)",
+    "error": "rgb(203 41 46)",
+    "icon": "rgb(71 71 71)",
+    "iconActive": "rgb(31 31 31)",
+    "info": "rgb(5 102 217)",
+    "negative": "rgb(186 26 26)",
+    "negativeForeground": "rgb(255 255 255)",
+    "negativeSubtle": "rgba(239, 68, 68, 0.13)",
+    "negativeSubtleForeground": "rgb(167 55 53)",
+    "overlay": "rgba(0, 0, 0, 0.5)",
+    "primary": "rgb(31 31 31)",
+    "primaryDark": "rgb(243 243 243)",
+    "primaryForeground": "rgb(255 255 255)",
+    "primaryLight": "rgb(243 243 243)",
+    "primarySubtle": "rgba(145, 145, 145, 0.13)",
+    "primarySubtleForeground": "rgb(255 255 255)",
+    "secondary": "rgb(85 85 85)",
+    "secondaryForeground": "rgb(255 255 255)",
+    "shadow": "rgba(0, 0, 0, 0.1)",
+    "success": "rgb(0 122 83)",
+    "tertiary": "rgb(31 31 31)",
+    "tertiaryForeground": "rgb(255 255 255)",
+    "text": "rgb(27 27 27)",
+    "textSecondary": "rgb(71 71 71)",
+    "textTertiary": "rgb(119 119 119)",
+    "tint": "rgb(31 31 31)",
+    "warning": "rgb(150 94 0)",
+  },
   "orange/dark": {
     "background": "rgb(23 11 5)",
     "backgroundSecondary": "rgb(38 24 17)",

package/src/theme/__tests__/policy-legibility.test.ts

@@ -3,7 +3,7 @@
  *
  * Every accent and status family is generated, not authored, so nothing else in
  * the suite can notice when a tuning change makes a label unreadable. This walks
- * the full matrix — 13 presets x 2 modes x 7 families — and asserts the property
+ * the full matrix — every preset x 2 modes x 7 families — and asserts the property
  * a user actually perceives.
  *
  * Two failure shapes it exists to catch, both of which have already happened:
@@ -124,7 +124,11 @@ describe('colour policy legibility', () => {
   // Each half was individually legible, so nothing else could catch either.
   it('the brand fill keeps light exemption-free and dark budgeted', () => {
     const white = { light: 0, dark: 0 };
-    for (const preset of APP_COLOR_NAMES) {
+    // `mono` is not governed by the budget — it has no chroma to preserve, and its
+    // dark fill is near-WHITE by design, so it takes a black label on purpose.
+    // Counting it here would let a real regression hide inside its slack.
+    const chromatic = APP_COLOR_NAMES.filter((name) => name !== 'mono');
+    for (const preset of chromatic) {
       for (const mode of ['light', 'dark'] as const) {
         if (getResolvedTokens(preset, mode)['--primary-foreground'] === 'rgb(255 255 255)') {
           white[mode] += 1;
@@ -133,7 +137,11 @@ describe('colour policy legibility', () => {
     }
     // Light admits no exemption, so every preset carries white there. Dark keeps
     // the budget, so the seeds that are already light keep their colour instead.
-    expect(white.light).toBe(APP_COLOR_NAMES.length);
-    expect(white.dark).toBeGreaterThan(APP_COLOR_NAMES.length - 4);
+    expect(white.light).toBe(chromatic.length);
+    expect(white.dark).toBeGreaterThan(chromatic.length - 4);
+    // And the monochrome exception itself, stated rather than tolerated: a fill at
+    // each end of the scale, carrying the opposite label.
+    expect(getResolvedTokens('mono', 'light')['--primary-foreground']).toBe('rgb(255 255 255)');
+    expect(getResolvedTokens('mono', 'dark')['--primary-foreground']).toBe('rgb(0 0 0)');
   });
 });

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

@@ -10,7 +10,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 { buildScheme, schemeVibrant, schemeExpressive, schemeTonalSpot, schemeNeutral, schemeMonochrome } from './scheme-variants';
 export type { SchemeVariant, AccentSources } from './scheme-variants';
 export { Roles } from './color-roles';
 export type { RoleName } from './color-roles';

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

@@ -13,7 +13,13 @@ import { sanitizeDegreesDouble } from './math-utils';
 import { TonalPalette } from './tonal-palette';
 import { Variant } from './variant';
 
-export type SchemeVariant = 'vivid' | 'vibrant' | 'expressive' | 'tonalSpot' | 'neutral';
+export type SchemeVariant =
+  | 'vivid'
+  | 'vibrant'
+  | 'expressive'
+  | 'tonalSpot'
+  | 'neutral'
+  | 'monochrome';
 
 /**
  * Optional explicit accent seeds for a scheme. When a source HCT is supplied, its
@@ -191,6 +197,36 @@ export function schemeNeutral(
   });
 }
 
+/**
+ * No colour at all: every palette is greyscale, so the seed's hue is irrelevant
+ * and only its tone survives. This is the variant the `isMonochrome` role
+ * branches in `color-roles` were written for — they push `primary` to the far end
+ * of the scale (tone 0 on a light page, 100 on a dark one) rather than the
+ * mid-tone the chromatic curves would pick, which is what keeps a black-and-white
+ * theme from reading as a grey one.
+ *
+ * A pinned accent is ignored on purpose: honouring it would put one coloured
+ * family back into a scheme whose entire point is that nothing is coloured.
+ */
+export function schemeMonochrome(
+  source: Hct,
+  isDark: boolean,
+  contrastLevel: number,
+): DynamicScheme {
+  const grey = (): TonalPalette => TonalPalette.fromHueAndChroma(source.hue, 0);
+  return new DynamicScheme({
+    sourceColorArgb: source.toInt(),
+    variant: Variant.MONOCHROME,
+    contrastLevel,
+    isDark,
+    primaryPalette: grey(),
+    secondaryPalette: grey(),
+    tertiaryPalette: grey(),
+    neutralPalette: grey(),
+    neutralVariantPalette: grey(),
+  });
+}
+
 const BUILDERS: Record<
   SchemeVariant,
   (s: Hct, d: boolean, c: number, accents: AccentSources) => DynamicScheme
@@ -200,6 +236,7 @@ const BUILDERS: Record<
   expressive: schemeExpressive,
   tonalSpot: schemeTonalSpot,
   neutral: schemeNeutral,
+  monochrome: schemeMonochrome,
 };
 
 /**

package/src/theme/color-policy.ts

@@ -131,6 +131,29 @@ const TEXT_CHROMA = 60;
 const SUBTLE_SOURCE_TONE = 60;
 const SUBTLE_ALPHA = { light: 0.13, dark: 0.24 } as const;
 
+/**
+ * A seed at or below this chroma has no colour to derive from, so the whole
+ * palette goes greyscale — the black-and-white theme. Keyed on the seed rather
+ * than on a flag, so picking any grey in a colour wheel lands there too instead
+ * of on a nearly-grey approximation of it.
+ */
+const MONOCHROME_MAX_CHROMA = 6;
+
+/**
+ * Whether a seed carries no colour to derive a theme from — the one authority for
+ * that question, so the policy and the scheme choice can never disagree about a
+ * given seed and produce a grey palette wearing chromatic surfaces.
+ */
+export function isColourlessSeed(seedHex: string): boolean {
+  return Hct.fromInt(argbFromHex(seedHex)).chroma <= MONOCHROME_MAX_CHROMA;
+}
+
+/** Where a monochrome brand fill sits: near-black on a white page, near-white on a black one. */
+const MONOCHROME_FILL_TONE = { light: 12, dark: 94 } as const;
+
+/** The quiet member of a monochrome trio — the only one that is actually grey. */
+const MONOCHROME_SECONDARY_TONE = { light: 36, dark: 72 } as const;
+
 /** Split-complementary: the two accents sit either side of the seed's complement. */
 const SPLIT_ROTATIONS = [150, 210] as const;
 
@@ -211,7 +234,8 @@ function vividHueNear(hue: number): number {
  * ceasing to be itself: yellow turns to brown and lime to moss. Those keep their
  * own tone and take a black label instead, which is what a bright yellow button
  * wants anyway. The 25-tone budget is what separates the two cases, and it is
- * why 11 of the 13 presets carry white and exactly the two light ones do not.
+ * why 11 of the 13 chromatic presets carry white and exactly the two light ones
+ * do not. (`mono` sits outside this rule — see MONOCHROME_FILL_TONE.)
  */
 function whiteLabelTone(palette: TonalPalette, seedTone: number, isDark: boolean): number {
   // LIGHT: every fill comes down, no exemption. On a near-white page a bright
@@ -306,12 +330,24 @@ export function buildPolicyTokens(
   // tone <= 49, so that is the ceiling — in dark as much as in light. Letting the
   // dark fill sit at the seed's own tone instead makes it brighter, but every one
   // of those labels turns black, which costs more than the brightness buys.
+  const monochrome = seed.chroma <= MONOCHROME_MAX_CHROMA;
   // DARK keys off the seed itself so the fill IS the brand hex; LIGHT uses the
   // max-chroma palette, which is what stops a deepened fill from going pastel.
-  const brandPalette = isDark
-    ? TonalPalette.fromInt(argbFromHex(seedHex))
-    : TonalPalette.fromHueAndChroma(seed.hue, 200);
-  const primary = fillPair(brandPalette, whiteLabelTone(brandPalette, seed.tone, isDark));
+  // A monochrome seed has no chroma to preserve either way, and its fill goes to
+  // the far end of the scale rather than the white-label ceiling: a mid-grey
+  // button reads as disabled, where near-black on white reads as the primary
+  // action.
+  const brandPalette = monochrome
+    ? TonalPalette.fromHueAndChroma(0, 0)
+    : isDark
+      ? TonalPalette.fromInt(argbFromHex(seedHex))
+      : TonalPalette.fromHueAndChroma(seed.hue, 200);
+  const primary = fillPair(
+    brandPalette,
+    monochrome
+      ? (isDark ? MONOCHROME_FILL_TONE.dark : MONOCHROME_FILL_TONE.light)
+      : whiteLabelTone(brandPalette, seed.tone, isDark),
+  );
 
   const tokens: PolicyTokens = {
     '--primary': primary.fill,
@@ -320,7 +356,7 @@ export function buildPolicyTokens(
     // does correctly, and which the fill must stop trying to do at the same time.
     '--primary-text': roles.primary,
     '--primary-subtle': rgba(
-      TonalPalette.fromHueAndChroma(seed.hue, 200).tone(SUBTLE_SOURCE_TONE),
+      TonalPalette.fromHueAndChroma(seed.hue, monochrome ? 0 : 200).tone(SUBTLE_SOURCE_TONE),
       isDark ? SUBTLE_ALPHA.dark : SUBTLE_ALPHA.light,
     ),
     '--ring': roles.primary,
@@ -332,7 +368,9 @@ export function buildPolicyTokens(
     '--card': isDark ? roles.surfaceContainer : roles.surfaceContainerLowest,
     // A touch darker than M3's page background: near-white reads as unfinished
     // next to the card, and the extra step gives the surface ramp somewhere to sit.
-    '--background': rgb(TonalPalette.fromHueAndChroma(seed.hue, 10).tone(isDark ? 4 : 96)),
+    '--background': rgb(
+      TonalPalette.fromHueAndChroma(seed.hue, monochrome ? 0 : 10).tone(isDark ? 4 : 96),
+    ),
     // `--accent` stays what every consumer actually uses it for: a hover surface.
     '--accent': roles.surfaceContainerHigh,
     '--accent-foreground': roles.onSurfaceVariant,
@@ -344,9 +382,11 @@ export function buildPolicyTokens(
     const hue = pin !== undefined ? Hct.fromInt(argbFromHex(pin)).hue : hues[role];
     // One hue, three palettes. Every member shares it, so the family still reads
     // as one colour; only how loudly each speaks differs.
-    const fillPalette = TonalPalette.fromHueAndChroma(hue, ACCENT_CHROMA);
-    const textPalette = TonalPalette.fromHueAndChroma(hue, TEXT_CHROMA);
-    const vividPalette = TonalPalette.fromHueAndChroma(hue, 200);
+    // A monochrome theme has no accents to rotate to; the trio becomes a ladder
+    // of greys, which still separates a standout button from a quiet one.
+    const fillPalette = TonalPalette.fromHueAndChroma(hue, monochrome ? 0 : ACCENT_CHROMA);
+    const textPalette = TonalPalette.fromHueAndChroma(hue, monochrome ? 0 : TEXT_CHROMA);
+    const vividPalette = TonalPalette.fromHueAndChroma(hue, monochrome ? 0 : 200);
     // DARK sits at the hue's peak tone, floored by the same rule the brand fill
     // uses: some hues peak dark (violet at 35), and rendering them there gives a
     // slab rather than a highlight. LIGHT goes deep like every other fill, but
@@ -362,7 +402,20 @@ export function buildPolicyTokens(
     // black. The accent chroma cap already keeps these hues out of neon territory,
     // and the hue itself is the caller's brand rather than ours to move. The
     // analyzer still runs where it was designed to, inside `color-roles`.
-    const tone = accentTone(hue, isDark);
+    // Monochrome keeps `tertiary` AT the brand fill rather than a step off it:
+    // tertiary is what a compose button and a FAB paint with, and those are the
+    // primary action — a step of grey between them and `primary` reads as two
+    // buttons disagreeing, not as hierarchy. `secondary` carries the whole
+    // demotion instead.
+    const tone = monochrome
+      ? role === 'tertiary'
+        ? isDark
+          ? MONOCHROME_FILL_TONE.dark
+          : MONOCHROME_FILL_TONE.light
+        : isDark
+          ? MONOCHROME_SECONDARY_TONE.dark
+          : MONOCHROME_SECONDARY_TONE.light
+      : accentTone(hue, isDark);
     const pair = fillPair(fillPalette, tone);
     tokens[`--${role}`] = pair.fill;
     tokens[`--${role}-foreground`] = pair.foreground;
@@ -377,9 +430,10 @@ export function buildPolicyTokens(
   // The old ramp drew all five from the primary/secondary/tertiary trio, which
   // spans ~35 degrees, so adjacent series were indistinguishable.
   for (let i = 0; i < 5; i += 1) {
-    tokens[`--chart-${i + 1}`] = rgb(
-      TonalPalette.fromHueAndChroma((seed.hue + i * 72) % 360, 60).tone(isDark ? 72 : 48),
-    );
+    // Greyscale charts spread by TONE instead of hue — the only axis left.
+    tokens[`--chart-${i + 1}`] = monochrome
+      ? rgb(TonalPalette.fromHueAndChroma(0, 0).tone(isDark ? 40 + i * 13 : 78 - i * 13))
+      : rgb(TonalPalette.fromHueAndChroma((seed.hue + i * 72) % 360, 60).tone(isDark ? 72 : 48));
   }
 
   // The status family, themed per mode. The four frozen hexes it replaces all

package/src/theme/color-presets.ts

@@ -13,7 +13,8 @@ export type AppColorName =
   | 'orange'
   | 'mint'
   | 'oxy'
-  | 'faircoin';
+  | 'faircoin'
+  | 'mono';
 
 /**
  * A single colour preset: a brand SEED colour plus the tonal scheme variant to
@@ -56,7 +57,7 @@ export interface AppColorPreset {
  */
 export type PresetTokens = Record<string, string>;
 
-export const APP_COLOR_NAMES: readonly AppColorName[] = ['teal', 'blue', 'green', 'amber', 'yellow', 'red', 'purple', 'pink', 'sky', 'orange', 'mint', 'oxy', 'faircoin'];
+export const APP_COLOR_NAMES: readonly AppColorName[] = ['teal', 'blue', 'green', 'amber', 'yellow', 'red', 'purple', 'pink', 'sky', 'orange', 'mint', 'oxy', 'faircoin', 'mono'];
 
 /** Premium-exclusive presets, hidden from the standard color picker. */
 export const PREMIUM_COLOR_NAMES: readonly AppColorName[] = ['oxy', 'faircoin'];
@@ -75,6 +76,7 @@ export const HEX_TO_APP_COLOR: Record<string, AppColorName> = {
   '#14b8a6': 'mint',
   '#c46ede': 'oxy',
   '#9ffb50': 'faircoin',
+  '#000000': 'mono',
 };
 
 export function hexToAppColorName(hex: string): AppColorName {
@@ -101,4 +103,11 @@ export const APP_COLOR_PRESETS: Record<AppColorName, AppColorPreset> = {
   mint: { name: 'mint', hex: '#14b8a6', variant: 'vivid' },
   oxy: { name: 'oxy', hex: '#c46ede', variant: 'vivid' },
   faircoin: { name: 'faircoin', hex: '#9ffb50', variant: 'vivid' },
+  /**
+   * No colour at all — the black-and-white theme. Its seed carries zero chroma,
+   * which is the whole mechanism: the policy derives a greyscale palette from any
+   * seed with none, so a user who picks a grey in the colour wheel lands here too
+   * rather than on a nearly-grey approximation.
+   */
+  mono: { name: 'mono', hex: '#000000', variant: 'monochrome' },
 };

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

@@ -1,5 +1,5 @@
 import { generateRoleColors, type RoleColors, type SchemeVariant } from '../color-engine';
-import { buildPolicyTokens } from '../color-policy';
+import { buildPolicyTokens, isColourlessSeed } from '../color-policy';
 import { CANONICAL_TOKENS } from '../token-registry';
 
 /**
@@ -104,7 +104,11 @@ export interface SeedScopeOptions {
 export function buildSeedScopeVars(options: SeedScopeOptions): Record<string, string> {
   const roles = generateRoleColors({
     seed: options.seed,
-    variant: options.variant ?? 'vivid',
+    // A seed with no chroma has no colour for a chromatic variant to work with,
+    // so it takes the greyscale scheme unless the caller asked for something else.
+    // This is what makes a grey picked in a colour wheel produce the SAME
+    // black-and-white theme as the `mono` preset instead of a tinted near-grey.
+    variant: options.variant ?? (isColourlessSeed(options.seed) ? 'monochrome' : 'vivid'),
     isDark: options.mode === 'dark',
     contrastLevel: options.contrastLevel ?? 0,
     secondarySeed: options.secondarySeed,