@motion-proto/live-tokens 0.40.0 → 0.41.0

package/src/editor/ui/colors/PaletteStepStrip.svelte

@@ -0,0 +1,142 @@
+<script lang="ts">
+  import { editorState } from '../../core/store/editorStore';
+  import {
+    PALETTE_STEPS,
+    derivePaletteValues,
+    serializeDerivedValue,
+    type PaletteSpec,
+  } from '../../core/palettes/paletteDerivation';
+  import { contrastRatio, AA_BODY } from '../../core/palettes/contrast';
+  import { defaultPaletteConfig } from '../palette/paletteMath';
+  import { dockGrow } from '../palette/dockMagnify';
+
+  let { spec }: { spec: PaletteSpec } = $props();
+
+  let config = $derived($editorState.palettes[spec.label]);
+  let isGradient = $derived(!!spec.emptySelector && (config?.emptyMode ?? 'solid') === 'gradient');
+
+  function withContrast(hex: string) {
+    const onWhite = contrastRatio(hex, '#ffffff');
+    const onBlack = contrastRatio(hex, '#000000');
+    const best = Math.max(onWhite, onBlack);
+    return { hex, textHex: onWhite >= onBlack ? '#ffffff' : '#000000', best, aa: best >= AA_BODY };
+  }
+
+  let effectiveConfig = $derived(config ?? defaultPaletteConfig({ baseColor: spec.initialColor, neutral: spec.neutral }));
+
+  let steps = $derived.by(() => {
+    const values = derivePaletteValues(spec, effectiveConfig);
+    return PALETTE_STEPS.map((ps) => ({
+      label: ps.label,
+      ...withContrast(serializeDerivedValue(values[`--color-${spec.cssNamespace}-${ps.label}`])),
+    }));
+  });
+
+  // Dock magnification, mirroring PaletteEditor's swatch grid: the flex-grow
+  // transition animates the walk as lightness is dialed.
+  let anchoredStep = $derived(effectiveConfig.anchorToBase === false ? null : effectiveConfig.anchorPlacement?.step ?? null);
+  // The page background follows the base anchor; there is no separate spot.
+  let backgroundStep = $derived(spec.emptySelector && !isGradient ? anchoredStep : null);
+
+  // Floor, don't round: the readout must never overstate a contrast ratio.
+  function verdict(s: { best: number; aa: boolean }): string {
+    const ratio = `${(Math.floor(s.best * 10) / 10).toFixed(1)}:1`;
+    return s.aa ? `best text contrast ${ratio}` : `no text reaches AA (best ${ratio})`;
+  }
+
+  function stepTitle(s: (typeof steps)[number], i: number): string {
+    const anchor = i === anchoredStep ? ' · base color' : '';
+    const bg = i === backgroundStep ? ' · page background' : '';
+    return `${spec.label} ${s.label}${anchor}${bg} · ${verdict(s)}`;
+  }
+</script>
+
+<div class="strip" role="group" aria-label={`${spec.label} derived scale`}>
+  {#each steps as s, i (s.label)}
+    <div
+      class="spot"
+      class:anchored={anchoredStep === i}
+      class:background={backgroundStep === i}
+      style:flex-grow={dockGrow(i, anchoredStep)}
+      title={stepTitle(s, i)}
+    >
+      <span class="chip" style:background={s.hex}>
+        <span class="aa" class:fail={!s.aa} style:color={s.textHex}>Aa</span>
+      </span>
+      <span class="step-label">{s.label}</span>
+    </div>
+  {/each}
+</div>
+{#if isGradient}
+  <p class="hint">The page background is currently a gradient; the base color takes over when gradient mode is off.</p>
+{/if}
+
+<style>
+  .strip {
+    display: flex;
+    align-items: flex-end;
+    gap: var(--ui-space-4);
+  }
+
+  .spot {
+    flex: 1 1 0;
+    min-width: 0;
+    display: flex;
+    flex-direction: column;
+    gap: var(--ui-space-4);
+    transition: flex-grow var(--ui-transition-fast);
+  }
+
+  .chip {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    height: 2.25rem;
+    /* Compensating margin: height + margin-top is constant every frame of the
+       magnification, so the strip's layout height never dips mid-transition
+       (the dip bounced everything below). Chip grows upward, label pinned. */
+    margin-top: 0.5rem;
+    border-radius: var(--ui-radius-sm);
+    border: 1px solid var(--ui-border-low);
+    transition: border-color var(--ui-transition-fast), height var(--ui-transition-fast), margin-top var(--ui-transition-fast);
+  }
+
+  .spot.anchored .chip {
+    height: 2.75rem;
+    margin-top: 0;
+    border-color: var(--ui-border-higher);
+  }
+
+  /* The ring marks the page background, which is the anchored base color. */
+  .spot.background .chip {
+    outline: 2px solid var(--ui-text-primary);
+    outline-offset: 1px;
+  }
+
+  .aa {
+    font-size: var(--ui-font-size-xs);
+    font-weight: var(--ui-font-weight-semibold);
+  }
+
+  .aa.fail {
+    opacity: 0.55;
+    text-decoration: line-through;
+  }
+
+  .step-label {
+    font-size: var(--ui-font-size-xs);
+    color: var(--ui-text-secondary);
+    text-align: center;
+  }
+
+  .spot.anchored .step-label {
+    color: var(--ui-text-primary);
+    font-weight: var(--ui-font-weight-semibold);
+  }
+
+  .hint {
+    margin: 0;
+    font-size: var(--ui-font-size-sm);
+    color: var(--ui-text-secondary);
+  }
+</style>

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

@@ -0,0 +1,9 @@
+import { gamutClamp } from '../../core/palettes/oklch';
+
+// The one gamut-max-chroma helper the wheel disc and the lightness bar share:
+// the in-gamut chroma boundary for a hue at a given L (invariant: gamut is
+// display-only). GAMUT_PROBE is a chroma the binary search walks inward from —
+// any value past the widest sRGB reach works.
+const GAMUT_PROBE = 0.5;
+
+export const maxChroma = (l: number, hue: number): number => gamutClamp(l, GAMUT_PROBE, hue).c;

package/src/editor/ui/colors/harmony-icons/analogous.svg

@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256">
+  <g>
+    <circle fill="none" stroke="currentColor" stroke-width="18" opacity="0.25" cx="128" cy="128" r="90"/>
+  </g>
+  <g>
+    <circle fill="currentColor" cx="128" cy="38" r="14"/>
+    <line fill="none" stroke="currentColor" stroke-width="10" stroke-linecap="round" x1="128" y1="128" x2="128" y2="38"/>
+    <circle fill="currentColor" cx="64.36" cy="64.36" r="14"/>
+    <line fill="none" stroke="currentColor" stroke-width="10" stroke-linecap="round" x1="128" y1="128" x2="64.36" y2="64.36"/>
+    <circle fill="currentColor" cx="191.64" cy="64.36" r="14"/>
+    <line fill="none" stroke="currentColor" stroke-width="10" stroke-linecap="round" x1="128" y1="128" x2="191.64" y2="64.36"/>
+  </g>
+</svg>

package/src/editor/ui/colors/harmony-icons/complementary.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256">
+  <g>
+    <circle fill="none" stroke="currentColor" stroke-width="18" opacity="0.25" cx="128" cy="128" r="90"/>
+  </g>
+  <g>
+    <circle fill="currentColor" cx="128" cy="38" r="14"/>
+    <circle fill="currentColor" cx="128" cy="218" r="14"/>
+    <line fill="none" stroke="currentColor" stroke-width="10" stroke-linecap="round" x1="128" y1="218" x2="128" y2="38"/>
+  </g>
+</svg>

package/src/editor/ui/colors/harmony-icons/compound.svg

@@ -0,0 +1,15 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256">
+  <g>
+    <circle fill="none" stroke="currentColor" stroke-width="18" opacity="0.25" cx="128" cy="128" r="90"/>
+  </g>
+  <g>
+    <circle fill="currentColor" cx="83" cy="50.058" r="14"/>
+    <line fill="none" stroke="currentColor" stroke-width="10" stroke-linecap="round" x1="128" y1="128" x2="83" y2="50.058"/>
+    <circle fill="currentColor" cx="50.058" cy="83" r="14"/>
+    <line fill="none" stroke="currentColor" stroke-width="10" stroke-linecap="round" x1="128" y1="128" x2="50.058" y2="83"/>
+    <circle fill="currentColor" cx="173" cy="205.942" r="14"/>
+    <line fill="none" stroke="currentColor" stroke-width="10" stroke-linecap="round" x1="128" y1="128" x2="173" y2="205.942"/>
+    <circle fill="currentColor" cx="128" cy="218" r="14"/>
+    <line fill="none" stroke="currentColor" stroke-width="10" stroke-linecap="round" x1="128" y1="128" x2="128" y2="218"/>
+  </g>
+</svg>

package/src/editor/ui/colors/harmony-icons/custom.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256">
+  <g>
+    <circle fill="none" stroke="currentColor" stroke-width="18" opacity="0.25" cx="128" cy="128" r="90"/>
+  </g>
+  <g>
+    <circle fill="currentColor" cx="150.686" cy="144.528" r="14"/>
+    <circle fill="currentColor" cx="175.564" cy="60.02" r="14"/>
+    <circle fill="currentColor" cx="75.597" cy="105.538" r="14"/>
+  </g>
+</svg>

package/src/editor/ui/colors/harmony-icons/monochromatic.svg

@@ -0,0 +1,11 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256">
+  <g>
+    <circle fill="none" stroke="currentColor" stroke-width="18" opacity="0.25" cx="128" cy="128" r="90"/>
+  </g>
+  <g>
+    <circle fill="currentColor" cx="128" cy="38" r="14"/>
+    <circle fill="currentColor" cx="128" cy="70" r="14"/>
+    <circle fill="currentColor" cx="128" cy="102" r="14"/>
+    <line fill="none" stroke="currentColor" stroke-width="10" stroke-linecap="round" x1="128" y1="128" x2="128" y2="38"/>
+  </g>
+</svg>

package/src/editor/ui/colors/harmony-icons/shades.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256">
+  <g>
+    <circle fill="none" stroke="currentColor" stroke-width="18" opacity="0.25" cx="128" cy="128" r="90"/>
+  </g>
+  <g>
+    <circle fill="currentColor" cx="128" cy="38" r="14"/>
+    <line fill="none" stroke="currentColor" stroke-width="10" stroke-linecap="round" x1="128" y1="128" x2="128" y2="38"/>
+  </g>
+</svg>

package/src/editor/ui/colors/harmony-icons/split-complementary.svg

@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256">
+  <g>
+    <circle fill="none" stroke="currentColor" stroke-width="18" opacity="0.25" cx="128" cy="128" r="90"/>
+  </g>
+  <g>
+    <circle fill="currentColor" cx="128" cy="38" r="14"/>
+    <line fill="none" stroke="currentColor" stroke-width="10" stroke-linecap="round" x1="128" y1="128" x2="128" y2="38"/>
+    <circle fill="currentColor" cx="83" cy="205.942" r="14"/>
+    <line fill="none" stroke="currentColor" stroke-width="10" stroke-linecap="round" x1="128" y1="128" x2="83" y2="205.942"/>
+    <circle fill="currentColor" cx="173" cy="205.942" r="14"/>
+    <line fill="none" stroke="currentColor" stroke-width="10" stroke-linecap="round" x1="128" y1="128" x2="173" y2="205.942"/>
+  </g>
+</svg>

package/src/editor/ui/colors/harmony-icons/square.svg

@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256">
+  <g>
+    <circle fill="none" stroke="currentColor" stroke-width="18" opacity="0.25" cx="128" cy="128" r="90"/>
+  </g>
+  <g>
+    <circle fill="currentColor" cx="64.36" cy="64.36" r="14"/>
+    <circle fill="currentColor" cx="64.36" cy="191.64" r="14"/>
+    <circle fill="currentColor" cx="191.64" cy="191.64" r="14"/>
+    <circle fill="currentColor" cx="191.64" cy="64.36" r="14"/>
+    <line fill="none" stroke="currentColor" stroke-width="10" stroke-linecap="round" stroke-linejoin="round" x1="191.64" y1="64.36" x2="64.36" y2="191.64"/>
+    <line fill="none" stroke="currentColor" stroke-width="10" stroke-linecap="round" stroke-linejoin="round" x1="64.36" y1="64.36" x2="191.64" y2="191.64"/>
+  </g>
+</svg>

package/src/editor/ui/colors/harmony-icons/tetradic.svg

@@ -0,0 +1,15 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256">
+  <g>
+    <circle fill="none" stroke="currentColor" stroke-width="18" opacity="0.25" cx="128" cy="128" r="90"/>
+  </g>
+  <g>
+    <circle fill="currentColor" cx="173" cy="50.058" r="14"/>
+    <line fill="none" stroke="currentColor" stroke-width="10" stroke-linecap="round" x1="128" y1="128" x2="173" y2="50.058"/>
+    <circle fill="currentColor" cx="83" cy="50.058" r="14"/>
+    <line fill="none" stroke="currentColor" stroke-width="10" stroke-linecap="round" x1="128" y1="128" x2="83" y2="50.058"/>
+    <circle fill="currentColor" cx="83" cy="205.942" r="14"/>
+    <line fill="none" stroke="currentColor" stroke-width="10" stroke-linecap="round" x1="128" y1="128" x2="83" y2="205.942"/>
+    <circle fill="currentColor" cx="173" cy="205.942" r="14"/>
+    <line fill="none" stroke="currentColor" stroke-width="10" stroke-linecap="round" x1="128" y1="128" x2="173" y2="205.942"/>
+  </g>
+</svg>

package/src/editor/ui/colors/harmony-icons/triadic.svg

@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256">
+  <g>
+    <circle fill="none" stroke="currentColor" stroke-width="18" opacity="0.25" cx="128" cy="128" r="90"/>
+  </g>
+  <g>
+    <circle fill="currentColor" cx="128" cy="38" r="14"/>
+    <circle fill="currentColor" cx="50.058" cy="173" r="14"/>
+    <circle fill="currentColor" cx="205.942" cy="173" r="14"/>
+    <line fill="none" stroke="currentColor" stroke-width="10" stroke-linecap="round" x1="128" y1="128" x2="128" y2="38"/>
+    <line fill="none" stroke="currentColor" stroke-width="10" stroke-linecap="round" x1="128" y1="128" x2="50.058" y2="173"/>
+    <line fill="none" stroke="currentColor" stroke-width="10" stroke-linecap="round" x1="128" y1="128" x2="205.942" y2="173"/>
+  </g>
+</svg>

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

@@ -0,0 +1,23 @@
+import type { HarmonyMode } from '../../core/palettes/colorHarmony';
+
+import monochromaticSvg from './harmony-icons/monochromatic.svg?raw';
+import analogousSvg from './harmony-icons/analogous.svg?raw';
+import complementarySvg from './harmony-icons/complementary.svg?raw';
+import splitComplementarySvg from './harmony-icons/split-complementary.svg?raw';
+import triadicSvg from './harmony-icons/triadic.svg?raw';
+import tetradicSvg from './harmony-icons/tetradic.svg?raw';
+import squareSvg from './harmony-icons/square.svg?raw';
+import compoundSvg from './harmony-icons/compound.svg?raw';
+import customSvg from './harmony-icons/custom.svg?raw';
+
+export const HARMONY_MODE_BUTTONS: { mode: HarmonyMode; label: string; svg: string }[] = [
+  { mode: 'monochromatic', label: 'Monochromatic', svg: monochromaticSvg },
+  { mode: 'analogous', label: 'Analogous', svg: analogousSvg },
+  { mode: 'complementary', label: 'Complementary', svg: complementarySvg },
+  { mode: 'split-complementary', label: 'Split complementary', svg: splitComplementarySvg },
+  { mode: 'triadic', label: 'Triadic', svg: triadicSvg },
+  { mode: 'tetradic', label: 'Tetradic', svg: tetradicSvg },
+  { mode: 'square', label: 'Square', svg: squareSvg },
+  { mode: 'compound', label: 'Compound', svg: compoundSvg },
+  { mode: 'custom', label: 'Custom', svg: customSvg },
+];

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

@@ -0,0 +1,214 @@
+/**
+ * The Colors view's writes to a palette's seed color and the page-background
+ * spot. Both the wheel handle drag and the readout panel funnel through here so
+ * a Colors-view edit is byte-identical to a PaletteEditor base-color edit
+ * (global invariant 5: one store path, no parallel color state). `mutate` runs
+ * inside whatever scope the caller has opened (a wheel drag's clipping session,
+ * a slider gesture, or none for a discrete edit); the seed-color setters never
+ * open or commit scopes themselves.
+ *
+ * The store holds unclamped OKLCH intent: setters write channels directly, with
+ * no gamut clamp and no hex round-trip. Clamping is projection-only (derivation
+ * output, canvas painting, hex/CSS serialization), which is what lets a drag
+ * past an L extreme recover its chroma and keep its hue through grey.
+ *
+ * The seed-if-missing branch mirrors `PaletteEditor.edit` — in a loaded theme
+ * every palette already exists, but keeping the write self-sufficient means a
+ * handle can never silently drop an edit.
+ */
+
+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';
+import type { PaletteConfig } from '../../core/themes/themeTypes';
+
+const SPEC_BY_LABEL: Record<string, PaletteSpec> = Object.fromEntries(PALETTE_SPECS.map((s) => [s.label, s]));
+
+const normHue = (d: number) => ((d % 360) + 360) % 360;
+
+function ensureConfig(s: EditorState, label: string): PaletteConfig {
+  let cfg = s.palettes[label];
+  if (!cfg) {
+    const spec = SPEC_BY_LABEL[label];
+    cfg = s.palettes[label] = defaultPaletteConfig({ baseColor: spec.initialColor, neutral: spec.neutral });
+  }
+  return cfg;
+}
+
+/** Drag the bound axis's hue along after a direct color-hue edit — the handle is
+ *  the color's handle while bound, so it must not silently detach (invariant 1). */
+function syncBoundAxisHue(s: EditorState, label: string): void {
+  const axis = s.harmonyAxes.find((a) => a.family === label);
+  if (axis) axis.hue = normHue(s.palettes[label].baseColor.h);
+}
+
+/** Set the full seed color (H, C and L). Used by the readout panel. */
+export function setBaseColor(label: string, color: Oklch): void {
+  mutate(`colors: ${label} base`, (s) => {
+    const cfg = ensureConfig(s, label);
+    cfg.baseColor = color;
+    syncBaseAnchor(cfg);
+    syncBoundAxisHue(s, label);
+  });
+}
+
+/** Set hue + chroma while preserving the seed's current lightness. Used by wheel drags/nudges. */
+export function setBaseHueChroma(label: string, hue: number, chroma: number): void {
+  mutate(`colors: ${label} base`, (s) => {
+    const cfg = ensureConfig(s, label);
+    cfg.baseColor = { l: cfg.baseColor.l, c: Math.max(0, chroma), h: normHue(hue) };
+    syncBaseAnchor(cfg);
+    syncBoundAxisHue(s, label);
+  });
+}
+
+/** Rotate a seed's hue only — chroma and lightness preserved (harmony rotation,
+ *  external rotate handles). Mirrors colorHarmony's `reHue`. */
+export function setBaseHue(label: string, hue: number): void {
+  mutate(`colors: ${label} hue`, (s) => {
+    const cfg = ensureConfig(s, label);
+    cfg.baseColor = { l: cfg.baseColor.l, c: cfg.baseColor.c, h: normHue(hue) };
+    syncBaseAnchor(cfg);
+    syncBoundAxisHue(s, label);
+  });
+}
+
+/** Set a seed's lightness and chroma, hue preserved from the store. Used by the
+ *  lightness bar. No pinned-hue parameter: numeric storage keeps hue stable even
+ *  at c≈0, so it can be read straight from the store. */
+export function setBaseLightnessChroma(label: string, lightness: number, chroma: number): void {
+  mutate(`colors: ${label} lightness`, (s) => {
+    const cfg = ensureConfig(s, label);
+    cfg.baseColor = { l: lightness, c: Math.max(0, chroma), h: cfg.baseColor.h };
+    syncBaseAnchor(cfg);
+  });
+}
+
+/** Set a seed's chroma only — hue and lightness preserved (rail-constrained drag). */
+export function setBaseChroma(label: string, chroma: number): void {
+  mutate(`colors: ${label} chroma`, (s) => {
+    const cfg = ensureConfig(s, label);
+    cfg.baseColor = { l: cfg.baseColor.l, c: Math.max(0, chroma), h: cfg.baseColor.h };
+    syncBaseAnchor(cfg);
+  });
+}
+
+/** Set one axis's hue; a bound family's baseColor follows in the same mutate.
+ *  familyChroma carries the wheel drag's chroma policy; omitted = chroma kept. */
+export function setAxisHue(index: number, hue: number, familyChroma?: number): void {
+  const h = normHue(hue);
+  const axis = get(editorState).harmonyAxes[index];
+  const c = familyChroma !== undefined ? Math.max(0, familyChroma) : undefined;
+  const base = axis.family !== null ? get(editorState).palettes[axis.family]?.baseColor : undefined;
+  const colorNoop = !base || (base.h === h && (c === undefined || base.c === c));
+  if (axis.hue === h && colorNoop) return;
+  mutate(`colors: ${AXIS_ROLES[index]} axis hue`, (s) => {
+    applyAxisHue(s, index, h, c);
+  });
+}
+
+/** Several axis hues in ONE transaction (mode apply, keyboard rotate-all). */
+export function setAxisHues(
+  entries: { index: number; hue: number; familyChroma?: number }[],
+  historyLabel: string,
+): void {
+  const s0 = get(editorState);
+  const changes = entries.map((e) => ({
+    index: e.index,
+    h: normHue(e.hue),
+    c: e.familyChroma !== undefined ? Math.max(0, e.familyChroma) : undefined,
+  }));
+  const changed = changes.some(({ index, h, c }) => {
+    const axis = s0.harmonyAxes[index];
+    if (axis.hue !== h) return true;
+    const base = axis.family !== null ? s0.palettes[axis.family]?.baseColor : undefined;
+    if (!base) return false;
+    return base.h !== h || (c !== undefined && base.c !== c);
+  });
+  if (!changed) return;
+  transaction(historyLabel, (s) => {
+    for (const { index, h, c } of changes) applyAxisHue(s, index, h, c);
+  });
+}
+
+function applyAxisHue(s: EditorState, index: number, hue: number, chroma: number | undefined): void {
+  const axis = s.harmonyAxes[index];
+  axis.hue = hue;
+  if (axis.family !== null) {
+    const cfg = ensureConfig(s, axis.family);
+    cfg.baseColor = { l: cfg.baseColor.l, c: chroma ?? cfg.baseColor.c, h: hue };
+    syncBaseAnchor(cfg);
+  }
+}
+
+/** Bind a family to an axis; the family adopts the axis hue (c + L kept).
+ *  Trade-places semantics: whatever occupied the destination takes the source's
+ *  position (another axis, adopting its hue, or Unassigned). One mutate. */
+export function bindFamilyToAxis(family: string, index: number): void {
+  const srcIndex = get(editorState).harmonyAxes.findIndex((a) => a.family === family);
+  if (srcIndex === index) return;
+  mutate(`colors: bind ${family}`, (s) => {
+    const axes = s.harmonyAxes;
+    const occupant = axes[index].family;
+    axes[index].family = family;
+    adoptAxisHue(s, family, axes[index].hue);
+    // Source was another axis: the occupant trades into it (adopting its hue).
+    // Source was Unassigned (-1): the occupant simply floats free, color kept.
+    if (srcIndex !== -1) {
+      axes[srcIndex].family = occupant;
+      if (occupant !== null) adoptAxisHue(s, occupant, axes[srcIndex].hue);
+    }
+  });
+}
+
+/** Unbind; the family keeps its current color, the axis keeps its hue. */
+export function unbindFamily(family: string): void {
+  const idx = get(editorState).harmonyAxes.findIndex((a) => a.family === family);
+  if (idx === -1) return;
+  mutate(`colors: unbind ${family}`, (s) => {
+    s.harmonyAxes[idx].family = null;
+  });
+}
+
+function adoptAxisHue(s: EditorState, family: string, hue: number): void {
+  const cfg = ensureConfig(s, family);
+  cfg.baseColor = { l: cfg.baseColor.l, c: cfg.baseColor.c, h: normHue(hue) };
+  syncBaseAnchor(cfg);
+}
+
+/** Set several seed colors in ONE undo entry (harmony apply, global rotate). */
+export function setBaseColors(patch: Record<string, Oklch>, historyLabel = 'colors: harmony'): void {
+  transaction(historyLabel, (s) => {
+    for (const [label, color] of Object.entries(patch)) {
+      const cfg = ensureConfig(s, label);
+      cfg.baseColor = color;
+      syncBaseAnchor(cfg);
+    }
+  });
+}
+
+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 };
+  }
+}
+
+/** 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 };
+  });
+}

package/src/editor/ui/index.ts

@@ -15,7 +15,6 @@ export * from './variantScales';
 
 // Editor tabs & panels
 export { default as VariablesTab } from './VariablesTab.svelte';
-export { default as TextTab } from './TextTab.svelte';
 export { default as SurfacesTab } from './SurfacesTab.svelte';
 
 // Palette editor stack

package/src/editor/ui/palette/OverridesPanel.svelte

@@ -3,6 +3,7 @@
   import UIPillButton from '../UIPillButton.svelte';
   import { type CurveAnchor, lightnessCurveConfig, saturationCurveConfig, textLightnessCurveConfig } from '../curveEngine';
   import { scaleToCssVar } from '../../core/palettes/paletteDerivation';
+  import type { Oklch } from '../../core/palettes/oklch';
 
   /**
    * Per-scale derived swatch section used for Text, Surfaces, and Borders
@@ -35,7 +36,9 @@
     saturation: () => CurveAnchor[];
   }
 
-  interface PaletteStep { label: string; hex: string }
+  // `hex` is the sRGB projection for swatch/compare; `oklch` is the numeric
+  // value a snap write stores. `overrides` arrives pre-projected to hex.
+  interface PaletteStep { label: string; hex: string; oklch: Oklch }
 
 
 
@@ -64,7 +67,7 @@
     onResetOverride: (key: string) => void;
     onOverrideClick: (key: string, step: Step, scaleTitle: string) => void;
     onSnappedClick: (key: string) => void;
-    onSelectSnapValue: (key: string, paletteHex: string, scaleTitle: string) => void;
+    onSelectSnapValue: (key: string, value: Oklch, scaleTitle: string) => void;
     onCopyHex: (key: string, hex: string, event?: MouseEvent) => void;
     onCopyVarName: (key: string, varName: string, event?: MouseEvent) => void;
     onSetScaleCurve: (scaleTitle: string, channel: Channel, anchors: CurveAnchor[]) => void;
@@ -224,7 +227,7 @@
                     class="snap-picker-item"
                     class:selected={overrides[k] === ps.hex}
                     type="button"
-                    onclick={() => onSelectSnapValue(k, ps.hex, scale.title)}
+                    onclick={() => onSelectSnapValue(k, ps.oklch, scale.title)}
                   >
                     <span class="snap-picker-swatch" style="background: {ps.hex}"></span>
                     <span class="snap-picker-label">{ps.label}</span>

package/src/editor/ui/palette/PaletteBase.svelte

@@ -2,7 +2,7 @@
   import ColorEditPanel from '../ColorEditPanel.svelte';
   import Toggle from '../Toggle.svelte';
   import { beginSliderGesture } from '../../core/store/editorStore';
-  import { hexToOklch } from '../../core/palettes/oklch';
+  import { oklchToHexClamped, type Oklch } from '../../core/palettes/oklch';
 
   // Full sRGB chroma range (gamutClamp trims per hue/lightness). Neutrals default
   // low but are not capped; their calm character comes from defaults, not a ceiling.
@@ -26,11 +26,13 @@
     label: string;
     displayLabel?: string | null;
     neutral?: boolean;
-    baseColor: string;
+    baseColor: Oklch;
     anchorToBase: boolean;
+    /** Palette step label ('500', '850', …) the base color is placed at; null while off or unplaced. */
+    anchorStepLabel?: string | null;
     isEditingBase: boolean;
     panelOpen: boolean;
-    editingColor: string | null;
+    editingColor: Oklch | null;
     editPanelTitle: string | null;
     copiedKey: string | null;
     onStartEdit: () => void;
@@ -47,6 +49,7 @@
     neutral = false,
     baseColor,
     anchorToBase,
+    anchorStepLabel = null,
     isEditingBase,
     panelOpen,
     editingColor,
@@ -60,7 +63,8 @@
     onCopyBaseHex
   }: Props = $props();
 
-  let baseOklch = $derived(hexToOklch(baseColor));
+  let baseOklch = $derived(baseColor);
+  let baseHex = $derived(oklchToHexClamped(baseColor.l, baseColor.c, baseColor.h));
   let pickerChromaHint = $derived(neutral ? NEUTRAL_CALM_CHROMA : undefined);
 </script>
 
@@ -70,7 +74,7 @@
     <div
       class="header-swatch"
       class:active={isEditingBase}
-      style="background: {baseColor}"
+      style="background: {baseHex}"
       onclick={onStartEdit}
       role="button"
       tabindex="0"
@@ -81,8 +85,8 @@
       <button
         class="base-hex clickable-hex"
         type="button"
-        onclick={(e) => onCopyBaseHex('__base__', baseColor, e)}
-      >{copiedKey === '__base__' ? 'copied!' : baseColor}</button>
+        onclick={(e) => onCopyBaseHex('__base__', baseHex, e)}
+      >{copiedKey === '__base__' ? 'copied!' : baseHex}</button>
     </div>
   </div>
 </div>
@@ -103,7 +107,11 @@
     onSliderStart={() => beginSliderGesture(`edit ${label} base`)}
   >
     {#snippet actions()}
-      <Toggle checked={anchorToBase} onchange={(v) => onAnchorToBaseChange(v ?? !anchorToBase)} label="Lock base color to position 500" />
+      <Toggle
+        checked={anchorToBase}
+        onchange={(v) => onAnchorToBaseChange(v ?? !anchorToBase)}
+        label={anchorStepLabel ? `Base color placed at ${anchorStepLabel}` : 'Place base color in palette'}
+      />
     {/snippet}
   </ColorEditPanel>
 {/if}