@motion-proto/live-tokens 0.43.0 → 0.45.0

package/src/editor/ui/colors/paletteBaseColor.ts

@@ -21,8 +21,6 @@ import { get } from 'svelte/store';
 import type { Oklch } from '../../core/palettes/oklch';
 import { AXIS_ROLES } from '../../core/palettes/colorHarmony';
 import { PALETTE_SPECS, syncBaseAnchor, type PaletteSpec } from '../../core/palettes/paletteDerivation';
-import { solveTextCurves } from '../../core/palettes/solveTextContrast';
-import { recommendNeutralText } from '../../core/palettes/recommendText';
 import { defaultPaletteConfig } from '../palette/paletteMath';
 import { mutate, transaction, editorState } from '../../core/store/editorStore';
 import type { EditorState } from '../../core/store/editorTypes';
@@ -193,22 +191,14 @@ export function setBaseColors(patch: Record<string, Oklch>, historyLabel = 'colo
   });
 }
 
-export function applySolvedTextCurves(s: EditorState): void {
-  const { patches } = solveTextCurves(s.palettes);
-  for (const [label, patch] of Object.entries(patches)) {
-    const cfg = s.palettes[label];
-    if (cfg) cfg.scaleCurves = { ...cfg.scaleCurves, ...patch.scaleCurves };
+/** Read-only view of every family's config, seeding spec defaults for the ones a
+ *  loaded theme leaves unconfigured — previews and recommendations must not go
+ *  static on a family the theme never mentions. */
+export function palettesWithDefaults(palettes: Record<string, PaletteConfig>): Record<string, PaletteConfig> {
+  const map: Record<string, PaletteConfig> = {};
+  for (const spec of PALETTE_SPECS) {
+    map[spec.label] =
+      palettes[spec.label] ?? defaultPaletteConfig({ baseColor: spec.initialColor, neutral: spec.neutral ?? false });
   }
-}
-
-/** Apply the Color Story's suggested neutral text hierarchy (primary anchor,
- *  two even L drops, AA floors) as the Neutral family's Text curve. */
-export function applySuggestedNeutralText(useBlackWhite = false): void {
-  mutate('colors: suggested text hierarchy', (s) => {
-    ensureConfig(s, 'Neutral');
-    const rec = recommendNeutralText(s.palettes, undefined, useBlackWhite);
-    if (!rec.patch) return;
-    const cfg = s.palettes['Neutral'];
-    cfg.scaleCurves = { ...cfg.scaleCurves, Text: rec.patch };
-  });
+  return map;
 }

package/src/editor/core/palettes/recommendText.ts

@@ -1,216 +0,0 @@
-// Suggested neutral text hierarchy for the Color Story.
-//
-// The solver (`solveTextContrast`) optimizes floors: it pushes every step to
-// the minimum L that clears its ratio, which can collapse secondary and
-// tertiary onto nearly the same value. This module instead anchors on the
-// user's current primary and derives secondary/tertiary as two even OKLCH-L
-// drops toward the background — hierarchy first, with WCAG AA (4.5) as a floor
-// rather than the driver. The floor is solved against the adverse extreme of
-// the neutral surface band so a compliant suggestion holds AA on EVERY band
-// surface (broadest reach); when the seed's reachable-L window can't span the
-// band, it falls back to the default surface and the coverage report says so.
-// Coverage is informational — callers alert on partial reach, never block.
-
-import { gamutClamp, oklchToHexClamped } from './oklch';
-import {
-  palettesToValues,
-  defaultScaleCurves,
-  BW_GUARD_MIN_L,
-  BW_GUARD_MAX_L,
-  type DerivedValue,
-  type SchemeDirection,
-} from './paletteDerivation';
-
-export { BW_GUARD_MIN_L, BW_GUARD_MAX_L };
-import { NEUTRAL_BAND } from './solveTextContrast';
-import { findLForContrast, contrastRatio, AA_BODY } from './contrast';
-import { sampleCurve, makeAnchor, type CurveAnchor } from '../../ui/curveEngine';
-import type { PaletteConfig } from '../themes/themeTypes';
-
-/** One even hierarchy drop in OKLCH L. Two drops span primary → tertiary. */
-export const SUGGESTED_STEP_DROP = 0.07;
-
-/** L difference below which current and suggested count as the same value. */
-const DIFF_EPS = 0.01;
-
-export interface SurfaceCheck {
-  var: string;
-  ratio: number;
-  meets: boolean;
-}
-
-export interface Coverage {
-  cleared: number;
-  total: number;
-  full: boolean;
-  /** Most adverse band surface met with every less-adverse one also met;
-   *  null when even the least adverse surface fails. */
-  reachVar: string | null;
-  /** Adversity-ascending (least adverse band surface first). */
-  checks: SurfaceCheck[];
-}
-
-export interface TextSuggestion {
-  step: 'primary' | 'secondary' | 'tertiary';
-  textVar: string;
-  current: { hex: string; l: number; coverage: Coverage };
-  suggested: { hex: string; l: number; c: number; coverage: Coverage };
-  differs: boolean;
-}
-
-export interface NeutralTextRecommendation {
-  scheme: SchemeDirection;
-  suggestions: TextSuggestion[];
-  anyDiffers: boolean;
-  /** Neutral Text-scale curve patch reproducing the suggested Ls at x=0/25/50
-   *  and pinning current muted/disabled at x=75/100. Null when nothing differs. */
-  patch: { lightness: CurveAnchor[]; saturation: CurveAnchor[] } | null;
-}
-
-const STEPS: { step: TextSuggestion['step']; x: number; textVar: string }[] = [
-  { step: 'primary', x: 0, textVar: '--text-primary' },
-  { step: 'secondary', x: 25, textVar: '--text-secondary' },
-  { step: 'tertiary', x: 50, textVar: '--text-tertiary' },
-];
-
-function colorL(v: DerivedValue | undefined): number | null {
-  return v?.kind === 'color' ? v.l : null;
-}
-
-export function recommendNeutralText(
-  palettes: Record<string, PaletteConfig>,
-  scheme?: SchemeDirection,
-  useBlackWhite = false,
-): NeutralTextRecommendation {
-  const neutral = palettes['Neutral']!;
-  const values = palettesToValues(palettes);
-
-  const pageBgL = colorL(values['--page-bg']) ?? colorL(values['--surface-neutral'])!;
-  const resolvedScheme: SchemeDirection = scheme ?? (pageBgL >= 0.5 ? 'light' : 'dark');
-  const direction: 'lighter' | 'darker' = resolvedScheme === 'light' ? 'darker' : 'lighter';
-  // Toward more contrast: +L for light text on dark surfaces, −L for dark text.
-  const sign = direction === 'lighter' ? 1 : -1;
-
-  const band = NEUTRAL_BAND
-    .map((v) => {
-      const value = values[v];
-      return value?.kind === 'color'
-        ? { var: v, l: value.l, hex: oklchToHexClamped(value.l, value.c, value.h) }
-        : null;
-    })
-    .filter((s): s is { var: string; l: number; hex: string } => s !== null)
-    .sort((a, b) => (a.l - b.l) * sign);
-  const bandAdverse = band[band.length - 1];
-  const surfaceDefaultHex = band.find((s) => s.var === '--surface-neutral')!.hex;
-
-  const seed = neutral.baseColor;
-  const seedL = Math.max(seed.l, 1e-4);
-  const baseC = Math.max(seed.c, 1e-9);
-  const baseH = seed.h;
-  const lMax = Math.min(1, 2 * seedL);
-
-  const curveOffset = neutral.curveOffset ?? {};
-  const lOff = curveOffset['Text-lightness'] ?? 0;
-  const sOff = curveOffset['Text-saturation'] ?? 0;
-  const satCurve = neutral.scaleCurves?.Text?.saturation ?? defaultScaleCurves.Text.saturation();
-
-  const stepChroma = (x: number): number =>
-    baseC * Math.max(0, Math.min(2, (sampleCurve(satCurve, x) + sOff) / 100));
-
-  function coverage(hex: string): Coverage {
-    const checks: SurfaceCheck[] = band.map((s) => {
-      const ratio = contrastRatio(hex, s.hex);
-      return { var: s.var, ratio, meets: ratio >= AA_BODY };
-    });
-    let reachVar: string | null = null;
-    for (const c of checks) {
-      if (!c.meets) break;
-      reachVar = c.var;
-    }
-    const cleared = checks.filter((c) => c.meets).length;
-    return { cleared, total: checks.length, full: cleared === checks.length, reachVar, checks };
-  }
-
-  // AA floors. Primary carries the broadest-reach preference: it floors
-  // against the band's adverse extreme so body text holds AA on every band
-  // surface the window can span (fallback: default surface, surfaced as
-  // partial coverage). Secondary/tertiary floor against the default surface —
-  // flooring THEM at the band extreme too would collapse the whole hierarchy
-  // onto near-white whenever the lightest band surface is a mid-tone.
-  const solveFloor = (against: string, c: number) =>
-    findLForContrast({ against, ratio: AA_BODY, direction, c, h: baseH, lMin: 0, lMax });
-
-  let primaryFloor = solveFloor(bandAdverse.hex, stepChroma(0));
-  if (contrastRatio(primaryFloor.hex, bandAdverse.hex) < AA_BODY) {
-    primaryFloor = solveFloor(surfaceDefaultHex, stepChroma(0));
-  }
-  const stepFloor = solveFloor(surfaceDefaultHex, stepChroma(50));
-
-  const towardContrast = (a: number, b: number): number => (sign > 0 ? Math.max(a, b) : Math.min(a, b));
-  const clampWindow = (l: number): number => Math.max(0, Math.min(lMax, l));
-
-  const currentL: Record<string, number> = {};
-  for (const s of STEPS) currentL[s.step] = colorL(values[s.textVar]) ?? seedL;
-
-  // Pure black/white is an affirmative choice (most designers find it too
-  // stark): opted in, primary anchors at the scheme extreme; otherwise the
-  // anchor is pulled inside the guard band, yielding only to the AA floor.
-  let primaryL: number;
-  if (useBlackWhite) {
-    primaryL = clampWindow(sign > 0 ? lMax : 0);
-  } else {
-    const guard = sign > 0
-      ? Math.max(BW_GUARD_MAX_L, primaryFloor.l)
-      : Math.min(BW_GUARD_MIN_L, primaryFloor.l);
-    const anchored = clampWindow(towardContrast(currentL.primary, primaryFloor.l));
-    primaryL = sign > 0 ? Math.min(anchored, guard) : Math.max(anchored, guard);
-  }
-  const tertiaryL = towardContrast(stepFloor.l, primaryL - sign * 2 * SUGGESTED_STEP_DROP);
-  const suggestedL: Record<string, number> = {
-    primary: primaryL,
-    secondary: towardContrast(stepFloor.l, (primaryL + tertiaryL) / 2),
-    tertiary: tertiaryL,
-  };
-
-  const suggestions: TextSuggestion[] = STEPS.map((s) => {
-    const currentValue = values[s.textVar];
-    const currentHex = currentValue?.kind === 'color'
-      ? oklchToHexClamped(currentValue.l, currentValue.c, currentValue.h)
-      : oklchToHexClamped(seedL, 0, 0);
-    const g = gamutClamp(suggestedL[s.step], stepChroma(s.x), baseH);
-    const hex = oklchToHexClamped(g.l, g.c, g.h);
-    return {
-      step: s.step,
-      textVar: s.textVar,
-      current: { hex: currentHex, l: currentL[s.step], coverage: coverage(currentHex) },
-      suggested: { hex, l: g.l, c: g.c, coverage: coverage(hex) },
-      differs: Math.abs(g.l - currentL[s.step]) > DIFF_EPS,
-    };
-  });
-
-  const anyDiffers = suggestions.some((s) => s.differs);
-
-  let patch: NeutralTextRecommendation['patch'] = null;
-  if (anyDiffers) {
-    const clampY = (v: number) => Math.max(0, Math.min(200, v));
-    const lightAnchors: CurveAnchor[] = [];
-    const satAnchors: CurveAnchor[] = [];
-    for (const s of suggestions) {
-      const x = STEPS.find((st) => st.step === s.step)!.x;
-      lightAnchors.push(makeAnchor(x, clampY((100 * s.suggested.l) / seedL - lOff)));
-      satAnchors.push(makeAnchor(x, clampY((100 * s.suggested.c) / baseC - sOff)));
-    }
-    // Pin muted/disabled at their current derived values so applying the
-    // suggestion never moves the steps it doesn't own.
-    for (const [x, textVar] of [[75, '--text-muted'], [100, '--text-disabled']] as const) {
-      const v = values[textVar];
-      const l = v?.kind === 'color' ? v.l : seedL;
-      const c = v?.kind === 'color' ? v.c : 0;
-      lightAnchors.push(makeAnchor(x, clampY((100 * l) / seedL - lOff)));
-      satAnchors.push(makeAnchor(x, clampY((100 * c) / baseC - sOff)));
-    }
-    patch = { lightness: lightAnchors, saturation: satAnchors };
-  }
-
-  return { scheme: resolvedScheme, suggestions, anyDiffers, patch };
-}

package/src/editor/core/palettes/solveTextContrast.ts

@@ -1,251 +0,0 @@
-// "Derive accessible text": solve each family's Text lightness curve so the
-// derived text colors clear WCAG AA against the surfaces they sit on.
-//
-// The Text scale derives L as seedL × (curveSample/100), clamped to [0,2], so a
-// family can only reach L ∈ [0, min(1, 2·seedL)]. The solver works inside that
-// window (passed as `lMax`) and emits a 5-anchor lightness curve whose sample
-// at each step x reproduces the solved L; a companion saturation curve pins the
-// solved (possibly chroma-decayed) chroma so the round-trip is exact. Surface
-// and page colors come from the real `palettesToValues` derivation (numeric
-// OKLCH); the solver converts to hex only at its own sRGB (WCAG) boundary.
-
-import { oklchToHexClamped } from './oklch';
-import {
-  palettesToValues,
-  serializeDerivedValue,
-  PALETTE_SPECS,
-  scaleToCssVar,
-  defaultScaleCurves,
-  type DerivedValue,
-  type SchemeDirection,
-} from './paletteDerivation';
-import { findLForContrast, contrastRatio } from './contrast';
-import { sampleCurve, makeAnchor, type CurveAnchor } from '../../ui/curveEngine';
-import type { PaletteConfig } from '../themes/themeTypes';
-
-export interface ContrastPairing {
-  family: string;
-  step: string;
-  textVar: string;
-  againstVar: string;
-  targetRatio: number;
-  achievedRatio: number;
-  meets: boolean;
-  /** True when this pairing carries an AA guarantee (vs. a deliberately graded,
-   *  non-AA step like `muted`/`disabled` on chromatic families). */
-  guaranteed: boolean;
-}
-
-export interface TextSolveResult {
-  patches: Record<string, Pick<PaletteConfig, 'scaleCurves'>>;
-  report: ContrastPairing[];
-}
-
-const TEXT_STEPS: { name: string; x: number }[] = [
-  { name: 'primary', x: 0 },
-  { name: 'secondary', x: 25 },
-  { name: 'tertiary', x: 50 },
-  { name: 'muted', x: 75 },
-  { name: 'disabled', x: 100 },
-];
-
-export const NEUTRAL_BAND = [
-  '--surface-neutral-lowest', '--surface-neutral-lower', '--surface-neutral-low',
-  '--surface-neutral', '--surface-neutral-high', '--surface-neutral-higher',
-  '--surface-neutral-highest',
-];
-
-interface StepPlan {
-  ratio: number;
-  guaranteed: boolean;
-  /** 'band' = adverse extreme of the neutral surface band; 'default' = surface
-   *  default; 'worst' = adverse of {surface default, page bg}. */
-  target: 'band' | 'default' | 'worst';
-}
-
-// Neutral family sits on neutral surfaces; primary/secondary must clear the
-// adverse band extreme, tertiary/muted the default surface. Disabled is graded.
-const NEUTRAL_PLAN: Record<string, StepPlan> = {
-  primary:   { ratio: 7.0, guaranteed: true,  target: 'band' },
-  secondary: { ratio: 4.5, guaranteed: true,  target: 'band' },
-  tertiary:  { ratio: 4.5, guaranteed: true,  target: 'default' },
-  muted:     { ratio: 3.0, guaranteed: true,  target: 'default' },
-  disabled:  { ratio: 2.0, guaranteed: false, target: 'default' },
-};
-
-// Chromatic families: primary must clear the worse of surface-default / page-bg
-// (chroma decay allowed), secondary the default surface; the rest grade toward
-// the surface (non-AA).
-const CHROMATIC_PLAN: Record<string, StepPlan> = {
-  primary:   { ratio: 4.5, guaranteed: true,  target: 'worst' },
-  secondary: { ratio: 4.5, guaranteed: true,  target: 'default' },
-  tertiary:  { ratio: 3.0, guaranteed: false, target: 'default' },
-  muted:     { ratio: 2.2, guaranteed: false, target: 'default' },
-  disabled:  { ratio: 1.6, guaranteed: false, target: 'default' },
-};
-
-interface Surface {
-  var: string;
-  l: number;
-  c: number;
-  h: number;
-}
-
-function colorSurface(varName: string, value: DerivedValue | undefined): Surface | null {
-  return value?.kind === 'color' ? { var: varName, l: value.l, c: value.c, h: value.h } : null;
-}
-
-// The solver terminates in sRGB (WCAG luminance is sRGB-defined); convert the
-// numeric surface to hex only at this boundary. Clamp so contrast math sees the
-// same chroma-reduced projection the CSS ships (unclamped override surfaces).
-function surfaceHex(s: Surface): string {
-  return oklchToHexClamped(s.l, s.c, s.h);
-}
-
-// The hardest surface to clear: for lighter text the highest-luminance surface,
-// for darker text the lowest.
-function pickAdverse(surfaces: Surface[], direction: 'lighter' | 'darker'): Surface {
-  let best = surfaces[0];
-  let bestL = best.l;
-  for (const s of surfaces.slice(1)) {
-    if (direction === 'lighter' ? s.l > bestL : s.l < bestL) {
-      best = s;
-      bestL = s.l;
-    }
-  }
-  return best;
-}
-
-export function solveTextCurves(
-  palettes: Record<string, PaletteConfig>,
-  scheme?: SchemeDirection,
-): TextSolveResult {
-  const values = palettesToValues(palettes);
-  const surfaceDefault = colorSurface('--surface-neutral', values['--surface-neutral'])!;
-  const rawPageBg = values['--page-bg'];
-  const pageBg: Surface = rawPageBg?.kind === 'color'
-    ? colorSurface('--page-bg', rawPageBg)!
-    : surfaceDefault;
-  const band: Surface[] = NEUTRAL_BAND
-    .map((v) => colorSurface(v, values[v]))
-    .filter((s): s is Surface => s !== null);
-
-  const resolvedScheme: SchemeDirection =
-    scheme ?? (pageBg.l >= 0.5 ? 'light' : 'dark');
-  const direction: 'lighter' | 'darker' = resolvedScheme === 'light' ? 'darker' : 'lighter';
-
-  const bandAdverse = pickAdverse(band, direction);
-  const worstAdverse = pickAdverse([surfaceDefault, pageBg], direction);
-
-  const patches: Record<string, Pick<PaletteConfig, 'scaleCurves'>> = {};
-  const report: ContrastPairing[] = [];
-
-  for (const spec of PALETTE_SPECS) {
-    const config = palettes[spec.label];
-    if (!config) continue;
-
-    const seed = config.baseColor;
-    const seedL = Math.max(seed.l, 1e-4);
-    const baseC = Math.max(seed.c, 1e-9);
-    const baseH = seed.h;
-    const lMax = Math.min(1, 2 * seedL);
-
-    const curveOffset = config.curveOffset ?? {};
-    const lOff = curveOffset['Text-lightness'] ?? 0;
-    const sOff = curveOffset['Text-saturation'] ?? 0;
-    const satCurve = config.scaleCurves?.Text?.saturation ?? defaultScaleCurves.Text.saturation();
-
-    const isNeutral = spec.label === 'Neutral';
-    const plan = isNeutral ? NEUTRAL_PLAN : CHROMATIC_PLAN;
-
-    const lightAnchors: CurveAnchor[] = [];
-    const satAnchors: CurveAnchor[] = [];
-
-    for (const step of TEXT_STEPS) {
-      const stepPlan = plan[step.name];
-      const against =
-        stepPlan.target === 'band' ? bandAdverse :
-        stepPlan.target === 'worst' ? worstAdverse : surfaceDefault;
-
-      const origSatMul = Math.max(0, Math.min(2, (sampleCurve(satCurve, step.x) + sOff) / 100));
-      const stepChroma = baseC * origSatMul;
-
-      const solved = findLForContrast({
-        against: surfaceHex(against),
-        ratio: stepPlan.ratio,
-        direction,
-        c: stepChroma,
-        h: baseH,
-        lMin: 0,
-        lMax,
-      });
-
-      const lightY = clamp(0, 200, (100 * solved.l) / seedL - lOff);
-      const satY = clamp(0, 200, (100 * solved.c) / baseC - sOff);
-      lightAnchors.push(makeAnchor(step.x, lightY));
-      satAnchors.push(makeAnchor(step.x, satY));
-    }
-
-    patches[spec.label] = {
-      scaleCurves: { Text: { lightness: lightAnchors, saturation: satAnchors } },
-    };
-  }
-
-  // Report against the actually-derived text hexes (post-round-trip verification
-  // at the solver level, mirroring Global invariant 8).
-  const derivedValues = palettesToValues(applyPatches(palettes, patches));
-  for (const spec of PALETTE_SPECS) {
-    if (!patches[spec.label]) continue;
-    const isNeutral = spec.label === 'Neutral';
-    const plan = isNeutral ? NEUTRAL_PLAN : CHROMATIC_PLAN;
-    for (const step of TEXT_STEPS) {
-      const stepPlan = plan[step.name];
-      const textVar = scaleToCssVar('Text', step.name, spec.cssNamespace);
-      if (!textVar) continue;
-      const against =
-        stepPlan.target === 'band' ? bandAdverse :
-        stepPlan.target === 'worst' ? worstAdverse : surfaceDefault;
-      const textValue = derivedValues[textVar];
-      const againstValue = derivedValues[against.var];
-      const againstHex = againstValue?.kind === 'color' ? serializeDerivedValue(againstValue) : surfaceHex(against);
-      const achieved = textValue?.kind === 'color' ? contrastRatio(serializeDerivedValue(textValue), againstHex) : 1;
-      report.push({
-        family: spec.label,
-        step: step.name,
-        textVar,
-        againstVar: against.var,
-        targetRatio: stepPlan.ratio,
-        achievedRatio: achieved,
-        meets: achieved >= minGuarantee(step.name, stepPlan),
-        guaranteed: stepPlan.guaranteed,
-      });
-    }
-  }
-
-  return { patches, report };
-}
-
-// The AA floor a guaranteed step must clear (primary/secondary/tertiary = body
-// 4.5; neutral muted = large 3.0). Graded steps floor at 1 (informational).
-function minGuarantee(stepName: string, plan: StepPlan): number {
-  if (!plan.guaranteed) return 1;
-  return stepName === 'muted' ? 3.0 : 4.5;
-}
-
-function clamp(lo: number, hi: number, v: number): number {
-  return Math.max(lo, Math.min(hi, v));
-}
-
-function applyPatches(
-  palettes: Record<string, PaletteConfig>,
-  patches: Record<string, Pick<PaletteConfig, 'scaleCurves'>>,
-): Record<string, PaletteConfig> {
-  const out: Record<string, PaletteConfig> = {};
-  for (const [label, config] of Object.entries(palettes)) {
-    const patch = patches[label];
-    out[label] = patch
-      ? { ...config, scaleCurves: { ...config.scaleCurves, ...patch.scaleCurves } }
-      : config;
-  }
-  return out;
-}