@motion-proto/live-tokens 0.41.0 → 0.42.0

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # Changelog
 
+## 0.42.0 — Canvas, and every ramp places its base color
+
+### Changed (breaking)
+
+- **The "Background" palette family is renamed to "Canvas".** Its CSS namespace
+  was always `canvas` (`--color-canvas-*`, `--surface-canvas-*`), and every other
+  surface that names the family already said Canvas: the token selector,
+  SectionDivider's variant families, the shadows backdrop picker. Only the
+  palette label said Background, so the label joins the namespace. **No token
+  names change**, so consumer CSS is unaffected. The label doubles as a storage
+  key, so theme migration `2026-07-29-background-palette-to-canvas` renames the
+  `editorConfigs` key and any `harmonyAxes` family binding. It applies
+  automatically both when a theme file loads and when a persisted editor session
+  hydrates, and it runs before the axes are sanitized, which would otherwise drop
+  the now-ineligible family and silently unbind the axis. The shipped
+  `default.json` is rewritten under the new key.
+
+### Added
+
+- **The Colors view's swatch rows read as ramps.** Both rows (core families and
+  functional families) order their swatches by base-color luminance, light to
+  dark, matching the palette ramps. The selected swatch dock-magnifies through
+  the same `dockGrow` policy the palette grid and the derived-scale strip already
+  share, and it animates to its new position as its lightness is dialed, so the
+  selection is legible while it walks the row.
+
+### Removed
+
+- `Theme.harmonyOrder` and its migration path. The field only ever existed
+  between v0.40.1 and v0.41.0, superseded by `harmonyAxes` inside the same
+  release cycle, so nothing on disk carries it: a 0.41.0-saved theme wrote both
+  fields and `harmonyAxes` was already authoritative on load. Themes with
+  neither field still resolve to the default axes, with the unbound Quaternary
+  offset from the anchor's own hue.
+
+### Fixed
+
+- **Palette ramps now show the enlarged slot for the step the base color sits
+  at.** The dock magnification keys off `anchorPlacement`, which the July 24
+  migration only wrote for configs carrying the legacy locked-500 curve anchor;
+  a palette whose `anchorToBase` was on but never re-edited had no placement, so
+  its ramp never magnified anything. Theme migration
+  `2026-07-29-place-base-anchors` places those configs up front by pinning the
+  base color at the step whose curve lightness is nearest the base L, the same
+  thing a base-color edit has always done. It applies on theme load and on
+  session hydrate, skips configs that are already placed or have `anchorToBase`
+  off, and self-sunsets once every theme has been resaved with a placement.
+
+### Migration
+
+- Both migrations in this release are **theme-file migrations**: they run
+  automatically when a theme loads and when a persisted editor session hydrates.
+  No token names changed, so `tokens.css` is untouched and there is nothing for
+  `npx live-tokens migrate` to do. Consumers upgrade by bumping the dependency.
+
 ## 0.41.0 — A Colors view, and semantic text styles
 
 ### Added

package/dist-plugin/index.cjs

@@ -198,7 +198,7 @@ function sampleCurve(anchors, xPos) {
 var PALETTE_SPECS = [
   { label: "Brand", cssNamespace: "brand", initialColor: { l: 0.5573, c: 0.1841, h: 25.49 } },
   { label: "Accent", cssNamespace: "accent", initialColor: { l: 0.7674, c: 0.164, h: 70.44 } },
-  { label: "Background", cssNamespace: "canvas", emptySelector: true, initialColor: { l: 0.2284, c: 0.0384, h: 282.93 } },
+  { label: "Canvas", cssNamespace: "canvas", emptySelector: true, initialColor: { l: 0.2284, c: 0.0384, h: 282.93 } },
   { label: "Neutral", cssNamespace: "neutral", neutral: true, initialColor: { l: 0.5679, c: 0.0134, h: 240.07 } },
   { label: "Alternate", cssNamespace: "alternate", neutral: true, displayLabel: "Alternate (neutral)", initialColor: { l: 0.5873, c: 87e-4, h: 48.57 } },
   { label: "Special", cssNamespace: "special", initialColor: { l: 0.6056, c: 0.2189, h: 292.72 } },

package/dist-plugin/index.js

@@ -157,7 +157,7 @@ function sampleCurve(anchors, xPos) {
 var PALETTE_SPECS = [
   { label: "Brand", cssNamespace: "brand", initialColor: { l: 0.5573, c: 0.1841, h: 25.49 } },
   { label: "Accent", cssNamespace: "accent", initialColor: { l: 0.7674, c: 0.164, h: 70.44 } },
-  { label: "Background", cssNamespace: "canvas", emptySelector: true, initialColor: { l: 0.2284, c: 0.0384, h: 282.93 } },
+  { label: "Canvas", cssNamespace: "canvas", emptySelector: true, initialColor: { l: 0.2284, c: 0.0384, h: 282.93 } },
   { label: "Neutral", cssNamespace: "neutral", neutral: true, initialColor: { l: 0.5679, c: 0.0134, h: 240.07 } },
   { label: "Alternate", cssNamespace: "alternate", neutral: true, displayLabel: "Alternate (neutral)", initialColor: { l: 0.5873, c: 87e-4, h: 48.57 } },
   { label: "Special", cssNamespace: "special", initialColor: { l: 0.6056, c: 0.2189, h: 292.72 } },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motion-proto/live-tokens",
-  "version": "0.41.0",
+  "version": "0.42.0",
   "type": "module",
   "description": "Design token editor with live CSS variable editing. Svelte 5 + Vite 8.",
   "keywords": [

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

@@ -21,7 +21,7 @@ export type HarmonyMode =
   | '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 HARMONY_ELIGIBLE: readonly string[] = ['Brand', 'Accent', 'Canvas', 'Special', 'Neutral', 'Alternate'];
 
 export const AXIS_COUNT = 4;
 export const AXIS_ROLES = ['Anchor', 'Secondary', 'Tertiary', 'Quaternary'] as const;
@@ -33,29 +33,6 @@ export interface HarmonyAxis {
   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);
@@ -116,7 +93,7 @@ export function defaultHarmonyAxes(): HarmonyAxis[] {
   return [
     { hue: anchorHue, family: 'Brand' },
     { hue: specInitialHue('Accent'), family: 'Accent' },
-    { hue: specInitialHue('Background'), family: 'Background' },
+    { hue: specInitialHue('Canvas'), family: 'Canvas' },
     { hue: norm(anchorHue + 270), family: null },
   ];
 }
@@ -196,33 +173,10 @@ export function sanitizeHarmonyAxes(
       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 });
-    }
-  }
+  // With no stored axes (a theme predating them), the default Quaternary hue is
+  // an offset from the anchor, so it follows the anchor's palette-seeded hue
+  // rather than the spec hue the defaults were built from.
+  const last = axes[AXIS_COUNT - 1];
+  if (!Array.isArray(input) && last.family === null) last.hue = norm(axes[0].hue + 270);
   return axes;
 }

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

@@ -40,7 +40,7 @@ export interface PaletteSpec {
 export const PALETTE_SPECS: readonly PaletteSpec[] = [
   { label: 'Brand',      cssNamespace: 'brand',     initialColor: { l: 0.5573, c: 0.1841, h: 25.49 } },
   { label: 'Accent',     cssNamespace: 'accent',    initialColor: { l: 0.7674, c: 0.164, h: 70.44 } },
-  { label: 'Background', cssNamespace: 'canvas',    emptySelector: true, initialColor: { l: 0.2284, c: 0.0384, h: 282.93 } },
+  { label: 'Canvas',     cssNamespace: 'canvas',    emptySelector: true, initialColor: { l: 0.2284, c: 0.0384, h: 282.93 } },
   { label: 'Neutral',    cssNamespace: 'neutral',   neutral: true, initialColor: { l: 0.5679, c: 0.0134, h: 240.07 } },
   { label: 'Alternate',  cssNamespace: 'alternate', neutral: true, displayLabel: 'Alternate (neutral)', initialColor: { l: 0.5873, c: 0.0087, h: 48.57 } },
   { label: 'Special',    cssNamespace: 'special',   initialColor: { l: 0.6056, c: 0.2189, h: 292.72 } },

package/src/editor/core/store/editorPersistence.ts

@@ -20,7 +20,12 @@ import { store } from './editorCore';
 import { quietGet, quietSet } from '../storage/storage';
 import { makeDefaultGradients } from '../themes/slices/gradients';
 import { seedShadowsFromDom } from '../themes/slices/shadows';
-import { sanitizeHarmonyAxes, axesFromLegacyOrder } from '../palettes/colorHarmony';
+import { sanitizeHarmonyAxes } from '../palettes/colorHarmony';
+import {
+  renameBackgroundPaletteKey,
+  renameBackgroundHarmonyFamily,
+} from '../themes/migrations/2026-07-29-background-palette-to-canvas';
+import { placeUnplacedBaseAnchors } from '../themes/migrations/2026-07-29-place-base-anchors';
 
 // Resolve the persist key lazily (per-call) so library consumers that invoke
 // `configureEditor({storagePrefix})` before the first store write get the
@@ -88,20 +93,25 @@ export function normalizeComponents(state: EditorState): EditorState {
   return { ...state, components };
 }
 
-// `hydrate` shallow-merges persisted state over `emptyState()`, which always
-// seeds a default `harmonyAxes`. So a pre-axes session (persisted `harmonyOrder`,
-// no `harmonyAxes`) surfaces here with the injected default axes over its real
-// palettes. The new store never persists `harmonyOrder`, so its presence is the
-// definitive pre-axes signal: migrate from it, seeding hues off the palettes.
-// Otherwise reconcile the persisted axes. Either way, drop the stale legacy key.
+// A session persisted before the rename keys its palette by the old label and
+// binds an axis to it. Both have to move before the axes are sanitized, which
+// would otherwise drop the now-ineligible family and unbind the axis.
+export function normalizePaletteLabels(state: EditorState): EditorState {
+  return { ...state, palettes: renameBackgroundPaletteKey(state.palettes) };
+}
+
+// `hydrate` shallow-merges persisted state over `emptyState()`, so the axes that
+// arrive here may be the injected defaults sitting over the session's real
+// palettes. Reconcile them against those palettes.
 export function normalizeHarmonyAxes(state: EditorState): EditorState {
-  const legacy = (state as { harmonyOrder?: unknown }).harmonyOrder;
-  const axes = legacy !== undefined
-    ? axesFromLegacyOrder(legacy, state.palettes)
-    : sanitizeHarmonyAxes(state.harmonyAxes, state.palettes);
-  const next = { ...state, harmonyAxes: axes };
-  delete (next as { harmonyOrder?: unknown }).harmonyOrder;
-  return next;
+  const axes = renameBackgroundHarmonyFamily(state.harmonyAxes);
+  return { ...state, harmonyAxes: sanitizeHarmonyAxes(axes, state.palettes) };
+}
+
+// A session persisted before placements existed has anchored palettes with no
+// `anchorPlacement`, so their ramps never show the anchored slot.
+export function normalizeBaseAnchors(state: EditorState): EditorState {
+  return { ...state, palettes: placeUnplacedBaseAnchors(state.palettes) };
 }
 
 export function hydrate(): void {
@@ -112,7 +122,7 @@ export function hydrate(): void {
     // Shallow-merge onto default shape so older persisted state missing
     // newly-added domain fields still loads.
     const merged = { ...emptyStateFactory(), ...(parsed as object) } as EditorState;
-    store.set(normalizeHarmonyAxes(normalizeComponents(migrateGradients(merged))));
+    store.set(normalizeHarmonyAxes(normalizeBaseAnchors(normalizePaletteLabels(normalizeComponents(migrateGradients(merged))))));
   }
   // m13 fix: seed shadows from the DOM at hydrate time so the editor
   // captures the tokens.css baseline regardless of whether the user opens

package/src/editor/core/store/editorStore.ts

@@ -28,11 +28,16 @@ import {
   runMigrations,
 } from '../themes/migrations';
 import { renamePrimaryPaletteKey } from '../themes/migrations/2026-05-13-primary-to-brand';
+import {
+  renameBackgroundPaletteKey,
+  renameBackgroundHarmonyFamily,
+} from '../themes/migrations/2026-07-29-background-palette-to-canvas';
 import { unifyGrayPalettes } from '../themes/migrations/2026-06-05-palette-unification';
 import { migratePaletteColorsToOklch, type PreOklchPaletteConfig } from '../themes/migrations/2026-07-21-palette-oklch-basis';
 import { adoptLegacyBaseAnchor } from '../themes/migrations/2026-07-24-base-anchor-placement';
+import { placeUnplacedBaseAnchors } from '../themes/migrations/2026-07-29-place-base-anchors';
 import { adoptBackgroundSpotAsBase } from '../themes/migrations/2026-07-25-background-spot-to-base';
-import { defaultHarmonyAxes, sanitizeHarmonyAxes, axesFromLegacyOrder } from '../palettes/colorHarmony';
+import { defaultHarmonyAxes, sanitizeHarmonyAxes } from '../palettes/colorHarmony';
 import { __resetRendererCacheForTests, installRenderer } from './editorRenderer';
 import {
   store,
@@ -517,13 +522,15 @@ const domainLoaders: Record<string, DomainLoader> = {
  */
 export function loadFromFile(theme: Theme): void {
   const next = emptyState();
-  // Structural palette migrations, innermost → outermost: rename Primary→Brand,
-  // drop the gray "mode", convert every color channel to the numeric OKLCH
-  // basis, adopt any legacy locked-500 anchor as a persisted placement, then
-  // fold a legacy background spot into the base color. The clone is still
-  // pre-basis (hex or already-numeric) on disk.
+  // Structural palette migrations, innermost → outermost: rename Primary→Brand
+  // and Background→Canvas (both key renames, so they precede anything that looks
+  // a palette up by label), drop the gray "mode", convert every color channel to
+  // the numeric OKLCH basis, adopt any legacy locked-500 anchor as a persisted
+  // placement, fold a legacy background spot into the base color, then place any
+  // still-unplaced anchor by base luminance. The clone is still pre-basis (hex
+  // or already-numeric) on disk.
   const raw = structuredClone(theme.editorConfigs ?? {}) as Record<string, PreOklchPaletteConfig>;
-  next.palettes = adoptBackgroundSpotAsBase(adoptLegacyBaseAnchor(migratePaletteColorsToOklch(unifyGrayPalettes(renamePrimaryPaletteKey(raw)))));
+  next.palettes = placeUnplacedBaseAnchors(adoptBackgroundSpotAsBase(adoptLegacyBaseAnchor(migratePaletteColorsToOklch(unifyGrayPalettes(renameBackgroundPaletteKey(renamePrimaryPaletteKey(raw)))))));
   next.fonts.sources = structuredClone(theme.fontSources ?? []);
   next.fonts.stacks  = structuredClone(theme.fontStacks  ?? []);
   const rawVars = runMigrations(
@@ -536,9 +543,7 @@ export function loadFromFile(theme: Theme): void {
   // (or in components' case, vars that wouldn't have been in the theme to
   // begin with).
   for (const load of Object.values(domainLoaders)) load(next, rawVars);
-  next.harmonyAxes = theme.harmonyAxes
-    ? sanitizeHarmonyAxes(theme.harmonyAxes, next.palettes)
-    : axesFromLegacyOrder(theme.harmonyOrder, next.palettes);
+  next.harmonyAxes = sanitizeHarmonyAxes(renameBackgroundHarmonyFamily(theme.harmonyAxes), next.palettes);
   next.cssVars = rawVars;
   resetHistoryForLoad();
   store.set(next);
@@ -564,9 +569,6 @@ export function toTheme(state: EditorState, meta: { name: string }): Theme {
   if (state.shadows.tokens.length > 0) {
     Object.assign(cssVariables, shadowsToVars(state.shadows));
   }
-  // Compat: bound families in axis order for older builds. Omitted when nothing
-  // is bound — an empty legacy list would resurrect the default trio on load.
-  const boundOrder = state.harmonyAxes.filter((a) => a.family !== null).map((a) => a.family!);
   return {
     name: meta.name,
     createdAt: now,
@@ -576,7 +578,6 @@ export function toTheme(state: EditorState, meta: { name: string }): Theme {
     fontSources: state.fonts.sources,
     fontStacks: state.fonts.stacks,
     harmonyAxes: state.harmonyAxes,
-    ...(boundOrder.length > 0 ? { harmonyOrder: boundOrder } : {}),
     schemaVersion: CURRENT_THEME_SCHEMA_VERSION,
   };
 }

package/src/editor/core/themes/migrations/2026-07-29-background-palette-to-canvas.ts

@@ -0,0 +1,41 @@
+/**
+ * Palette family "Background" → "Canvas".
+ *
+ * The family's CSS namespace was always `canvas` (`--color-canvas-*`,
+ * `--surface-canvas-*`), and every other surface that names it — the token
+ * selector, SectionDivider's variant families, the shadows backdrop picker —
+ * said Canvas too. Only the palette label said Background, so the label joins
+ * the namespace rather than the other way round. No token names change.
+ *
+ * The label doubles as a storage key in two places, so this renames both: the
+ * `editorConfigs` map key and any `harmonyAxes` family binding. It has to run
+ * before `sanitizeHarmonyAxes`, which drops families outside `HARMONY_ELIGIBLE`
+ * to `null` and would silently unbind the axis.
+ *
+ * Lives outside the `runMigrations` framework (whose contract is the flat
+ * cssVariables bag) because it transforms structured state, exactly like
+ * `renamePrimaryPaletteKey`, which it composes with in `loadFromFile`. Applied
+ * unconditionally; idempotent (a `Canvas` key already present wins, so a second
+ * run is a no-op) and self-sunsetting once every saved theme has been resaved.
+ */
+
+import type { HarmonyAxis } from '../../palettes/colorHarmony';
+
+const OLD = 'Background';
+const NEW = 'Canvas';
+
+export function renameBackgroundPaletteKey<T>(editorConfigs: Record<string, T>): Record<string, T> {
+  if (!(OLD in editorConfigs)) return editorConfigs;
+  const { [OLD]: legacy, ...rest } = editorConfigs;
+  // A hand-merged file could carry both; the already-renamed key is the newer intent.
+  return NEW in rest ? rest : { ...rest, [NEW]: legacy };
+}
+
+export function renameBackgroundHarmonyFamily(axes: unknown): unknown {
+  if (!Array.isArray(axes)) return axes;
+  return axes.map((axis) =>
+    axis && typeof axis === 'object' && (axis as HarmonyAxis).family === OLD
+      ? { ...(axis as HarmonyAxis), family: NEW }
+      : axis,
+  );
+}

package/src/editor/core/themes/migrations/2026-07-29-place-base-anchors.ts

@@ -0,0 +1,29 @@
+/**
+ * Base-anchor placement for never-edited palettes.
+ *
+ * `anchorToBase` defaults on, but configs saved before placements existed
+ * carry no `anchorPlacement` until the next base-color edit — so their ramps
+ * never show the anchored slot. Place them up front: `syncBaseAnchor` pins the
+ * base color at the step whose curve lightness is nearest the base L.
+ *
+ * Composes outermost in `loadFromFile` — it must run after
+ * `adoptBackgroundSpotAsBase`, which derives the legacy spot color from the
+ * not-yet-pinned curves — and over hydrated session state
+ * (`normalizeBaseAnchors`). Idempotent (skips placed configs) and
+ * self-sunsetting once every saved theme has been resaved with a placement.
+ */
+
+import { syncBaseAnchor } from '../../palettes/paletteDerivation';
+import type { PaletteConfig } from '../themeTypes';
+
+export function placeUnplacedBaseAnchors(
+  editorConfigs: Record<string, PaletteConfig>,
+): Record<string, PaletteConfig> {
+  for (const cfg of Object.values(editorConfigs)) {
+    if (cfg.anchorPlacement !== undefined || cfg.anchorToBase === false) continue;
+    // Disk/storage data: a config missing its basis can't be placed.
+    if (!cfg.baseColor || !cfg.lightnessCurve?.length || !cfg.saturationCurve?.length) continue;
+    syncBaseAnchor(cfg);
+  }
+  return editorConfigs;
+}

package/src/editor/core/themes/themeTypes.ts

@@ -91,11 +91,6 @@ export interface Theme {
   cssVariables: Record<string, string>;
   fontSources?: FontSource[];
   fontStacks?: FontStack[];
-  /**
-   * Deprecated legacy field. Read when `harmonyAxes` is absent; written on save
-   * for older builds.
-   */
-  harmonyOrder?: string[];
   /** Four fixed harmony axes, each owning a hue with an optional bound family. */
   harmonyAxes?: HarmonyAxis[];
   /**

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

@@ -57,21 +57,21 @@
   let partialCoverage = $derived(rec.suggestions.filter((s) => !s.current.coverage.full));
 
   // Shadow the consumed text variables locally with the store-derived values;
-  // the page field is the Background family's SEED, not its derived page step.
+  // the page field is the Canvas family's SEED, not its derived page step.
   let storyVars = $derived(
     ['--text-primary', '--text-secondary', '--text-tertiary', '--text-inverted']
       .concat([...TONES, ...FUNCTIONAL].map((t) => `--text-${t.ns}`))
       .filter((name) => vars[name] !== undefined)
       .map((name) => `${name}: ${vars[name]}`)
-      .concat(`--page-bg: ${seedHex('Background')}`)
+      .concat(`--page-bg: ${seedHex('Canvas')}`)
       .join('; '),
   );
 
-  // Ratios are measured against the DISPLAYED field — the Background seed —
+  // Ratios are measured against the DISPLAYED field — the Canvas seed —
   // so the numbers always describe what the story shows.
   function ratioOnBg(textVar: string): number | null {
     const text = vars[textVar];
-    return typeof text === 'string' ? contrastRatio(text, seedHex('Background')) : null;
+    return typeof text === 'string' ? contrastRatio(text, seedHex('Canvas')) : null;
   }
 
   // Floor, don't round: the readout must never overstate a contrast ratio.
@@ -97,7 +97,7 @@
 <div class="story" style={storyVars}>
   <div class="field">
     <div class="field-head">
-      <span class="field-label">Background</span>
+      <span class="field-label">Canvas</span>
       {#if fmt(bgRatio)}<span class="ratio">{fmt(bgRatio)}</span>{/if}
     </div>
     <p class="body">The dominant surface. Body text sits here.</p>
@@ -125,7 +125,7 @@
         <span class="suggest-entry" class:dim={!s.differs}>
           <span class="fn-dot" style:--dot={s.suggested.hex}></span>
           <span class="suggest-step">{s.step}</span>
-          <span class="ratio">{fmt(contrastRatio(s.suggested.hex, seedHex('Background')))}</span>
+          <span class="ratio">{fmt(contrastRatio(s.suggested.hex, seedHex('Canvas')))}</span>
         </span>
       {/each}
       <label class="bw-toggle" title="Anchor the suggestion at pure white or black instead of the softened extreme">

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

@@ -1,4 +1,6 @@
 <script lang="ts">
+  import { flip } from 'svelte/animate';
+  import { cubicOut } from 'svelte/easing';
   import { oklchToHexClamped } from '../../core/palettes/oklch';
   import { PALETTE_SPECS } from '../../core/palettes/paletteDerivation';
   import { editorState, beginSliderGesture, transaction } from '../../core/store/editorStore';
@@ -13,6 +15,7 @@
   import UIPillButton from '../UIPillButton.svelte';
   import { setBaseColor, setBaseColors, setAxisHues, applySolvedTextCurves } from './paletteBaseColor';
   import { HARMONY_MODE_BUTTONS } from './harmonyModeIcons';
+  import { dockGrow } from '../palette/dockMagnify';
 
   let selected = $state('Brand');
   let activeMode = $state<HarmonyMode>('custom');
@@ -71,14 +74,17 @@
         label: spec.label,
         display: spec.displayLabel ?? spec.label,
         hex: oklchToHexClamped(l, c, h),
+        l,
         onWheel: $editorState.harmonyAxes.some((a, i) => a.family === spec.label && active[i]),
       };
     });
   });
 
   const FUNCTIONAL_FAMILIES = new Set(['Info', 'Success', 'Warning', 'Danger']);
-  let coreSwatches = $derived(swatches.filter((sw) => !FUNCTIONAL_FAMILIES.has(sw.label)));
-  let functionalSwatches = $derived(swatches.filter((sw) => FUNCTIONAL_FAMILIES.has(sw.label)));
+  // Light → dark, matching the palette ramps (white bookend on the left).
+  const byLuminance = (arr: typeof swatches) => [...arr].sort((a, b) => b.l - a.l);
+  let coreSwatches = $derived(byLuminance(swatches.filter((sw) => !FUNCTIONAL_FAMILIES.has(sw.label))));
+  let functionalSwatches = $derived(byLuminance(swatches.filter((sw) => FUNCTIONAL_FAMILIES.has(sw.label))));
 
   let shownModeLabel = $derived(
     HARMONY_MODE_BUTTONS.find((b) => b.mode === (hoverMode ?? activeMode))?.label ?? '',
@@ -163,33 +169,33 @@
 
       <div class="group">
         <span class="eyebrow">Swatches</span>
-        {#snippet swatchButton(sw: (typeof swatches)[number])}
-          <button
-            type="button"
-            class="swatch"
-            class:active={selected === sw.label}
-            style="--swatch-fill: {sw.hex}"
-            title={sw.display}
-            aria-label={`Select ${sw.display}`}
-            aria-pressed={selected === sw.label}
-            onclick={() => select(sw.label)}
-          >
-            <span class="chip"></span>
-            <span class="swatch-label">{sw.label}</span>
-            {#if sw.onWheel}<span class="wheel-dot" title="On the wheel" aria-hidden="true"></span>{/if}
-          </button>
-        {/snippet}
-        <div class="swatch-rows">
-          <div class="swatch-row">
-            {#each coreSwatches as sw (sw.label)}
-              {@render swatchButton(sw)}
-            {/each}
-          </div>
+        {#snippet swatchRow(row: typeof swatches)}
+          {@const selIdx = row.findIndex((sw) => sw.label === selected)}
           <div class="swatch-row">
-            {#each functionalSwatches as sw (sw.label)}
-              {@render swatchButton(sw)}
+            {#each row as sw, i (sw.label)}
+              <button
+                type="button"
+                class="swatch"
+                class:active={selected === sw.label}
+                style="--swatch-fill: {sw.hex}"
+                style:flex-grow={dockGrow(i, selIdx === -1 ? null : selIdx)}
+                title={sw.display}
+                aria-label={`Select ${sw.display}`}
+                aria-pressed={selected === sw.label}
+                onclick={() => select(sw.label)}
+                animate:flip={{ duration: 200, easing: cubicOut }}
+              >
+                <span class="chip">
+                  {#if sw.onWheel}<span class="wheel-dot" title="On the wheel" aria-hidden="true"></span>{/if}
+                </span>
+                <span class="swatch-label">{sw.label}</span>
+              </button>
             {/each}
           </div>
+        {/snippet}
+        <div class="swatch-rows">
+          {@render swatchRow(coreSwatches)}
+          {@render swatchRow(functionalSwatches)}
         </div>
       </div>
 
@@ -438,14 +444,18 @@
     min-width: 0;
   }
 
+  /* Dock magnification, mirroring PaletteStepStrip: the flex-grow transition
+     animates the selected swatch opening while flip walks it to its
+     luminance-sorted spot as lightness is dialed. */
   .swatch-row {
-    display: grid;
-    grid-template-columns: repeat(auto-fill, minmax(4rem, 1fr));
+    display: flex;
+    align-items: flex-end;
     gap: var(--ui-space-8);
   }
 
   .swatch {
-    position: relative;
+    flex: 1 1 0;
+    min-width: 0;
     display: flex;
     flex-direction: column;
     align-items: stretch;
@@ -454,15 +464,26 @@
     background: none;
     border: none;
     cursor: pointer;
+    transition: flex-grow var(--ui-transition-fast);
   }
 
   .chip {
+    position: relative;
     display: block;
     height: 2.75rem;
+    /* Compensating margin: height + margin-top is constant every frame of the
+       magnification, so the row's layout height never dips mid-transition.
+       Chip grows upward, label pinned. */
+    margin-top: 0.5rem;
     border-radius: var(--ui-radius-sm);
     background: var(--swatch-fill);
     border: 1px solid var(--ui-border-low);
-    transition: border-color var(--ui-transition-fast);
+    transition: border-color var(--ui-transition-fast), height var(--ui-transition-fast), margin-top var(--ui-transition-fast);
+  }
+
+  .swatch.active .chip {
+    height: 3.25rem;
+    margin-top: 0;
   }
 
   .swatch:hover .chip {
@@ -497,6 +518,7 @@
     border-radius: var(--ui-radius-full);
     background: var(--ui-text-primary);
     box-shadow: 0 0 0 1.5px var(--ui-surface-lowest);
+    pointer-events: none;
   }
 
   @media (max-width: 1024px) {

package/src/live-tokens/data/themes/default.json

@@ -328,7 +328,7 @@
       "snappedScales": [],
       "anchorToBase": true
     },
-    "Background": {
+    "Canvas": {
       "baseColor": "#3c3c53",
       "lightnessCurve": [
         {