@motion-proto/live-tokens 0.43.0 → 0.45.0

package/CHANGELOG.md

@@ -1,5 +1,96 @@
 # Changelog
 
+## 0.45.0 — The Color Story shows the tokens you actually have
+
+### Fixed
+
+- **The Color Story's text steps read the live tokens.** The primary, secondary
+  and tertiary row rendered the values the *Even neutral steps* pill would have
+  written, not the current ones, so the same step could report two different
+  ratios in the same frame (the Canvas header said 17.9:1 while the row said
+  14.7:1). Each step now resolves `--text-primary` / `--text-secondary` /
+  `--text-tertiary` through the same path the functional chips and tone pills
+  already used, renders in its own token, and reports its real contrast against
+  the canvas.
+
+### Removed
+
+- **The Color Story's action pills.** *Raise all text to AA*, *Even neutral
+  steps*, and the *Anchor at pure white/black* toggle, added in 0.44.0, are
+  gone. The story is a proportional preview, and authoring text steps from it
+  put a second palette editor next to the real one. Text steps are edited in
+  the Tokens view.
+
+- **The text-contrast solvers.** `solveTextContrast.ts` and `recommendText.ts`
+  (plus `applySolvedTextCurves` and `applySuggestedNeutralText`) backed only
+  those pills and are deleted. Both were internal to `src/editor/core/palettes/`
+  and never reachable through the package exports, so no consumer import
+  changes. `BW_GUARD_MIN_L` / `BW_GUARD_MAX_L` are unaffected: they live in
+  `paletteDerivation.ts` and still guard derived inverted text.
+
+### Changed
+
+- **The story's prose lines and its unlabeled header ratio are gone.** The three
+  sentences under Canvas ("The dominant surface. Body text sits here." and its
+  two siblings) said nothing the labelled steps don't, and the ratio beside the
+  Canvas heading was primary's, measured but never named. The stacked steps
+  carry all three ratios now.
+
+## 0.44.0 — Every text step derives to body contrast
+
+### Added
+
+- **A full-page Colors route.** `/live-tokens/colors` renders the Colors editor
+  as its own page, alongside the existing editor and components routes, and is
+  auto-appended to the dev nav rail. New `@motion-proto/live-tokens/colors`
+  export for consumers mounting it themselves, and a new `colors` key on
+  `editorRoutes` to relocate it or pass `false` to disable it. Entering the
+  route flips the overlay off its Colors view so the two surfaces never stack.
+
+### Changed
+
+- **Selection reads across every Colors surface.** Picking a family used to
+  highlight only its swatch. Its harmony-axis row and chip now light up, and on
+  the wheel its rail thickens to full contrast while its axis numeral goes
+  white and the others step back. Axis chips are clickable to select.
+
+- **The Color Story is a readout, not a control panel.** Its "Use suggested"
+  button and "Use black and white" checkbox moved out to three pills above the
+  story: *Raise all text to AA* (every family, contrast-first), *Even neutral
+  steps* (Neutral only, hierarchy-first), and an *Anchor at pure white/black*
+  toggle. The old labels named neither the scope nor the effect, which are what
+  separate the two actions; each pill now carries the full explanation on hover.
+  The AA-reach line is gone.
+
+- **Color swatches hold their position.** Both swatch rows were sorted by
+  luminance, so editing a color's lightness reshuffled the row under the
+  pointer and stuttered mid-drag. They render in declaration order now.
+
+- **`--text-muted` now derives to 4.5:1, not 3:1.** The neutral text ramp
+  guaranteed muted at the WCAG AA floor for *large* text, one step below
+  `--text-tertiary`, on the assumption it would only ever be set at 24px (or
+  18.66px bold). Nothing in the token's name or its position in a ramp of text
+  colors carried that condition, so consumers reached for it as a quiet body
+  color and shipped text below AA — in the first site audited, all eleven uses
+  were 13–16px, every one of them failing. `--text-muted` joins primary,
+  secondary and tertiary on the 4.5:1 body floor, which leaves `--text-disabled`
+  as the ramp's only sub-AA step, and WCAG 1.4.3 exempts disabled controls.
+  `AA_LARGE` is unchanged and still floors the graded chromatic steps.
+
+  Derived palettes get a lighter (dark scheme) or darker (light scheme) muted
+  step the next time text contrast is solved. **A theme already on disk keeps
+  its stored curve** — its `--text-muted` does not move until the palette is
+  re-solved, so a consuming site that has shipped muted on small text must
+  either re-derive or restate those colors itself.
+
+  Expect muted and tertiary to derive to nearly the same color: both target the
+  default surface, so both settle just past the same floor (on the reference
+  dark palette, tertiary `#94999c` 4.58:1 and muted `#96989a` 4.55:1). That is
+  arithmetic, not a rough edge — a step quieter than tertiary cannot also clear
+  tertiary's floor. Treat `--text-muted` as an alias of `--text-tertiary` for
+  now; reach for `--text-disabled` when a genuinely quieter, non-AA step is
+  wanted, and expect a decision on deprecating one of the two.
+
 ## 0.43.0 — The editor opens on Tokens
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motion-proto/live-tokens",
-  "version": "0.43.0",
+  "version": "0.45.0",
   "type": "module",
   "description": "Design token editor with live CSS variable editing. Svelte 5 + Vite 8.",
   "keywords": [
@@ -65,6 +65,11 @@
       "svelte": "./src/editor/pages/ComponentEditorPage.svelte",
       "default": "./src/editor/pages/ComponentEditorPage.svelte"
     },
+    "./colors": {
+      "types": "./src/editor/pages/ColorsPage.svelte.d.ts",
+      "svelte": "./src/editor/pages/ColorsPage.svelte",
+      "default": "./src/editor/pages/ColorsPage.svelte"
+    },
     "./docs": {
       "types": "./src/editor/docs/Docs.svelte.d.ts",
       "svelte": "./src/editor/docs/Docs.svelte",

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

@@ -104,8 +104,7 @@ export const SCALES: readonly Scale[] = [
 ];
 
 /** Guard band for derived near-black/near-white text: values stay between
- *  ≈ #111 and ≈ #e8e8e8 unless pure black/white is opted into. The AA floor
- *  beats the guard (see `recommendText.ts`). */
+ *  ≈ #111 and ≈ #e8e8e8, the range most designers prefer over pure extremes. */
 export const BW_GUARD_MIN_L = 0.17;
 export const BW_GUARD_MAX_L = 0.93;
 

package/src/editor/core/routing/ownedRoutes.ts

@@ -8,4 +8,5 @@
 // <LiveTokensRouter>; these are only the defaults.
 export const DEFAULT_EDITOR_PATH = '/live-tokens/editor';
 export const DEFAULT_COMPONENTS_PATH = '/live-tokens/components';
+export const DEFAULT_COLORS_PATH = '/live-tokens/colors';
 export const DEFAULT_DOCS_PATH = '/live-tokens/docs';

package/src/editor/overlay/LiveEditorOverlay.svelte

@@ -15,7 +15,7 @@
   import { fade } from 'svelte/transition';
   import { cubicInOut } from 'svelte/easing';
   import { route, navigate } from '../core/routing/router';
-  import { DEFAULT_EDITOR_PATH, DEFAULT_COMPONENTS_PATH } from '../core/routing/ownedRoutes';
+  import { DEFAULT_EDITOR_PATH, DEFAULT_COMPONENTS_PATH, DEFAULT_COLORS_PATH } from '../core/routing/ownedRoutes';
   import { editorView } from '../core/store/editorViewStore';
   import { columnsVisible, toggleColumns } from './columnsOverlay';
   import { storageKey } from '../core/store/editorConfig';
@@ -29,6 +29,7 @@
     open?: boolean | undefined;
     editorPath?: string;
     componentsPath?: string;
+    colorsPath?: string;
     navLinks?: NavLink[];
     pageSources?: Record<string, string>;
     hidePageSourceOn?: string[];
@@ -39,6 +40,7 @@
     open = $bindable(undefined),
     editorPath = DEFAULT_EDITOR_PATH,
     componentsPath = DEFAULT_COMPONENTS_PATH,
+    colorsPath = DEFAULT_COLORS_PATH,
     navLinks = [],
     pageSources = {},
     hidePageSourceOn = [],
@@ -65,9 +67,9 @@
     overlayOpen.set(!!open);
   });
 
-  // The components route renders the same component-editor surface as the
-  // overlay's components view. Pair them: on entering it, flip the overlay to
-  // tokens so the two surfaces don't stack. Fires only on route
+  // The components and colors routes render the same surfaces as the overlay's
+  // components and colors views. Pair them: on entering one, flip the overlay
+  // to tokens so the two surfaces don't stack. Fires only on route
   // change, not on every editorView change — otherwise cross-window storage
   // sync re-triggers the rule, which writes editorView, which fires another
   // storage event, which fires the rule again. The result is heavy re-render
@@ -81,6 +83,9 @@
     if (r === componentsPath) {
       editorView.update((v) => (v === 'components' ? 'tokens' : v));
     }
+    if (r === colorsPath) {
+      editorView.update((v) => (v === 'colors' ? 'tokens' : v));
+    }
   });
 
   // Editor route has its own chrome — hide overlay there.

package/src/editor/overlay/LiveTokensRouter.svelte

@@ -30,20 +30,22 @@
   /**
    * Override the package's dev-only routes, which default to the reserved
    * `/live-tokens/*` namespace (`/live-tokens/editor`, `/live-tokens/components`,
-   * `/live-tokens/docs`) so they never collide with consumer pages. Pass a
-   * string to relocate a route; pass `false` to disable it entirely (no
-   * dispatch and, for `components`/`docs`, no auto-injected nav-rail entry).
+   * `/live-tokens/colors`, `/live-tokens/docs`) so they never collide with
+   * consumer pages. Pass a string to relocate a route; pass `false` to disable
+   * it entirely (no dispatch and, for `components`/`colors`/`docs`, no
+   * auto-injected nav-rail entry).
    */
   export interface EditorRouteOverrides {
     editor?: string | false;
     components?: string | false;
+    colors?: string | false;
     docs?: string | false;
   }
 
   /**
    * Resolve a path to the single entry that renders it. Precedence, after the
-   * package-owned `/live-tokens/*` routes (editor, components, docs) have
-   * already been matched by the component:
+   * package-owned `/live-tokens/*` routes (editor, components, colors, docs)
+   * have already been matched by the component:
    *
    *   1. `pages[route]` — exact static match.
    *   2. `resolve(route)` — consumer code, where params / prefixes / gating
@@ -68,7 +70,7 @@
   import LiveEditorOverlay from './LiveEditorOverlay.svelte';
   import ColumnsOverlay from './ColumnsOverlay.svelte';
   import { route, navigate } from '../core/routing/router';
-  import { DEFAULT_EDITOR_PATH, DEFAULT_COMPONENTS_PATH, DEFAULT_DOCS_PATH } from '../core/routing/ownedRoutes';
+  import { DEFAULT_EDITOR_PATH, DEFAULT_COMPONENTS_PATH, DEFAULT_COLORS_PATH, DEFAULT_DOCS_PATH } from '../core/routing/ownedRoutes';
 
   interface Props {
     pages: Record<string, RouteEntry>;
@@ -86,32 +88,38 @@
 
   let editorEnabled = $derived(editorRoutes.editor !== false);
   let componentsEnabled = $derived(editorRoutes.components !== false);
+  let colorsEnabled = $derived(editorRoutes.colors !== false);
   let docsEnabled = $derived(editorRoutes.docs !== false);
   let editorPath = $derived(typeof editorRoutes.editor === 'string' ? editorRoutes.editor : DEFAULT_EDITOR_PATH);
   let componentsPath = $derived(typeof editorRoutes.components === 'string' ? editorRoutes.components : DEFAULT_COMPONENTS_PATH);
+  let colorsPath = $derived(typeof editorRoutes.colors === 'string' ? editorRoutes.colors : DEFAULT_COLORS_PATH);
   let docsPath = $derived(typeof editorRoutes.docs === 'string' ? editorRoutes.docs : DEFAULT_DOCS_PATH);
 
   const isDev = import.meta.env.DEV;
   let isEditor = $derived(isDev && editorEnabled && $route === editorPath);
   let isComponentEditor = $derived(isDev && componentsEnabled && $route === componentsPath);
+  let isColors = $derived(isDev && colorsEnabled && $route === colorsPath);
   let isDocs = $derived(isDev && docsEnabled && $route === docsPath);
 
   // The single entry that renders the current route. Owned routes are handled
-  // by the isEditor/isComponentEditor/isDocs branches, so they resolve to null
-  // here; everything else flows through resolveRoute and drives both dispatch
-  // (component + props) and page-source from this one value.
+  // by the isEditor/isComponentEditor/isColors/isDocs branches, so they resolve
+  // to null here; everything else flows through resolveRoute and drives both
+  // dispatch (component + props) and page-source from this one value.
   let resolvedEntry = $derived(
-    isEditor || isComponentEditor || isDocs ? null : resolveRoute(pages, resolve, $route),
+    isEditor || isComponentEditor || isColors || isDocs ? null : resolveRoute(pages, resolve, $route),
   );
 
   // Pages with a label show up in the nav rail, in declaration order. In dev,
-  // the components-editor and docs routes are auto-appended so they're reachable
-  // from every page. Docs ship from the package, so consumers reference the
-  // guide in the editor while building without vendoring a copy.
+  // the colors, components-editor, and docs routes are auto-appended so they're
+  // reachable from every page. Docs ship from the package, so consumers
+  // reference the guide in the editor while building without vendoring a copy.
   let navLinks = $derived([
     ...Object.entries(pages)
       .filter(([, e]) => !!e.label)
       .map(([path, e]) => ({ path, label: e.label!, icon: e.icon ?? '' })),
+    ...(isDev && colorsEnabled
+      ? [{ path: colorsPath, label: 'Colors', icon: 'fa-palette' }]
+      : []),
     ...(isDev && componentsEnabled
       ? [{ path: componentsPath, label: 'Components', icon: 'fa-puzzle-piece' }]
       : []),
@@ -132,14 +140,15 @@
     ...(resolvedEntry?.source ? { [$route]: resolvedEntry.source } : {}),
   });
 
-  // The package-owned components and docs routes hide the page-source button
-  // (no consumer source file backs them).
+  // The package-owned components, colors, and docs routes hide the page-source
+  // button (no consumer source file backs them).
   let hidePageSourceOn = $derived([
     ...Object.entries(pages)
       .filter(([, e]) => e.hidePageSource)
       .map(([path]) => path),
     ...(resolvedEntry?.hidePageSource ? [$route] : []),
     ...(componentsEnabled ? [componentsPath] : []),
+    ...(colorsEnabled ? [colorsPath] : []),
     ...(docsEnabled ? [docsPath] : []),
   ]);
 
@@ -150,6 +159,7 @@
   let pagePromise = $derived.by(() => {
     if (isEditor) return import('../pages/Editor.svelte');
     if (isComponentEditor) return import('../pages/ComponentEditorPage.svelte');
+    if (isColors) return import('../pages/ColorsPage.svelte');
     if (isDocs) return import('../docs/Docs.svelte');
     const entry = resolvedEntry;
     if (!entry) return Promise.resolve({ default: null as unknown as Component<any, any, any> });
@@ -177,9 +187,10 @@
   class="lt-app"
   class:is-editor={isEditor}
   class:is-component-editor={isComponentEditor}
+  class:is-colors={isColors}
   onclick={handleClick}
 >
-  <LiveEditorOverlay {navLinks} {pageSources} {hidePageSourceOn} {editorPath} {componentsPath} />
+  <LiveEditorOverlay {navLinks} {pageSources} {hidePageSourceOn} {editorPath} {componentsPath} {colorsPath} />
   <ColumnsOverlay />
 
   {#await pagePromise then m}
@@ -210,7 +221,8 @@
     padding-right: var(--lt-overlay-scroll-pad, 0px);
   }
 
-  .lt-app.is-editor {
+  .lt-app.is-editor,
+  .lt-app.is-colors {
     padding-bottom: 0;
     background: black;
   }

package/src/editor/pages/ColorsPage.svelte

@@ -0,0 +1,117 @@
+<script lang="ts">
+  import { onMount } from 'svelte';
+  import ColorsTab from '../ui/colors/ColorsTab.svelte';
+  import UICopyPopover from '../ui/UICopyPopover.svelte';
+  import { installEditorKeybindings } from '../core/store/editorKeybindings';
+  import { initializeEditorStore } from '../core/store/editorStore';
+  import { storageKey } from '../core/store/editorConfig';
+  import { DEFAULT_COLORS_PATH } from '../core/routing/ownedRoutes';
+  // Editor chrome + form controls + icon font must be JS imports (not @import
+  // inside the style block) so Vite resolves them via the module graph
+  // regardless of how the consumer compiles Svelte CSS (external ?lang.css vs
+  // injected); otherwise the @import URLs leak to the browser and 404 against
+  // the consumer's root.
+  import '../styles/ui-editor.css';
+  import '../styles/ui-form-controls.css';
+  import '@fortawesome/fontawesome-free/css/all.min.css';
+
+  // Where "Back to site" sends the user. Prefer the previous non-colors entry
+  // from session history; fall back to home.
+  const backHref = pickBackHref();
+
+  function pickBackHref(): string {
+    try {
+      const prev = sessionStorage.getItem(storageKey('prev-route'));
+      if (prev && prev !== DEFAULT_COLORS_PATH) return prev;
+    } catch {
+      // ignore
+    }
+    return '/';
+  }
+
+  onMount(() => {
+    initializeEditorStore();
+    return installEditorKeybindings();
+  });
+</script>
+
+<!-- .editor-page scopes the --ui-* token definitions from ui-editor.css. -->
+<div class="editor-page colors-page">
+  <div class="page-bar">
+    <div class="bar-left">
+      <a href={backHref} class="back-link">
+        <i class="fas fa-arrow-left"></i>
+        <span>Back to site</span>
+      </a>
+      <span class="page-label">Colors</span>
+    </div>
+  </div>
+
+  <main class="content">
+    <ColorsTab />
+  </main>
+  <UICopyPopover />
+</div>
+
+<style>
+  .colors-page {
+    min-height: 100vh;
+    background: black;
+  }
+
+  .page-bar {
+    display: flex;
+    align-items: center;
+    gap: var(--ui-space-16);
+    padding: var(--ui-space-10) var(--ui-space-16);
+    background: black;
+    border-bottom: 1px solid var(--ui-border-low);
+    min-height: 52px;
+  }
+
+  .bar-left {
+    display: flex;
+    align-items: center;
+    gap: var(--ui-space-16);
+    min-width: 0;
+  }
+
+  .back-link {
+    display: flex;
+    align-items: center;
+    gap: var(--ui-space-6);
+    color: var(--ui-text-tertiary);
+    text-decoration: none;
+    font-size: var(--ui-font-size-md);
+    transition: color var(--ui-transition-fast);
+  }
+
+  .back-link:hover {
+    color: var(--ui-text-primary);
+  }
+
+  .page-label {
+    font-size: var(--ui-font-size-md);
+    font-weight: var(--ui-font-weight-semibold);
+    color: var(--ui-text-secondary);
+  }
+
+  .content {
+    max-width: 1680px;
+    margin: 0 auto;
+    padding: var(--ui-space-24) var(--ui-space-32);
+    isolation: isolate;
+  }
+
+  @media (max-width: 1280px) {
+    .content {
+      padding: var(--ui-space-20) var(--ui-space-20);
+    }
+  }
+
+  @media (max-width: 1024px) {
+    .content {
+      padding: var(--ui-space-16) var(--ui-space-12);
+    }
+  }
+</style>

package/src/editor/pages/ColorsPage.svelte.d.ts

@@ -0,0 +1,2 @@
+import { SvelteComponent } from 'svelte';
+export default class ColorsPage extends SvelteComponent<Record<string, never>> {}

package/src/editor/ui/EditorViewSwitcher.svelte

@@ -1,7 +1,7 @@
 <script lang="ts">
   import { editorView, type EditorView } from '../core/store/editorViewStore';
   import { parentRoute } from '../core/routing/parentRouteStore';
-  import { DEFAULT_COMPONENTS_PATH } from '../core/routing/ownedRoutes';
+  import { DEFAULT_COMPONENTS_PATH, DEFAULT_COLORS_PATH } from '../core/routing/ownedRoutes';
 
   interface Props {
     condensed?: boolean;
@@ -9,16 +9,17 @@
 
   let { condensed = false }: Props = $props();
 
-  // On the components route the host page is already the components editor —
-  // the overlay's components view would just stack on top, so disable the
-  // switch. The switcher renders inside the editor iframe, so we read the
-  // *parent* route, not this iframe's own. Compares the default path:
-  // editorRoutes.components relocation isn't plumbed across the iframe, so a
-  // relocated route won't disable the switch.
+  // On the components or colors route the host page already renders that
+  // surface — the overlay's matching view would just stack on top, so disable
+  // the switch. The switcher renders inside the editor iframe, so we read the
+  // *parent* route, not this iframe's own. Compares the default paths:
+  // editorRoutes relocation isn't plumbed across the iframe, so a relocated
+  // route won't disable the switch.
   let componentsDisabled = $derived($parentRoute === DEFAULT_COMPONENTS_PATH);
+  let colorsDisabled = $derived($parentRoute === DEFAULT_COLORS_PATH);
 
   // Editing flow order: Tokens → Colors → Components. The condensed rail cycles
-  // through these; Components is skipped while it's disabled (already on that
+  // through these; a view is skipped while it's disabled (already on that
   // page) so the cycle never lands on a dead view.
   const CYCLE: readonly EditorView[] = ['tokens', 'colors', 'components'];
   const ICONS: Record<EditorView, string> = {
@@ -43,6 +44,7 @@
         i = (i + 1) % CYCLE.length;
         const next = CYCLE[i];
         if (next === 'components' && componentsDisabled) continue;
+        if (next === 'colors' && colorsDisabled) continue;
         return next;
       }
       return current;
@@ -81,6 +83,8 @@
         class="seg-btn"
         class:active={$editorView === 'colors'}
         aria-selected={$editorView === 'colors'}
+        disabled={colorsDisabled}
+        title={colorsDisabled ? 'Already viewing the Colors page' : undefined}
         onclick={() => set('colors')}
       >
         <span class="radio" aria-hidden="true"></span>

package/src/editor/ui/UIPillButton.svelte

@@ -10,6 +10,8 @@
     disabled?: boolean;
     title?: string;
     type?: 'button' | 'submit' | 'reset';
+    /** Marks the pill a toggle; true also lights it as on. */
+    ariaPressed?: boolean;
     onclick?: (e: MouseEvent) => void;
     children?: Snippet;
   }
@@ -23,6 +25,7 @@
     disabled = false,
     title,
     type = 'button',
+    ariaPressed,
     onclick,
     children,
   }: Props = $props();
@@ -48,6 +51,7 @@
     {disabled}
     {title}
     {onclick}
+    aria-pressed={ariaPressed}
   >
     {#if icon}<i class="fas {icon}" aria-hidden="true"></i>{/if}
     {#if children}<span class="ui-pill-label">{@render children()}</span>{/if}
@@ -89,6 +93,17 @@
     border-color: rgba(255, 255, 255, 0.75);
   }
 
+  /* Toggle "on": inset fill so it reads as depressed, not merely hovered. */
+  .ui-pill[aria-pressed='true'] {
+    background: linear-gradient(180deg, rgba(255, 255, 255, 0.30) 0%, rgba(255, 255, 255, 0.16) 100%);
+    border-color: rgba(255, 255, 255, 0.9);
+    box-shadow: inset 0 1px 3px rgba(0, 0, 0, 0.35);
+  }
+
+  .ui-pill[aria-pressed='true'] i {
+    color: rgba(255, 255, 255, 0.95);
+  }
+
   .ui-pill:focus-visible {
     outline: none;
     border-color: rgba(255, 255, 255, 0.9);