@motion-proto/live-tokens 0.54.2 → 0.55.1

package/CHANGELOG.md

@@ -1,5 +1,72 @@
 # Changelog
 
+## 0.55.1 — The anchored step is the base color
+
+### Fixed
+
+- **Editing the anchored palette step edits the base color.** The anchor pins
+  the lightness, saturation and hue curves through one step, so that swatch was
+  already rendering the base color. Clicking it opened a per-step override,
+  which forked the two apart: the ramp moved, the family's base swatch and hex
+  did not, and the palette stopped passing through the base color the anchor
+  guarantees it passes through. That step now opens the base color itself. The
+  whole ramp re-derives, a bound harmony axis follows the hue, and the header
+  swatch moves with it. Both swatches carry the selection ring together and the
+  panel titles itself "Base Color > 500", so the pairing is stated rather than
+  inferred. An override left on the anchored step by an earlier build is cleared
+  when the step is opened, inside the edit session, so Cancel and undo both put
+  it back. Every other step keeps its own override, unchanged.
+
+### Changed
+
+- **The color editor docks under the row it edits.** It rendered at the bottom
+  of the family block, past the curve editors and the Text, Surfaces and Borders
+  section, far enough from the swatch that opened it to read as unrelated
+  chrome. It now opens directly beneath the ramp for a palette step, or beneath
+  the derived row that owns the step, with a caret on the step's own column. The
+  caret is placed on the grid rather than positioned, so it stays under its
+  swatch at any width. Showing and hiding use the disclosure motion the
+  expandable sections already use.
+
+- **Selection reads by weight.** The editor's chrome is greyscale by design, so
+  a selected swatch is marked by a heavy ring drawn inside it: a white band
+  between two dark keylines, which survives both ends of a ramp running white to
+  black where a single-tone ring disappears at one end. The ring is inset rather
+  than an outline, which would close the gutter between neighbouring swatches,
+  or a thicker border, which would resize the swatch inside its own grid.
+
+## 0.55.0 — A focused palette arrives ready
+
+### Changed
+
+- **A palette focused before mount opens without the reveal.** `paletteEditorOpen`
+  started false and flipped in an effect, so a deep link that set the focus
+  ahead of mount landed the visitor mid-animation, reading as a page still
+  loading. The editor now reads the pending focus when it constructs and opens
+  on the first frame; the scroll that brings it into view jumps rather than
+  gliding, since nothing expanded for the motion to match. A jump from the
+  Colors view, where the editor is already mounted, keeps its reveal.
+
+- **"Base color must appear in palette" moved to the family band.** The toggle
+  sets `anchorToBase`, which is family-level config persisted in the theme,
+  but it sat in the base-colour panel among the controls that edit the colour's
+  *value* — and it only occupied a row of its own because it wrapped out of that
+  panel's title row. It now sits beside the family's name as
+  "Must appear in palette", the swatch alongside supplying the subject the label
+  drops; the full sentence stays as its title. The colour panel closes back up
+  to a title row and its sliders. Collapsed families are untouched: the setting
+  shows only while that family's editor is open, so a page of ten collapsed
+  palettes does not repeat it ten times.
+
+- **The palette band holds two columns at every width.** With the setting on
+  the band's row, a band too narrow for it wrapped the buttons to the left edge,
+  under the swatch. The setting sits in the identity column instead, a third
+  line under the hex — name, value and constraint all describe the family and
+  share its left rail — which leaves the buttons a column of their own that no
+  width takes away. They wrap among themselves against the right edge before the
+  cluster ever drops a line. The swatch keeps its square: the taller column
+  would otherwise stretch the chip into a rectangle.
+
 ## 0.54.2 — Palette focus is public API
 
 ### Added

package/package.json

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

package/src/editor/ui/ColorEditPanel.svelte

@@ -8,6 +8,9 @@
   
   interface Props {
     title?: string | null;
+    /** Ties the panel to the swatch it was opened from, when it renders docked
+     *  beneath that swatch's row. */
+    highlighted?: boolean;
     showRemoveOverride?: boolean;
     /** Hide the confirm/cancel actions for live-apply consumers (Colors view
      *  readout) where edits commit through the store as they happen. */
@@ -37,6 +40,7 @@
 
   let {
     title = null,
+    highlighted = false,
     showRemoveOverride = false,
     hideActions = false,
     hidePreview = false,
@@ -133,7 +137,7 @@
   }
 </script>
 
-<div class="hsl-panel">
+<div class="hsl-panel" class:highlighted>
   <div class="hsl-panel-header">
     {#if !hidePreview}
       <div class="hsl-preview" style="background: {previewHex}"></div>
@@ -250,6 +254,17 @@
     border-radius: var(--ui-radius-md);
   }
 
+  /* Docked to a swatch: the border thickens to the weight of that swatch's
+     selection ring, so the pair reads as one object. */
+  .hsl-panel.highlighted {
+    border-width: 2px;
+    border-color: var(--ui-border-higher);
+  }
+
+  .hsl-panel.highlighted .hsl-panel-title {
+    color: var(--ui-text-primary);
+  }
+
   .hsl-panel-header {
     display: flex;
     align-items: center;

package/src/editor/ui/PaletteEditor.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
   import { onMount, onDestroy, tick } from 'svelte';
+  import { get } from 'svelte/store';
   import { oklchToHexClamped, type Oklch } from '../core/palettes/oklch';
   import { type CurveAnchor, lightnessCurveConfig, saturationCurveConfig, hueCurveConfig } from './curveEngine';
   import ColorEditPanel from './ColorEditPanel.svelte';
@@ -114,7 +115,14 @@
   }
 
   let showDerived = $state(false);
-  let paletteEditorOpen = $state(false);
+  // A deep link sets the focus before this mounts, so the controls are open on
+  // the first frame: UIReveal's `{#if}` never toggles and there is no reveal to
+  // sit through. Landing mid-animation reads as a page still loading.
+  // svelte-ignore state_referenced_locally
+  // The mount-time value is the whole point: a family's label is fixed for the
+  // life of the instance (PALETTE_SPECS keys the `{#each}` by it).
+  const focusedOnMount = get(pendingPaletteFocus) === label;
+  let paletteEditorOpen = $state(focusedOnMount);
   let rootEl: HTMLElement | undefined = $state();
 
   // Arriving from the Colors view's Edit button: open this family's controls and
@@ -123,7 +131,11 @@
     if ($pendingPaletteFocus !== label) return;
     pendingPaletteFocus.set(null);
     paletteEditorOpen = true;
-    tick().then(() => rootEl?.scrollIntoView({ behavior: 'smooth', block: 'start' }));
+    // Nothing expanded when we opened on mount, so there is no motion for a
+    // smooth scroll to match — jump, and the first frame is the final state.
+    tick().then(() =>
+      rootEl?.scrollIntoView({ behavior: focusedOnMount ? 'auto' : 'smooth', block: 'start' }),
+    );
   });
 
   function setLightnessCurve(a: CurveAnchor[]) { edit('lightnessCurve', a); }
@@ -195,8 +207,19 @@
     openSession();
   }
 
-  function handlePaletteClick(ps: { label: string; lightness: number; index: number }) {
+  function handlePaletteClick(ps: { label: string; index: number; anchored: boolean }) {
     const k = paletteStepKey(ps.label);
+    // The anchored step is not a copy of the base color, it IS the base color:
+    // the anchor pins the curves through it. So editing it edits the base, and
+    // the header swatch and the whole ramp follow. An override here would fork
+    // the two apart and quietly break the guarantee the anchor makes.
+    if (ps.anchored) {
+      if (isEditingBase) { confirmEdit(); return; }
+      startBaseEdit();
+      // After openSession, so cancel and undo both put it back.
+      if (k in overrides) removeOverride(k);
+      return;
+    }
     if (editingKey === k) {
       confirmEdit();
       return;
@@ -493,6 +516,10 @@
   let overridesHex = $derived(Object.fromEntries(Object.entries(overrides).map(([k, v]) => [k, toHex(v)])));
 
   let isEditingBase = $derived(isBaseEdit(editing));
+  // Naming the step the base sits on is what says the header swatch and that
+  // ramp swatch are one value, not two that happen to match.
+  let anchoredStep = $derived(paletteComputed.find(ps => ps.anchored) ?? null);
+  let basePanelTitle = $derived(anchoredStep ? `Base Color \u203A ${anchoredStep.label}` : 'Base Color');
   let editingColor = $derived(isEditingBase ? baseColor : editingDraft);
   let editingStepInfo = $derived((() => {
     if (!editingKey || isEditingBase) return null;
@@ -508,11 +535,28 @@
     return null;
   })());
   let panelOpen = $derived(editingKey !== null && (isEditingBase || (editingDraft !== null && editingStepInfo !== null)));
-  let editPanelTitle = $derived(isEditingBase
-    ? 'Base Color'
-    : editingStepInfo
-      ? `${editingStepInfo.scale} \u203A ${editingStepInfo.step}`
-      : null);
+  // The panel docks under the row that owns the step being edited, so these
+  // place it: a column for the palette caret, a row slot for the derived scales.
+  let editingPaletteIndex = $derived.by(() => {
+    if (!panelOpen || isEditingBase) return null;
+    const i = paletteComputed.findIndex(ps => ps.key === editingKey);
+    return i === -1 ? null : i;
+  });
+  let editingDerivedRow = $derived.by(() => {
+    if (!panelOpen || isEditingBase || editingPaletteIndex !== null) return null;
+    const scale = scales.find(s => s.title === editingStepInfo?.scale);
+    if (!scale) return null;
+    return scale.isText ? 'text' : 'solid';
+  });
+  let editPanelTitle = $derived(editingStepInfo ? `${editingStepInfo.scale} \u203A ${editingStepInfo.step}` : null);
+  // The reveal's outro needs something to render: closing the panel resets
+  // `editing` to idle, and every value below it goes null in the same tick, so a
+  // live read would slide an empty box shut. Held until the next edit replaces it.
+  let dock: { title: string | null; color: Oklch; paletteIndex: number | null } | null = $state(null);
+  $effect(() => {
+    if (!panelOpen || isEditingBase || !editingColor) return;
+    dock = { title: editPanelTitle, color: editingColor, paletteIndex: editingPaletteIndex };
+  });
   $effect(() => {
     // Touch each input so the effect tracks them (resnapScales reads indirectly).
     void baseColor;
@@ -525,6 +569,24 @@
   });
 </script>
 
+{#snippet stepEditPanel()}
+  {#if dock}
+    <ColorEditPanel
+      title={dock.title}
+      highlighted
+      showRemoveOverride
+      hue={dock.color.h}
+      chroma={dock.color.c}
+      lightness={dock.color.l * 100}
+      onHueChromaChange={(h, c, l) => handleColorChange({ l: l / 100, c, h })}
+      onConfirm={confirmEdit}
+      onCancel={cancelEdit}
+      onRemoveOverride={() => editingKey && removeOverride(editingKey)}
+      onSliderStart={() => beginSliderGesture(`edit ${label} ${editingKey ?? 'color'}`)}
+    />
+  {/if}
+{/snippet}
+
 <div class="palette-editor" bind:this={rootEl} style="--editor-base: {toHex(baseColor)}">
   <PaletteBase
     {label}
@@ -532,10 +594,23 @@
     {baseColor}
     {isEditingBase}
     pinnedOpen={paletteEditorOpen}
+    selected={isEditingBase}
     {copiedKey}
     onStartEdit={startBaseEdit}
     onCopyBaseHex={copyHex}
   >
+    {#snippet setting()}
+      <!-- The family's own swatch and name sit alongside, so the label drops
+           its subject; the title carries the full sentence. -->
+      <span class="base-anchor-toggle" title="Base color must appear in palette">
+        <Toggle
+          checked={anchorToBase}
+          onchange={(v) => setAnchorToBase(v ?? !anchorToBase)}
+          label="Must appear in palette"
+        />
+      </span>
+    {/snippet}
+
     {#snippet actions()}
       <PaletteJumpButton family={label} {displayLabel} target="wheel" />
       <UIPillButton size="compact" variant="outline" onclick={clearPaletteOverrides}>Clear Overrides</UIPillButton>
@@ -549,7 +624,7 @@
     <div class="swatch-grid" style="--swatch-cols: {paletteStepLightness.length + 2}">
       <div class="base-panel" style="grid-column: 2 / {paletteStepLightness.length + 2}">
         <ColorEditPanel
-          title={isEditingBase ? editPanelTitle : 'Base Color'}
+          title={basePanelTitle}
           showRemoveOverride={false}
           hideActions={!isEditingBase}
           hidePreview
@@ -563,18 +638,7 @@
           onCancel={cancelEdit}
           onRemoveOverride={() => {}}
           onSliderStart={() => beginSliderGesture(`edit ${label} base`)}
-        >
-          {#snippet actions()}
-            <div class="base-anchor-toggle">
-              <Toggle
-                checked={anchorToBase}
-                onchange={(v) => setAnchorToBase(v ?? !anchorToBase)}
-                label="Base color must appear in palette"
-                labelFirst
-              />
-            </div>
-          {/snippet}
-        </ColorEditPanel>
+        />
       </div>
     </div>
   </UIReveal>
@@ -604,21 +668,21 @@
         </div>
         {#each paletteComputed as ps}
           <div class="step-column">
-            <button class="step-label copyable-label" class:copied={copiedLabelKey === ps.key} type="button" onclick={(e) => copyVarName(ps.key, `--color-${cssNamespace}-${ps.label}`, e)}>
+            <button class="step-label copyable-label" class:copied={copiedLabelKey === ps.key} class:selected={editingKey === ps.key || (isEditingBase && ps.anchored)} type="button" onclick={(e) => copyVarName(ps.key, `--color-${cssNamespace}-${ps.label}`, e)}>
               {copiedLabelKey === ps.key ? 'copied!' : ps.label}
             </button>
             <!-- svelte-ignore a11y_no_noninteractive_tabindex -->
             <div
               class="swatch gray-swatch"
-              class:active={editingKey === ps.key}
+              class:active={editingKey === ps.key || (isEditingBase && ps.anchored)}
               class:overridden={ps.key in overrides}
               class:anchored={ps.anchored}
               title={ps.anchored ? 'Base color' : undefined}
               style="background: {ps.effective}"
-              onclick={() => handlePaletteClick({ label: ps.label, lightness: ps.lightness, index: ps.index })}
+              onclick={() => handlePaletteClick(ps)}
               role="button"
               tabindex="0"
-              onkeydown={(e) => e.key === 'Enter' && handlePaletteClick({ label: ps.label, lightness: ps.lightness, index: ps.index })}
+              onkeydown={(e) => e.key === 'Enter' && handlePaletteClick(ps)}
             >
               {#if ps.key in overrides}
                 <span class="override-lock" title="Palette override: this step is set by hand, not derived from the curve">
@@ -640,6 +704,17 @@
           </button>
           <div class="swatch gray-swatch bookend" style="background: #000000"></div>
         </div>
+
+        <UIReveal open={editingPaletteIndex !== null} style="grid-column: 2 / {paletteStepLightness.length + 2}">
+          <!-- The reveal has to own the grid slot, so the dock rebuilds the
+               ramp's tracks inside it: the caret is then placed on the step's
+               own column and points at it at any width, no arithmetic. -->
+          <div class="dock" style="--dock-cols: {paletteStepLightness.length}">
+            <div class="edit-caret" style="grid-column: {(dock?.paletteIndex ?? 0) + 1}"></div>
+            <div class="docked-panel">{@render stepEditPanel()}</div>
+          </div>
+        </UIReveal>
+
       <UIReveal open={paletteEditorOpen} style="grid-column: 2 / {paletteStepLightness.length + 2}">
         <div class="curve-grid-span">
           {#if anchorUnlockPrompt && anchorToBase}
@@ -774,29 +849,19 @@
           {@render overridesPanel(scale, true, derivedHexForBase)}
         {/each}
       </div>
+      <UIReveal open={editingDerivedRow === 'text'}>
+        <div class="docked-panel">{@render stepEditPanel()}</div>
+      </UIReveal>
       <div class="scales-row">
         {#each scales.filter(s => !s.isText) as scale}
           {@render overridesPanel(scale, true, derivedHexForBase)}
         {/each}
       </div>
+      <UIReveal open={editingDerivedRow === 'solid'}>
+        <div class="docked-panel">{@render stepEditPanel()}</div>
+      </UIReveal>
     </div>
   </UIReveal>
-
-  <!-- Color Edit Panel (non-base edits) -->
-  {#if !isEditingBase && panelOpen && editingColor}
-    <ColorEditPanel
-      title={editPanelTitle}
-      showRemoveOverride={!!editingKey}
-      hue={editingColor.h}
-      chroma={editingColor.c}
-      lightness={editingColor.l * 100}
-      onHueChromaChange={(h, c, l) => handleColorChange({ l: l / 100, c, h })}
-      onConfirm={confirmEdit}
-      onCancel={cancelEdit}
-      onRemoveOverride={() => editingKey && removeOverride(editingKey)}
-      onSliderStart={() => beginSliderGesture(`edit ${label} ${editingKey ?? 'color'}`)}
-    />
-  {/if}
 </div>
 
 <style>
@@ -924,6 +989,12 @@
     color: var(--ui-text-accent, var(--ui-text-primary));
   }
 
+  /* The name the docked panel's title repeats back. */
+  .step-label.copyable-label.selected {
+    color: var(--ui-text-primary);
+    font-weight: var(--ui-font-weight-semibold);
+  }
+
   /* Swatches */
 
   .swatch {
@@ -988,8 +1059,10 @@
     min-width: 0;
   }
 
+  /* A box of its own so the title has something to hover; placement in the
+     band belongs to PaletteBase. */
   .base-anchor-toggle {
-    margin-left: auto;
+    display: flex;
   }
 
   .curve-grid-span {
@@ -998,6 +1071,34 @@
     gap: var(--ui-space-8);
   }
 
+  /* Same tracks and gutter as the ramp above, so a column here lands under the
+     swatch of the same index. */
+  .dock {
+    display: grid;
+    grid-template-columns: repeat(var(--dock-cols), minmax(0, 1fr));
+    gap: var(--ui-space-4) var(--swatch-gap, var(--ui-space-4));
+  }
+
+  /* Docked under the row it edits, pointed at the swatch it edits. */
+  .docked-panel {
+    grid-column: 1 / -1;
+    min-width: 0;
+  }
+
+  .edit-caret {
+    display: flex;
+    justify-content: center;
+    align-items: flex-end;
+    height: var(--ui-space-6);
+  }
+
+  .edit-caret::after {
+    content: '';
+    border-left: var(--ui-space-6) solid transparent;
+    border-right: var(--ui-space-6) solid transparent;
+    border-bottom: var(--ui-space-6) solid var(--ui-border-higher);
+  }
+
   .anchor-unlock-notice {
     display: flex;
     align-items: center;
@@ -1042,10 +1143,17 @@
     border-color: var(--ui-border-high);
   }
 
-  .swatch.gray-swatch.active {
-    border-color: var(--ui-border-higher);
-    outline: 2px solid var(--ui-border-high);
-    outline-offset: 1px;
+  /* A ring drawn inside the swatch, weight only: the editor stays greyscale, so
+     selection has to out-weigh the anchored step's emphasized border rather
+     than out-colour it. Insets, because a 3px outline would eat the column gap
+     and a 3px border would resize the swatch mid-grid. The dark keylines either
+     side of the white band keep it legible at both ends of the ramp. */
+  .swatch.gray-swatch.active,
+  .swatch.gray-swatch.anchored.active {
+    border-color: var(--ui-surface-lowest);
+    box-shadow:
+      inset 0 0 0 3px var(--ui-text-primary),
+      inset 0 0 0 4px var(--ui-surface-lowest);
   }
 
   /* The step the base color is placed at: taller, with an emphasized border. It

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

@@ -424,9 +424,12 @@
     border-color: var(--ui-border-high);
   }
 
+  /* Same weight-only selection language as the palette ramp, at the smaller
+     swatch's scale. */
   .override-slot.active {
-    border-color: var(--ui-border-higher);
-    outline: 1px solid var(--ui-border-high);
+    border-style: solid;
+    border-color: var(--ui-surface-lowest);
+    outline: 2px solid var(--ui-text-primary);
     outline-offset: 1px;
   }
 

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

@@ -14,10 +14,16 @@
     isEditingBase: boolean;
     /** Keep the swatch reading as active while the curve editors are visible. */
     pinnedOpen?: boolean;
+    /** The same ring the ramp's anchored step wears, so the two swatches read
+     *  as the one value they are. */
+    selected?: boolean;
     copiedKey: string | null;
     onStartEdit: () => void;
     onCopyBaseHex: (key: string, hex: string, event?: MouseEvent) => void;
     actions?: Snippet;
+    /** A family-level setting, shown beside the name while this family's
+     *  editor is open. Collapsed families keep the band to identity + actions. */
+    setting?: Snippet;
   }
 
   let {
@@ -26,13 +32,19 @@
     baseColor,
     isEditingBase,
     pinnedOpen = false,
+    selected = false,
     copiedKey,
     onStartEdit,
     onCopyBaseHex,
-    actions
+    actions,
+    setting
   }: Props = $props();
 
   let baseHex = $derived(oklchToHexClamped(baseColor.l, baseColor.c, baseColor.h));
+
+  // `pinnedOpen || isEditingBase` is exactly when the base panel shows: editing
+  // the base implies both a panel and a colour to put in it.
+  let showSetting = $derived(!!setting && (pinnedOpen || isEditingBase));
 </script>
 
 <div class="editor-top">
@@ -41,6 +53,7 @@
     <div
       class="header-swatch"
       class:active={isEditingBase || pinnedOpen}
+      class:selected
       style="background: {baseHex}"
       onclick={onStartEdit}
       role="button"
@@ -64,6 +77,10 @@
           aria-hidden="true"
         ></i>
       </button>
+
+      {#if showSetting}
+        <div class="header-setting">{@render setting?.()}</div>
+      {/if}
     </div>
   </div>
 
@@ -100,12 +117,28 @@
   .header-actions {
     display: flex;
     align-items: center;
+    flex-wrap: wrap;
+    justify-content: flex-end;
     gap: var(--ui-space-8);
   }
 
+  /* Third line of the identity, under the hex: name, value, constraint all
+     describe the family and share its left rail. Keeping it out of the band's
+     row is what leaves the buttons a column of their own at every width. */
+  .header-setting {
+    display: flex;
+    align-items: center;
+    margin-top: var(--ui-space-4);
+  }
+
+  /* The setting makes the identity column taller than the swatch, and the row
+     stretches its items; left alone the chip would grow into a rectangle. It is
+     a colour sample, so it stays square and hangs from the top of the column. */
   .header-swatch {
     width: 4.5rem;
     min-height: 4.5rem;
+    aspect-ratio: 1;
+    align-self: flex-start;
     border-radius: var(--ui-radius-md);
     border: 2px solid var(--ui-border);
     flex-shrink: 0;
@@ -122,6 +155,14 @@
     outline-offset: 1px;
   }
 
+  .header-swatch.selected {
+    border-color: var(--ui-surface-lowest);
+    outline: none;
+    box-shadow:
+      inset 0 0 0 3px var(--ui-text-primary),
+      inset 0 0 0 4px var(--ui-surface-lowest);
+  }
+
   .editor-label {
     font-size: var(--ui-font-size-xl);
     font-weight: var(--ui-font-weight-semibold);