@motion-proto/live-tokens 0.40.0 → 0.41.0

package/src/app/site.css

@@ -10,58 +10,67 @@
  */
 
 h1 {
-  font-family: var(--font-display);
-  font-size: var(--font-size-4xl);
-  font-weight: var(--font-weight-semibold);
+  font-family: var(--heading-xl-font-family);
+  font-size: var(--heading-xl-font-size);
+  font-weight: var(--heading-xl-font-weight);
+  line-height: var(--heading-xl-line-height);
+  letter-spacing: var(--heading-xl-letter-spacing);
   color: var(--text-primary);
   margin: 0 0 var(--space-12);
-  line-height: var(--line-height-sm);
   overflow-wrap: break-word;
 }
 
 h2 {
-  font-family: var(--font-serif);
-  font-size: var(--font-size-2xl);
-  font-weight: var(--font-weight-semibold);
+  font-family: var(--heading-lg-font-family);
+  font-size: var(--heading-lg-font-size);
+  font-weight: var(--heading-lg-font-weight);
+  line-height: var(--heading-lg-line-height);
+  letter-spacing: var(--heading-lg-letter-spacing);
   color: var(--text-primary);
-  letter-spacing: var(--letter-spacing-normal);
   margin: var(--space-32) 0 var(--space-12);
-  line-height: var(--line-height-sm);
   overflow-wrap: break-word;
 }
 
 h3 {
-  font-family: var(--font-serif);
-  font-size: var(--font-size-xl);
-  font-weight: var(--font-weight-normal);
+  font-family: var(--heading-md-font-family);
+  font-size: var(--heading-md-font-size);
+  font-weight: var(--heading-md-font-weight);
+  line-height: var(--heading-md-line-height);
+  letter-spacing: var(--heading-md-letter-spacing);
   color: var(--text-primary);
   margin: var(--space-24) 0 var(--space-8);
-  line-height: var(--line-height-sm);
   overflow-wrap: break-word;
 }
 
+h4 {
+  font-family: var(--heading-sm-font-family);
+  font-size: var(--heading-sm-font-size);
+  font-weight: var(--heading-sm-font-weight);
+  line-height: var(--heading-sm-line-height);
+  letter-spacing: var(--heading-sm-letter-spacing);
+  color: var(--text-primary);
+  margin: var(--space-16) 0 var(--space-4);
+}
+
 @media (max-width: 768px) {
   h1 {
-    line-height: 1.1;
     margin-bottom: var(--space-8);
   }
 
   h2 {
-    line-height: 1.15;
     margin-top: var(--space-24);
   }
 
   h3 {
-    line-height: 1.2;
     margin-top: var(--space-20);
   }
 }
 
 p {
-  font-family: var(--font-serif);
-  font-size: var(--font-size-md);
+  font-family: var(--body-md-font-family);
+  font-size: var(--body-md-font-size);
   color: var(--text-secondary);
-  line-height: var(--line-height-md);
+  line-height: var(--body-md-line-height);
   margin: 0 0 14px;
 }
 
@@ -69,6 +78,17 @@ p:last-child {
   margin-bottom: 0;
 }
 
+code {
+  font-family: var(--code-font-family);
+  font-size: var(--code-font-size);
+}
+
+pre {
+  font-family: var(--code-font-family);
+  font-size: var(--code-font-size);
+  line-height: var(--code-line-height);
+}
+
 a {
   color: var(--text-brand);
   text-decoration: none;
@@ -94,7 +114,7 @@ ul li {
   font-family: var(--font-serif);
   font-size: var(--font-size-md);
   color: var(--text-secondary);
-  line-height: 1.75;
+  line-height: var(--line-height-relaxed);
   margin-bottom: var(--space-4);
 }
 
@@ -136,3 +156,60 @@ blockquote {
   color: var(--text-secondary);
   font-style: italic;
 }
+
+.heading-xl {
+  font-family: var(--heading-xl-font-family);
+  font-size: var(--heading-xl-font-size);
+  font-weight: var(--heading-xl-font-weight);
+  line-height: var(--heading-xl-line-height);
+  letter-spacing: var(--heading-xl-letter-spacing);
+}
+
+.heading-lg {
+  font-family: var(--heading-lg-font-family);
+  font-size: var(--heading-lg-font-size);
+  font-weight: var(--heading-lg-font-weight);
+  line-height: var(--heading-lg-line-height);
+  letter-spacing: var(--heading-lg-letter-spacing);
+}
+
+.heading-md {
+  font-family: var(--heading-md-font-family);
+  font-size: var(--heading-md-font-size);
+  font-weight: var(--heading-md-font-weight);
+  line-height: var(--heading-md-line-height);
+  letter-spacing: var(--heading-md-letter-spacing);
+}
+
+.heading-sm {
+  font-family: var(--heading-sm-font-family);
+  font-size: var(--heading-sm-font-size);
+  font-weight: var(--heading-sm-font-weight);
+  line-height: var(--heading-sm-line-height);
+  letter-spacing: var(--heading-sm-letter-spacing);
+}
+
+.body-md {
+  font-family: var(--body-md-font-family);
+  font-size: var(--body-md-font-size);
+  font-weight: var(--body-md-font-weight);
+  line-height: var(--body-md-line-height);
+  letter-spacing: var(--body-md-letter-spacing);
+}
+
+.body-sm {
+  font-family: var(--body-sm-font-family);
+  font-size: var(--body-sm-font-size);
+  font-weight: var(--body-sm-font-weight);
+  line-height: var(--body-sm-line-height);
+  letter-spacing: var(--body-sm-letter-spacing);
+}
+
+.eyebrow {
+  font-family: var(--eyebrow-font-family);
+  font-size: var(--eyebrow-font-size);
+  font-weight: var(--eyebrow-font-weight);
+  line-height: var(--eyebrow-line-height);
+  letter-spacing: var(--eyebrow-letter-spacing);
+  text-transform: var(--eyebrow-text-transform);
+}

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

@@ -0,0 +1,228 @@
+// Harmony rotates HUE ONLY (Global invariant 6). Each palette keeps its own
+// OKLCH chroma and lightness; only a family's hue moves onto a geometric
+// relationship with the anchor. The anchor is axis 0's stored hue: harmony lives
+// on four fixed axes (Anchor/Secondary/Tertiary/Quaternary), each owning a hue
+// whether or not a color family is bound to it. No chroma clamp or cap lives
+// here; a saturated background is a legitimate choice, not something to correct.
+
+import type { Oklch } from './oklch';
+import type { PaletteConfig } from '../themes/themeTypes';
+import { PALETTE_SPECS } from './paletteDerivation';
+
+export type HarmonyMode =
+  | 'complementary'
+  | 'split-complementary'
+  | 'triadic'
+  | 'tetradic'
+  | 'compound'
+  | 'square'
+  | 'analogous'
+  | 'monochromatic'
+  | 'custom';
+
+/** Families the user may order/include on the harmony axes (dev-declared pool). */
+export const HARMONY_ELIGIBLE: readonly string[] = ['Brand', 'Accent', 'Background', 'Special', 'Neutral', 'Alternate'];
+
+export const AXIS_COUNT = 4;
+export const AXIS_ROLES = ['Anchor', 'Secondary', 'Tertiary', 'Quaternary'] as const;
+
+export interface HarmonyAxis {
+  /** Hue in [0, 360). Always present, bound or not. */
+  hue: number;
+  /** Bound family label (member of HARMONY_ELIGIBLE), or null when the axis is empty. */
+  family: string | null;
+}
+
+// Slot 0 is the anchor (Brand), then Accent, Background — the pre-axes default.
+const LEGACY_DEFAULT_ORDER: readonly string[] = ['Brand', 'Accent', 'Background'];
+
+/**
+ * Coerce an untrusted legacy `harmonyOrder` (theme JSON) into a valid order:
+ * keep only eligible entries, first occurrence of each. A non-array, empty, or
+ * fully-invalid input falls back to the default order. Private to
+ * `axesFromLegacyOrder`, the sole migration entry point.
+ */
+function sanitizeLegacyOrder(input: unknown): string[] {
+  if (!Array.isArray(input)) return [...LEGACY_DEFAULT_ORDER];
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const entry of input) {
+    if (typeof entry !== 'string') continue;
+    if (!HARMONY_ELIGIBLE.includes(entry)) continue;
+    if (seen.has(entry)) continue;
+    seen.add(entry);
+    out.push(entry);
+  }
+  return out.length > 0 ? out : [...LEGACY_DEFAULT_ORDER];
+}
+
+// In-range hues pass through bit-exact: the mod-360 round trip perturbs the
+// last mantissa bits, which would make a preserved hue compare unequal.
+const norm = (h: number): number => (h >= 0 && h < 360 ? h : ((h % 360) + 360) % 360);
+
+/**
+ * Slot hues for `mode` from the anchor hue, priority-ordered: slot 1 is the
+ * primary harmonic partner. Returns the first `slotCount` slots (1–4). With the
+ * default order, dealing slots 0–2 reproduces today's per-family output.
+ */
+export function harmonyHues(mode: HarmonyMode, anchorHue: number, slotCount: number): number[] {
+  const a = norm(anchorHue);
+  const slots = ((): number[] => {
+    switch (mode) {
+      case 'complementary':       return [a, norm(a + 180), a, norm(a + 180)];
+      case 'split-complementary': return [a, norm(a + 210), norm(a + 150), a];
+      case 'triadic':             return [a, norm(a + 240), norm(a + 120), a];
+      case 'tetradic':            return [a, norm(a + 180), norm(a + 60), norm(a + 240)];
+      case 'compound':            return [a, norm(a + 180), norm(a + 30), norm(a + 210)];
+      case 'square':              return [a, norm(a + 180), norm(a + 90), norm(a + 270)];
+      case 'analogous':           return [a, norm(a + 30), norm(a - 30), a];
+      case 'monochromatic':       return [a, a, a, a];
+      case 'custom':              return [a, a, a, a];
+    }
+  })();
+  return slots.slice(0, slotCount);
+}
+
+function reHue(config: PaletteConfig, hue: number): Oklch {
+  const { l, c } = config.baseColor;
+  return { l, c, h: norm(hue) };
+}
+
+/** Re-hue Neutral and Alternate to `anchorHue`, own chroma + lightness kept. */
+export function tintNeutralsFromAnchor(
+  palettes: Record<string, PaletteConfig>,
+  anchorHue: number,
+): Record<string, Oklch> {
+  const out: Record<string, Oklch> = {};
+  for (const label of ['Neutral', 'Alternate']) {
+    const config = palettes[label];
+    if (config) out[label] = reHue(config, anchorHue);
+  }
+  return out;
+}
+
+// Callers only pass HARMONY_ELIGIBLE families, all of which have a spec; a miss
+// is a programming error, so surface it rather than seed a silent hue 0.
+const specInitialHue = (label: string): number =>
+  PALETTE_SPECS.find((s) => s.label === label)!.initialColor.h;
+
+/**
+ * Seed the four axes for a fresh editor: the default trio bound (hues read from
+ * `PALETTE_SPECS`, never hardcoded) and Quaternary unbound at anchor + 270 (the
+ * square slot-3 offset). Fresh array each call — it seeds mutable state.
+ */
+export function defaultHarmonyAxes(): HarmonyAxis[] {
+  const anchorHue = specInitialHue('Brand');
+  return [
+    { hue: anchorHue, family: 'Brand' },
+    { hue: specInitialHue('Accent'), family: 'Accent' },
+    { hue: specInitialHue('Background'), family: 'Background' },
+    { hue: norm(anchorHue + 270), family: null },
+  ];
+}
+
+/**
+ * Per-axis availability in `mode`: an axis participates only when its slot is a
+ * distinct position (complementary → 2 axes, triadic → 3, square → 4). Two
+ * carve-outs keep every axis active: monochromatic, whose repeats are the point
+ * (all axes collapse onto the anchor), and custom, which imposes no geometry.
+ */
+export function modeActiveAxes(mode: HarmonyMode): boolean[] {
+  if (mode === 'custom' || mode === 'monochromatic') return Array(AXIS_COUNT).fill(true);
+  const slots = harmonyHues(mode, 0, AXIS_COUNT);
+  return slots.map((h, i) => slots.slice(0, i).every((prev) => prev !== h));
+}
+
+/**
+ * Re-deal every axis's hue from `mode`'s geometry, anchored on axis 0's hue.
+ * Bindings are preserved; `'custom'` imposes no constraint and returns a copy.
+ * An axis inactive in `mode` (its slot would be a repeat) is left alone — the
+ * UI disables it while unbound.
+ */
+export function applyHarmonyToAxes(mode: HarmonyMode, axes: HarmonyAxis[]): HarmonyAxis[] {
+  if (mode === 'custom') return axes.map((a) => ({ ...a }));
+  const hues = harmonyHues(mode, axes[0].hue, AXIS_COUNT);
+  const active = modeActiveAxes(mode);
+  return axes.map((a, i) => (active[i] ? { hue: hues[i], family: a.family } : { ...a }));
+}
+
+/**
+ * New baseColors for the families bound to axes, each re-hued to its axis hue
+ * with its own chroma + lightness preserved. Unbound axes and missing configs
+ * contribute nothing.
+ */
+export function boundColorPatch(
+  axes: HarmonyAxis[],
+  palettes: Record<string, PaletteConfig>,
+): Record<string, Oklch> {
+  const out: Record<string, Oklch> = {};
+  for (const axis of axes) {
+    if (axis.family === null) continue;
+    const config = palettes[axis.family];
+    if (config) out[axis.family] = reHue(config, axis.hue);
+  }
+  return out;
+}
+
+/**
+ * Coerce untrusted `harmonyAxes` (theme JSON) into exactly `AXIS_COUNT` axes:
+ * truncate extras, pad missing indexes from the defaults, drop ineligible or
+ * duplicate families to `null`, and replace non-finite hues with the default
+ * axis hue. The loaded color is ground truth, so every bound axis whose palette
+ * exists finally snaps its hue to that palette's `baseColor.h`.
+ */
+export function sanitizeHarmonyAxes(
+  input: unknown,
+  palettes: Record<string, PaletteConfig>,
+): HarmonyAxis[] {
+  const defaults = defaultHarmonyAxes();
+  const source = Array.isArray(input) ? input : defaults;
+  const used = new Set<string>();
+  const axes: HarmonyAxis[] = [];
+  for (let i = 0; i < AXIS_COUNT; i++) {
+    const entry = (source[i] ?? defaults[i]) as Partial<HarmonyAxis>;
+    const rawFamily = entry.family;
+    let family: string | null = null;
+    if (typeof rawFamily === 'string' && HARMONY_ELIGIBLE.includes(rawFamily) && !used.has(rawFamily)) {
+      family = rawFamily;
+      used.add(rawFamily);
+    }
+    const rawHue = entry.hue;
+    const hue = typeof rawHue === 'number' && Number.isFinite(rawHue) ? norm(rawHue) : defaults[i].hue;
+    axes.push({ hue, family });
+  }
+  for (const axis of axes) {
+    if (axis.family !== null && palettes[axis.family]) {
+      axis.hue = norm(palettes[axis.family].baseColor.h);
+    }
+  }
+  return axes;
+}
+
+/**
+ * Migrate a legacy `harmonyOrder` into axes: `order[i]` binds to axis `i` (via
+ * the same eligibility/dedup rules as the old model), seeded at its palette's
+ * `baseColor.h` (or the family's spec hue when no palette loaded). Unfilled axes
+ * stay unbound at the default hues, Quaternary offset from the migrated anchor.
+ */
+export function axesFromLegacyOrder(
+  order: unknown,
+  palettes: Record<string, PaletteConfig>,
+): HarmonyAxis[] {
+  const legacy = sanitizeLegacyOrder(order);
+  const defaults = defaultHarmonyAxes();
+  const hueOf = (family: string): number =>
+    norm(palettes[family] ? palettes[family].baseColor.h : specInitialHue(family));
+  const axes: HarmonyAxis[] = [];
+  for (let i = 0; i < AXIS_COUNT; i++) {
+    const family = legacy[i] ?? null;
+    if (family) {
+      axes.push({ hue: hueOf(family), family });
+    } else if (i === AXIS_COUNT - 1) {
+      axes.push({ hue: norm(axes[0].hue + 270), family: null });
+    } else {
+      axes.push({ hue: defaults[i].hue, family: null });
+    }
+  }
+  return axes;
+}

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

@@ -0,0 +1,128 @@
+// WCAG 2.1 contrast math + an OKLCH-lightness solver.
+//
+// The solver is the engine behind the "Derive accessible text" action: given a
+// surface hex and a target ratio, it finds the lightness (at fixed hue) whose
+// gamut-clamped color clears the ratio. Contrast is monotonic in L only on one
+// side of the surface's own lightness, so `direction` selects the branch.
+
+import { hexToOklch, oklchToHex, gamutClamp } from './oklch';
+
+export const AA_BODY = 4.5;
+export const AA_LARGE = 3.0;
+
+function linearizeChannel(v8: number): number {
+  const s = v8 / 255;
+  return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+}
+
+export function relativeLuminance(hex: string): number {
+  const r = linearizeChannel(parseInt(hex.slice(1, 3), 16));
+  const g = linearizeChannel(parseInt(hex.slice(3, 5), 16));
+  const b = linearizeChannel(parseInt(hex.slice(5, 7), 16));
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+export function contrastRatio(a: string, b: string): number {
+  const la = relativeLuminance(a);
+  const lb = relativeLuminance(b);
+  const hi = Math.max(la, lb);
+  const lo = Math.min(la, lb);
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+export interface FindLOptions {
+  against: string;
+  ratio: number;
+  direction: 'lighter' | 'darker';
+  c: number;
+  h: number;
+  margin?: number;
+  /** Reachable-L window. The Text derivation multiplies seed L by a curve
+   *  factor clamped to [0,2], so a family can only reach L ∈ [0, min(1,2·seedL)].
+   *  The solver passes that ceiling as `lMax` so the returned L is realisable. */
+  lMin?: number;
+  lMax?: number;
+}
+
+export interface FindLResult {
+  l: number;
+  c: number;
+  hex: string;
+}
+
+/**
+ * Binary-search OKLCH lightness for a color that clears `ratio` against
+ * `against`, staying on the `direction` side of the surface (the monotonic
+ * branch). If the ratio is unreachable at chroma `c` within the window, decay
+ * chroma toward 0 and retry — achromatic extremes reach the full 1..21 range.
+ * The result is re-verified with `contrastRatio` after the hex round-trip and
+ * nudged one step if 8-bit quantization ate the margin (Global invariant 8).
+ */
+export function findLForContrast(opts: FindLOptions): FindLResult {
+  const { against, ratio, direction, c, h } = opts;
+  const margin = opts.margin ?? 0.05;
+  const lMin = opts.lMin ?? 0;
+  const lMax = opts.lMax ?? 1;
+  const target = ratio + margin;
+  const againstL = hexToOklch(against).l;
+
+  const evalAt = (l: number, cc: number) => {
+    const g = gamutClamp(l, cc, h);
+    const hex = oklchToHex(g.l, g.c, g.h);
+    return { hex, chroma: g.c, ratio: contrastRatio(hex, against) };
+  };
+
+  // Returns the boundary solution at a fixed chroma, or null if `target` is
+  // unreachable within the window at that chroma. `extreme` is the window end
+  // with the most contrast (top L for lighter, bottom L for darker).
+  const solveAtChroma = (cc: number): { l: number; hex: string; chroma: number } | null => {
+    const lighter = direction === 'lighter';
+    const lo0 = lighter ? Math.max(lMin, againstL) : lMin;
+    const hi0 = lighter ? lMax : Math.min(lMax, againstL);
+    if (lo0 >= hi0) return null; // no room to move to the requested side within the window
+    const extreme = lighter ? hi0 : lo0;
+    if (evalAt(extreme, cc).ratio < target) return null;
+    let lo = lo0;
+    let hi = hi0;
+    for (let i = 0; i < 24; i++) {
+      const mid = (lo + hi) / 2;
+      const meets = evalAt(mid, cc).ratio >= target;
+      // Contrast rises toward `extreme`; keep the half that still meets target.
+      if (lighter ? meets : !meets) hi = mid;
+      else lo = mid;
+    }
+    const at = lighter ? hi : lo;
+    const e = evalAt(at, cc);
+    return { l: at, hex: e.hex, chroma: e.chroma };
+  };
+
+  let sol = solveAtChroma(c);
+  if (!sol) {
+    if (!solveAtChroma(0)) {
+      // Even achromatic can't reach the target within the window — return the
+      // extreme (best effort); the caller reports it as unmet.
+      const extremeL = direction === 'lighter' ? lMax : lMin;
+      const e = evalAt(extremeL, 0);
+      return { l: extremeL, c: 0, hex: e.hex };
+    }
+    let lo = 0;
+    let hi = c;
+    for (let i = 0; i < 24; i++) {
+      const mid = (lo + hi) / 2;
+      if (solveAtChroma(mid)) lo = mid;
+      else hi = mid;
+    }
+    sol = solveAtChroma(lo)!;
+  }
+
+  let { l, hex, chroma } = sol;
+  const step = direction === 'lighter' ? 0.004 : -0.004;
+  for (let k = 0; k < 12 && contrastRatio(hex, against) < ratio; k++) {
+    l = Math.min(lMax, Math.max(lMin, l + step));
+    const g = gamutClamp(l, chroma, h);
+    l = g.l;
+    chroma = g.c;
+    hex = oklchToHex(g.l, g.c, g.h);
+  }
+  return { l, c: chroma, hex };
+}

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

@@ -102,6 +102,14 @@ function isInGamut(r: number, g: number, b: number): boolean {
   return r >= -eps && r <= 1 + eps && g >= -eps && g <= 1 + eps && b >= -eps && b <= 1 + eps;
 }
 
+/** The clamped sRGB projection: reduce chroma into gamut, then serialize to hex.
+ *  This is the correct projection for unclamped stored intent — naive
+ *  `oklchToHex` per-channel clips (shifting hue), this preserves hue and L. */
+export function oklchToHexClamped(l: number, c: number, h: number): string {
+  const g = gamutClamp(l, c, h);
+  return oklchToHex(g.l, g.c, g.h);
+}
+
 export function gamutClamp(l: number, c: number, h: number): Oklch {
   // Clamp lightness
   if (l <= 0) return { l: 0, c: 0, h };