@oxy.so/bloom 3.6.0 → 4.0.0

package/src/text-field/shared.ts

@@ -1,4 +1,5 @@
 import { useMemo } from 'react';
+import type { BloomSize } from '../appearance';
 import { Platform, type ViewStyle } from 'react-native';
 
 import type { WebCssStyle } from '../styles/web-view-style';
@@ -34,7 +35,7 @@ import { TYPE_SCALE } from '../typography/scale';
  * NEUTRAL, not the accent; the accent ring belongs to the OTP boxes.
  */
 
-export type TextFieldSize = 'medium' | 'small';
+export type TextFieldSize = BloomSize | 'small' | 'medium';
 
 export interface TextFieldGeometry {
   height: number;
@@ -42,8 +43,12 @@ export interface TextFieldGeometry {
 }
 
 export const TEXT_FIELD_GEOMETRY: Record<TextFieldSize, TextFieldGeometry> = {
-  medium: { height: 36, paddingHorizontal: 8 },
-  small: { height: 32, paddingHorizontal: 6 },
+  small: {height: 32, paddingHorizontal: 6},
+  medium: {height: 36, paddingHorizontal: 8},
+  xs: { height: 28, paddingHorizontal: 4 },
+  lg: { height: 44, paddingHorizontal: 10 },
+  md: { height: 36, paddingHorizontal: 8 },
+  sm: { height: 32, paddingHorizontal: 6 },
 };
 
 /**
@@ -55,8 +60,12 @@ export const TEXT_FIELD_ADDON_PADDING: Record<
   TextFieldSize,
   { paddingLeft: number; paddingRight: number }
 > = {
-  medium: { paddingLeft: 4, paddingRight: 8 },
-  small: { paddingLeft: 4, paddingRight: 6 },
+  small: {paddingLeft: 4, paddingRight: 6},
+  medium: {paddingLeft: 4, paddingRight: 8},
+  xs: { paddingLeft: 4, paddingRight: 4 },
+  lg: { paddingLeft: 4, paddingRight: 10 },
+  md: { paddingLeft: 4, paddingRight: 8 },
+  sm: { paddingLeft: 4, paddingRight: 6 },
 };
 
 /** `rounded-2lg`. */
@@ -142,69 +151,31 @@ export { TRANSPARENT as TEXT_FIELD_TRANSPARENT };
  * Resolve the input tokens against a Bloom theme and the SURFACE the field sits
  * on. Pure, so it can be walked over every preset × mode without rendering.
  *
- * `surface` is what makes the field a field. As fixed ramp stops the dark fill
- * was `neutral-800` — byte for byte the surface `floating/menu-palette` paints a
- * menu, a popover, a select and a tooltip with, measured 1.000:1 against it. A
- * field dropped into any of those had no shell at all, and one inside a `card`
- * had 1.225:1. Every fill and every quiet text colour here is now a step off
- * whatever it was given, so the field keeps a shell wherever it lands; on the
- * page it lands within 0.04 of the colour it always had.
- *
- * The dark `color-mix(... N%, transparent)` tokens are composited over that same
- * surface, which is what they sit on.
+ * Surfaces and their foregrounds come from the shared tonal policy.
+ * Invalid fields use the semantic error tint and its paired foreground.
  */
 export function resolveTextFieldPalette(
   theme: Theme,
   surface: string = theme.colors.background,
 ): TextFieldPalette {
   const c = theme.colors;
-  const { neutral: n } = resolveButtonRamps(theme);
-  const red = colorRamp(c.negative, DANGER_TABLE);
-  const background = surfaceFillOn(theme, surface);
-  // The value, the placeholder and the counter sit on the FILL; the hint and the
-  // label sit on the surface behind it. Both are floored on the right one.
-  const onField = surfaceTextOn(theme, background);
-  const onSurface = surfaceTextOn(theme, surface);
-
-  if (theme.isDark) {
-    const backgroundDisabled = mixColor(surface, background, 0.3);
-    return {
-      background,
-      backgroundDisabled,
-      backgroundInvalid: mixColor(surface, red[950], 0.6),
-      ringHover: hairlineOn(theme, background),
-      ringFocus: n[600],
-      text: c.text,
-      textDisabled: mixColor(backgroundDisabled, n[500], 0.4),
-      placeholder: onField.textTertiary,
-      placeholderInvalid: red[400],
-      icon: onField.textTertiary,
-      iconDisabled: n[600],
-      iconInvalid: red[400],
-      hint: onSurface.textTertiary,
-      error: red[400],
-      infoIcon: n[700],
-      count: onField.textTertiary,
-    };
-  }
-
   return {
-    background,
-    backgroundDisabled: mixColor(surface, background, 0.5),
-    backgroundInvalid: red[100],
-    ringHover: hairlineOn(theme, background),
-    ringFocus: n[400],
+    background: surfaceFillOn(theme, surface),
+    backgroundDisabled: surfaceFillOn(theme, surface),
+    backgroundInvalid: c.errorSubtle,
+    ringHover: c.border,
+    ringFocus: c.primary,
     text: c.text,
-    textDisabled: n[300],
-    placeholder: onField.textTertiary,
-    placeholderInvalid: red[400],
-    icon: onField.textTertiary,
-    iconDisabled: n[300],
-    iconInvalid: red[600],
-    hint: onSurface.textTertiary,
-    error: red[500],
-    infoIcon: n[300],
-    count: onField.textTertiary,
+    textDisabled: c.textTertiary,
+    placeholder: surfaceTextOn(theme, surfaceFillOn(theme, surface)).textTertiary,
+    placeholderInvalid: c.errorSubtleForeground,
+    icon: c.textSecondary,
+    iconDisabled: c.textTertiary,
+    iconInvalid: c.errorSubtleForeground,
+    hint: surfaceTextOn(theme, surface).textTertiary,
+    error: c.errorSubtleForeground,
+    infoIcon: c.textSecondary,
+    count: surfaceTextOn(theme, surfaceFillOn(theme, surface)).textTertiary,
   };
 }
 

package/src/text-field/types.ts

@@ -8,14 +8,15 @@ export type { TextFieldSize } from './shared';
 
 export type TextFieldProps = React.PropsWithChildren<
   {
-    isInvalid?: boolean;
+    invalid?: boolean;
+  isInvalid?: boolean;
     /**
      * Paint the whole field disabled: the dimmed fill,
      * no ring, dimmed adornments, and a non-editable input. An input with
      * `disabled` or `editable={false}` reports the same state up on its own.
      */
     disabled?: boolean;
-    /** Two heights: `medium` 36 (default), `small` 32. */
+    /** Two heights: `md` 36 (default), `sm` 32. */
     size?: TextFieldSize;
     /** Corner radius of the chrome, default `10`. A large value (999) reads as a pill. */
     radius?: number;
@@ -36,7 +37,9 @@ export type TextFieldInputProps = Omit<
 > & {
   label: string;
   value?: string;
-  onChangeText?: (value: string) => void;
+  onValueChange?: (value: string) => void;
+    onChangeText?: (value: string) => void;
+  invalid?: boolean;
   isInvalid?: boolean;
   /** Disable the input; the field around it paints disabled. */
   disabled?: boolean;
@@ -72,7 +75,8 @@ export type TextFieldLabelProps = React.PropsWithChildren<
 export type TextFieldHintProps = React.PropsWithChildren<
   {
     /** Paint the hint in the error colour. */
-    isInvalid?: boolean;
+    invalid?: boolean;
+  isInvalid?: boolean;
     nativeID?: string;
   } & TextStyleProp
 >;

package/src/textarea/Textarea.tsx

@@ -1,3 +1,5 @@
+import { normalizeBloomSize } from '../appearance/legacy';
+import { useBloomAppearance } from '../appearance';
 import React, { useMemo, useRef, useState } from 'react';
 import { Platform, StyleSheet, TextInput, type TextStyle, View } from 'react-native';
 
@@ -51,6 +53,7 @@ export function Textarea({
   placeholder,
   value,
   defaultValue,
+  onValueChange: onValueChangeProp,
   onChangeText,
   onFocus,
   onBlur,
@@ -61,7 +64,8 @@ export function Textarea({
   resize = 'vertical',
   maxLength,
   showCount = false,
-  isInvalid = false,
+  invalid: invalidProp,
+  isInvalid,
   disabled = false,
   required = false,
   tooltip = false,
@@ -73,18 +77,21 @@ export function Textarea({
   testID,
   ...rest
 }: TextareaProps) {
+  const invalid = invalidProp ?? isInvalid ?? false;
+  const onValueChange = onValueChangeProp ?? onChangeText;
   const theme = useTheme();
   // The two contracts a textarea sits inside: a container's density
   // (`ControlSurface`) and an enclosing `Field`'s association. The label is
   // STACKED here, as it is on `TextField`, so the field's label wins — they are
   // two spellings of one thing and rendering both is the mistake `docs/field.mdx`
   // names.
-  const size = useInheritedControl('density', sizeProp, 'medium');
+  const { size: scopedSize } = useBloomAppearance({ size: normalizeBloomSize(sizeProp) }, { size: 'md', tone: 'neutral' });
+  const size = useInheritedControl('density', normalizeBloomSize(sizeProp), scopedSize);
   const field = useFieldMembership({
     accessibilityLabel,
     label: label ?? placeholder,
     disabled,
-    invalid: isInvalid,
+    invalid: invalid,
     required,
     nativeID,
     // An `aria-describedby` the caller spread through `rest` is KEPT and the
@@ -189,7 +196,7 @@ export function Textarea({
           keyboardAppearance={theme.isDark ? 'dark' : 'light'}
           onChangeText={(next) => {
             if (showCount && value === undefined) setTypedLength(next.length);
-            onChangeText?.(next);
+            onValueChange?.(next);
           }}
           onFocus={(e) => {
             onFocusIn();
@@ -213,7 +220,7 @@ export function Textarea({
             marginTop: TEXT_FIELD_STACK_GAP,
           }}>
           {hint ? (
-            <TextFieldHint isInvalid={field.invalid} style={{ marginTop: 0 }}>
+            <TextFieldHint invalid={field.invalid} style={{ marginTop: 0 }}>
               {hint}
             </TextFieldHint>
           ) : null}

package/src/textarea/types.ts

@@ -21,8 +21,9 @@ export type TextareaProps = Omit<
     placeholder?: string;
     value?: string;
     defaultValue?: string;
+    onValueChange?: (value: string) => void;
     onChangeText?: (value: string) => void;
-    /** Two insets: `medium` (default) or `small`. */
+    /** Two insets: `md` (default) or `sm`. */
     size?: TextFieldSize;
     /** Resting height in lines, default `3`. Also the floor when `autoResize` is on. */
     rows?: number;
@@ -36,7 +37,8 @@ export type TextareaProps = Omit<
     maxLength?: number;
     /** Show the character counter under the field (`12/280` with `maxLength`). */
     showCount?: boolean;
-    isInvalid?: boolean;
+    invalid?: boolean;
+  isInvalid?: boolean;
     disabled?: boolean;
     /** Append the required asterisk to the label. */
     required?: boolean;

package/src/theme/accent-colors.ts

@@ -38,7 +38,7 @@ import type { ThemeColors } from './types';
  * the only member with no hue, which is why it reads from the neutral surface
  * and text roles rather than from a `*Subtle` family.
  */
-export type AccentTone = 'default' | 'primary' | 'success' | 'warning' | 'error' | 'info';
+export type AccentTone = 'default' | 'primary' | 'secondary' | 'tertiary' | 'success' | 'warning' | 'error' | 'info';
 
 /**
  * How loudly it speaks: a full fill, a translucent tint, or an outline on the
@@ -86,6 +86,10 @@ function tonePalette(colors: ThemeColors, tone: AccentTone): TonePalette {
         tint: colors.primarySubtle,
         accent: colors.primarySubtleForeground,
       };
+    case 'secondary':
+      return { fill: colors.secondary, fillForeground: colors.secondaryForeground, tint: colors.secondarySubtle, accent: colors.secondarySubtleForeground };
+    case 'tertiary':
+      return { fill: colors.tertiary, fillForeground: colors.tertiaryForeground, tint: colors.tertiarySubtle, accent: colors.tertiarySubtleForeground };
     case 'success':
       return {
         fill: colors.success,

package/src/theme/adaptive-colors.ts

@@ -103,8 +103,12 @@ function getAndroidColors(): AdaptiveColors | null {
       primaryDark: c(d.onPrimaryContainer),
       secondary: c(d.secondary),
       secondaryForeground: c(d.onSecondary),
+      secondarySubtle: c(d.secondaryContainer),
+      secondarySubtleForeground: c(d.onSecondaryContainer),
       tertiary: c(d.tertiary),
       tertiaryForeground: c(d.onTertiary),
+      tertiarySubtle: c(d.tertiaryContainer),
+      tertiarySubtleForeground: c(d.onTertiaryContainer),
       tint: c(d.primary),
       icon: c(d.onSurfaceVariant),
       iconActive: c(d.primary),
@@ -152,8 +156,14 @@ function getIOSColors(): AdaptiveColors | null {
       primaryDark: c(i.systemBlue),
       secondary: c(i.systemPurple),
       secondaryForeground: '#FFFFFF',
+      // iOS has no named accent container/on-container pair. Use its readable
+      // neutral container pair rather than inventing an alpha or on-color.
+      secondarySubtle: c(i.systemGray6),
+      secondarySubtleForeground: c(i.label),
       tertiary: c(i.systemTeal),
       tertiaryForeground: '#FFFFFF',
+      tertiarySubtle: c(i.systemGray6),
+      tertiarySubtleForeground: c(i.label),
       tint: c(i.systemBlue),
       icon: c(i.secondaryLabel),
       iconActive: c(i.systemBlue),

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

@@ -1,3 +1,4 @@
+import { chartColorsFromTokens } from './chart-colors';
 import { generateRoleColors, type RoleColors, type SchemeVariant } from './color-engine';
 import { buildSeedScopeVars } from './color-scope/seed-scope';
 import { STATUS_COLORS } from './build-theme';
@@ -29,13 +30,13 @@ export interface SeedAccents {
  * family (primarySubtle / negative / …) reads the engine's container/error roles
  * directly — identical to the preset path.
  */
-export function buildColorsFromSeed(
+function buildSeedThemeValues(
   seed: string,
   resolved: 'light' | 'dark',
   variant?: SchemeVariant,
   contrastLevel?: number,
   accents?: SeedAccents,
-): ThemeColors {
+): Pick<Theme, 'colors' | 'chartColors'> {
   const t = buildSeedScopeVars({
     seed,
     mode: resolved,
@@ -58,7 +59,7 @@ export function buildColorsFromSeed(
     tertiarySeed: accents?.tertiarySeed,
   });
 
-  return {
+  return { chartColors: chartColorsFromTokens(t), colors: {
     background: g('background'),
     backgroundSecondary: g('surface'),
     backgroundTertiary: g('popover'),
@@ -80,8 +81,12 @@ export function buildColorsFromSeed(
 
     secondary: g('secondary'),
     secondaryForeground: g('secondary-foreground'),
+    secondarySubtle: g('secondary-subtle'),
+    secondarySubtleForeground: g('secondary-text'),
     tertiary: g('tertiary'),
     tertiaryForeground: g('tertiary-foreground'),
+    tertiarySubtle: g('tertiary-subtle'),
+    tertiarySubtleForeground: g('tertiary-text'),
 
     tint: g('primary'),
     icon: g('muted-foreground'),
@@ -119,7 +124,18 @@ export function buildColorsFromSeed(
     card: g('card'),
     shadow: isDark ? 'rgba(0, 0, 0, 0.3)' : 'rgba(0, 0, 0, 0.1)',
     overlay: 'rgba(0, 0, 0, 0.5)',
-  };
+  } };
+}
+
+/** Resolve only the color roles for consumers that do not need the full theme. */
+export function buildColorsFromSeed(
+  seed: string,
+  resolved: 'light' | 'dark',
+  variant?: SchemeVariant,
+  contrastLevel?: number,
+  accents?: SeedAccents,
+): ThemeColors {
+  return buildSeedThemeValues(seed, resolved, variant, contrastLevel, accents).colors;
 }
 
 /**
@@ -136,7 +152,7 @@ export function buildThemeFromSeed(
 ): Theme {
   return {
     mode: resolved,
-    colors: buildColorsFromSeed(seed, resolved, variant, contrastLevel, accents),
+    ...buildSeedThemeValues(seed, resolved, variant, contrastLevel, accents),
     gradients: THEME_GRADIENTS,
     isDark: resolved === 'dark',
     isLight: resolved === 'light',

package/src/theme/build-theme.ts

@@ -1,3 +1,4 @@
+import { chartColorsFromTokens } from './chart-colors';
 import { Platform } from 'react-native';
 import { APP_COLOR_PRESETS, type AppColorName } from './color-presets';
 import { generateRoleColors, type RoleColors } from './color-engine';
@@ -5,7 +6,7 @@ import type { ExplicitAccents } from './preset-vars';
 import { getAdaptiveColors } from './adaptive-colors';
 import { getResolvedTokens } from './token-registry';
 import { THEME_GRADIENTS } from './gradients';
-import type { Theme, ThemeColors } from './types';
+import type { Theme } from './types';
 
 /**
  * Status colors used across the design system. Independent of the accent
@@ -34,7 +35,7 @@ function buildColorsFromPreset(
   preset: AppColorName,
   resolved: 'light' | 'dark',
   accents?: ExplicitAccents,
-): ThemeColors {
+): Pick<Theme, 'colors' | 'chartColors'> {
   const t = getResolvedTokens(preset, resolved, accents);
   const isDark = resolved === 'dark';
 
@@ -53,7 +54,7 @@ function buildColorsFromPreset(
     tertiarySeed: accents?.tertiaryHex ?? config.tertiaryHex,
   });
 
-  return {
+  return { chartColors: chartColorsFromTokens(t), colors: {
     background: g('background'),
     backgroundSecondary: g('surface'),
     backgroundTertiary: g('popover'),
@@ -91,8 +92,12 @@ function buildColorsFromPreset(
     // and tertiary completes primary/secondary/tertiary.
     secondary: g('secondary'),
     secondaryForeground: g('secondary-foreground'),
+    secondarySubtle: g('secondary-subtle'),
+    secondarySubtleForeground: g('secondary-text'),
     tertiary: g('tertiary'),
     tertiaryForeground: g('tertiary-foreground'),
+    tertiarySubtle: g('tertiary-subtle'),
+    tertiarySubtleForeground: g('tertiary-text'),
 
     tint: g('primary'),
     icon: g('muted-foreground'),
@@ -143,7 +148,7 @@ function buildColorsFromPreset(
     card: g('card'),
     shadow: isDark ? 'rgba(0, 0, 0, 0.3)' : 'rgba(0, 0, 0, 0.1)',
     overlay: 'rgba(0, 0, 0, 0.5)',
-  };
+  } };
 }
 
 /**
@@ -158,7 +163,7 @@ export function buildTheme(
   isAdaptive: boolean = false,
   accents?: ExplicitAccents,
 ): Theme {
-  const base = buildColorsFromPreset(preset, resolved, accents);
+  const { colors: base, chartColors } = buildColorsFromPreset(preset, resolved, accents);
   const adaptive = isAdaptive && Platform.OS !== 'web' ? getAdaptiveColors() : undefined;
   // The platform palette OVERLAYS the preset one rather than replacing it. Every
   // field the platform answers still wins, byte for byte; the tinted status
@@ -169,6 +174,7 @@ export function buildTheme(
   return {
     mode: resolved,
     colors,
+    chartColors,
     gradients: THEME_GRADIENTS,
     isDark: resolved === 'dark',
     isLight: resolved === 'light',

package/src/theme/chart-colors.ts

@@ -0,0 +1,40 @@
+import { Hct } from './color-engine/hct';
+import { TonalPalette } from './color-engine/tonal-palette';
+import { argbFromRgb, redFromArgb, greenFromArgb, blueFromArgb } from './color-engine/color-utils';
+import { parseRgba } from './color-utils';
+import type { Theme, ThemeChartColor } from './types';
+
+/** Keep the first five canonical series stable; interleave four extra hues. */
+const HUE_OFFSETS = [0, 72, 144, 216, 288, 36, 108, 180, 252] as const;
+const MONO_STEPS = [0, 1, 2, 3, 4, 0.5, 1.5, 2.5, 3.5] as const;
+const rgb = (argb: number) => `rgb(${redFromArgb(argb)} ${greenFromArgb(argb)} ${blueFromArgb(argb)})`;
+
+/** One categorical policy for CSS tokens, JS themes and custom-theme fallback. */
+export function createChartColors(hue: number, isDark: boolean, monochrome: boolean): readonly ThemeChartColor[] {
+  return HUE_OFFSETS.map((offset, index) => {
+    const palette = TonalPalette.fromHueAndChroma(monochrome ? 0 : (hue + offset) % 360, monochrome ? 0 : 60);
+    const tone = monochrome ? (isDark ? 40 + MONO_STEPS[index]! * 13 : 78 - MONO_STEPS[index]! * 13) : isDark ? 72 : 48;
+    // A uniform mono shift keeps every neighbouring step separated, including
+    // the lightest dark-mode series; clipping an +8 shift would crowd it.
+    const activeTone = tone + (isDark ? (monochrome ? 3 : 8) : -8);
+    return { color: rgb(palette.tone(tone)), activeColor: rgb(palette.tone(activeTone)) };
+  });
+}
+
+export function chartColorsFromTokens(tokens: Record<string, string>): readonly ThemeChartColor[] {
+  return HUE_OFFSETS.map((_, index) => {
+    const color = tokens[`--chart-${index + 1}`];
+    const activeColor = tokens[`--chart-${index + 1}-active`];
+    if (!color || !activeColor) throw new Error(`Missing canonical chart-${index + 1} pair`);
+    return { color, activeColor };
+  });
+}
+
+/** Hand-authored themes may omit the optional palette; use the same policy. */
+export function resolveThemeChartColors(theme: Theme): readonly ThemeChartColor[] {
+  if (theme.chartColors?.length === 9) return theme.chartColors;
+  const source = parseRgba(theme.colors.primary);
+  if (!source) return createChartColors(0, theme.isDark, true);
+  const seed = Hct.fromInt(argbFromRgb(source.r, source.g, source.b));
+  return createChartColors(seed.hue, theme.isDark, seed.chroma <= 6);
+}

package/src/theme/color-policy.ts

@@ -22,6 +22,7 @@
  * near-black one it must stay bright or it turns to mud. Every asymmetry below
  * is that rule applied to one more role.
  */
+import { createChartColors } from './chart-colors';
 import { argbFromHex, type RoleColors } from './color-engine';
 import { APP_COLOR_PRESETS, HEX_TO_APP_COLOR } from './color-presets';
 import { Hct } from './color-engine/hct';
@@ -169,7 +170,7 @@ const SUBTLE_SOURCE_TONE = 60;
 const SUBTLE_ALPHA = { light: 0.13, dark: 0.24 } as const;
 
 /**
- * The neutral surface ramp, owned here as TONES rather than taken from M3's
+ * The tonal surface ramp, owned here as TONES rather than taken from M3's
  * container roles.
  *
  * M3's container ramp steps by 2 tones, which at these lightnesses is ~1.2
@@ -177,14 +178,15 @@ const SUBTLE_ALPHA = { light: 0.13, dark: 0.24 } as const;
  * every rung of Bloom's surface stack was invisible against its neighbour, and
  * the thirteen components that carry meaning ONLY in the step between two
  * surfaces (a heatmap's empty cell, a filled card, a progress track, a hover
- * row, a skeleton) read as nothing at all. Measured across all 64 presets, 4
- * tones is ~2.4 ΔE00 and is the first spacing where every pair separates.
+ * row, a skeleton) read as nothing at all. In that historical low-chroma
+ * measurement across all 64 presets, 4 tones was ~2.4 ΔE00. The new chromatic
+ * palette preserves that tone spacing; its quantized neighbour gaps are tested
+ * directly rather than inheriting the old ΔE00 claim.
  *
- * `--background` is deliberately NOT in here: the page keeps the tone it
- * already had, so no consuming app inherits a new page colour. The rungs below
- * it move instead. `--card` is not here either — it sits on the far side of the
- * page in light (tone 100, white) and at the top of the ramp in dark, so it is
- * expressed as the engine role that means exactly that in each mode.
+ * Chromatic light cards stop at tone 98 so they retain the seed hue. The
+ * rest of that ladder moves down two tones with them, preserving four-tone
+ * separation. Monochrome keeps its original white-card ladder. Dark keeps
+ * the original page4 / surface10 / popover14 / muted18 / card22 spacing.
  *
  * Both members of each declared alias share a rung on purpose: `--sidebar` IS
  * `--surface` and `--accent` IS `--muted`, and splitting them here would invent
@@ -198,13 +200,8 @@ const SURFACE_RAMP = {
 /** Where the page itself sits. A touch off M3's own page background in both modes. */
 const BACKGROUND_TONE = { light: 96, dark: 4 } as const;
 
-/**
- * Large surfaces keep only a trace of the identity hue. At the old chroma 10 a
- * green or yellow seed washed the whole shell in a pastel cast; chroma 4 keeps
- * the family relationship visible without making neutral layout layers compete
- * with identity and action fills.
- */
-const NEUTRAL_CHROMA = 4;
+/** Seed-linked chroma for the whole shell, not merely its accent controls. */
+const NEUTRAL_CHROMA = 28;
 
 /**
  * A seed at or below this chroma has no colour to derive from, so the whole
@@ -474,11 +471,18 @@ export function buildPolicyTokens(
       : brandTone(brandPalette, isDark, declaresWhiteLabel(seedHex)),
   );
 
-  // The palette every neutral surface is cut from — the same one the `vivid`
-  // scheme builds its neutrals from, so a policy-owned tone and an engine role
-  // at that tone are the same colour rather than two near-misses.
+  // Surfaces, text and boundaries share the identity hue and tonal authority.
   const neutral = TonalPalette.fromHueAndChroma(seed.hue, monochrome ? 0 : NEUTRAL_CHROMA);
-  const rampTones = isDark ? SURFACE_RAMP.dark : SURFACE_RAMP.light;
+  const originalRamp = isDark ? SURFACE_RAMP.dark : SURFACE_RAMP.light;
+  const lightShift = !isDark && !monochrome ? -2 : 0;
+  const rampTones = {
+    surface: originalRamp.surface + lightShift,
+    popover: originalRamp.popover + lightShift,
+    muted: originalRamp.muted + lightShift,
+  };
+  const foreground = rgb(neutral.tone(isDark ? 94 : 10));
+  const mutedForeground = rgb(neutral.tone(isDark ? 80 : 30));
+  const boundary = rgb(neutral.tone(isDark ? 35 : 72));
 
   const tokens: PolicyTokens = {
     '--primary': primary.fill,
@@ -491,23 +495,20 @@ export function buildPolicyTokens(
       isDark ? SUBTLE_ALPHA.dark : SUBTLE_ALPHA.light,
     ),
     '--ring': roles.primary,
-    // `--card` lifts OFF the page, and which direction that is flips with the
-    // mode: in light it is white, brighter than everything; in dark it is the
-    // top of the container ramp, M3's own filled-card role.
-    //
-    // Neither end is free. `surfaceContainerLowest` in dark is tone 4, which is
-    // exactly where `--background` sits below, so a card would be byte-identical
-    // to the page — and `surfaceContainer` in dark is `--popover`'s role
-    // (`preset-vars.ts`), which is what it WAS: every card, sheet and chat
-    // bubble rendering the same colour as every menu, in every preset.
-    '--card': isDark ? roles.surfaceContainerHighest : roles.surfaceContainerLowest,
-    // The page. A touch darker than M3's page background, which stays
-    // `--content-area`: near-white reads as unfinished next to the card.
-    //
-    // This tone is the one thing the ramp holds still — it is every consuming
-    // app's page colour. It sits ON `surfaceContainerLow`'s tone, which is why
-    // `--surface` no longer comes from that role.
-    '--background': rgb(neutral.tone(isDark ? BACKGROUND_TONE.dark : BACKGROUND_TONE.light)),
+    '--card': monochrome
+      ? (isDark ? roles.surfaceContainerHighest : roles.surfaceContainerLowest)
+      : rgb(neutral.tone(isDark ? 22 : 98)),
+    '--background': rgb(neutral.tone((isDark ? BACKGROUND_TONE.dark : BACKGROUND_TONE.light) + lightShift)),
+    '--content-area': monochrome ? roles.background : rgb(neutral.tone(isDark ? 6 : 96)),
+    '--foreground': monochrome ? roles.onBackground : foreground,
+    '--surface-foreground': monochrome ? roles.onSurface : foreground,
+    '--card-foreground': monochrome ? roles.onSurface : foreground,
+    '--popover-foreground': monochrome ? roles.onSurface : foreground,
+    '--sidebar-foreground': monochrome ? roles.onSurface : foreground,
+    '--muted-foreground': monochrome ? roles.onSurfaceVariant : mutedForeground,
+    '--border': monochrome ? roles.outlineVariant : boundary,
+    '--input': monochrome ? roles.outlineVariant : boundary,
+    '--sidebar-border': monochrome ? roles.outlineVariant : boundary,
     // The rungs below the page, spaced far enough apart to be seen. These
     // override the M3 container roles `preset-vars.ts` maps them to; see
     // `SURFACE_RAMP` for why the roles themselves cannot be used.
@@ -517,7 +518,9 @@ export function buildPolicyTokens(
     '--muted': rgb(neutral.tone(rampTones.muted)),
     // `--accent` stays what every consumer actually uses it for: a hover surface.
     '--accent': rgb(neutral.tone(rampTones.muted)),
-    '--accent-foreground': roles.onSurfaceVariant,
+    '--accent-foreground': monochrome ? roles.onSurfaceVariant : mutedForeground,
+    '--sidebar-accent': monochrome ? roles.secondaryContainer : rgb(neutral.tone(rampTones.muted)),
+    '--sidebar-accent-foreground': monochrome ? roles.onSecondaryContainer : mutedForeground,
   };
 
   const hues = accentHues(seed.hue);
@@ -597,15 +600,12 @@ export function buildPolicyTokens(
     );
   }
 
-  // Categorical chart ramp: five hues spread evenly from the seed at one tone.
-  // 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) {
-    // 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));
-  }
+  // CSS and component palettes share all nine categorical fill/active pairs.
+  // Existing chart-1…5 fills remain byte-for-byte stable.
+  createChartColors(seed.hue, isDark, monochrome).forEach((pair, index) => {
+    tokens[`--chart-${index + 1}`] = pair.color;
+    tokens[`--chart-${index + 1}-active`] = pair.activeColor;
+  });
 
   // The status family, themed per mode. The four frozen hexes it replaces all
   // FAIL AA under white text — warning at 2.15, success 2.54, info 3.68, error