@motion-proto/live-tokens 0.55.1 → 0.57.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motion-proto/live-tokens",
-  "version": "0.55.1",
+  "version": "0.57.0",
   "type": "module",
   "description": "Design token editor with live CSS variable editing. Svelte 5 + Vite 8.",
   "keywords": [
@@ -30,6 +30,7 @@
     "src/live-tokens/data/colors-and-type/midnight-study.json",
     "src/live-tokens/data/colors-and-type/ocean.json",
     "src/live-tokens/data/colors-and-type/royal-velvet.json",
+    "src/live-tokens/data/colors-and-type/sketches.json",
     "src/live-tokens/data/colors-and-type/spring-meadow.json",
     "src/live-tokens/data/colors-and-type/sunset.json",
     "src/live-tokens/data/themes/autumn.json",
@@ -37,6 +38,7 @@
     "src/live-tokens/data/themes/midnight-study.json",
     "src/live-tokens/data/themes/ocean.json",
     "src/live-tokens/data/themes/royal-velvet.json",
+    "src/live-tokens/data/themes/sketches.json",
     "src/live-tokens/data/themes/spring-meadow.json",
     "src/live-tokens/data/themes/sunset.json",
     "dist-plugin",
@@ -129,13 +131,14 @@
     "check:docs-content": "node scripts/sync-docs.mjs --check",
     "check:token-contract": "node scripts/check-token-contract.mjs",
     "check:preset-themes": "node scripts/check-preset-themes.mjs",
+    "check:skills": "node scripts/check-skills.mjs",
     "sync:component-defaults": "node scripts/sync-component-defaults.mjs --write",
     "sync:docs": "node scripts/sync-docs.mjs --write",
     "seed:preset-theme": "node scripts/seed-preset-theme.mjs",
     "collapse:theme": "node scripts/collapse-theme-to-default.mjs",
     "check:smoke-install": "bash scripts/smoke-install.sh",
     "check:smoke-create": "bash scripts/smoke-create.sh",
-    "prepublishOnly": "npm run check:no-style-imports && npm run check:no-tooling-imports && npm run check:slot-prose && npm run check:overlay-portal && npm run check:editor-font-isolation && npm run check:component-defaults && npm run check:production-is-default && npm run check:docs-content && npm run build:lib && npm run check:token-contract && npm run check:preset-themes && npm run check:smoke-install && npm run check:smoke-create"
+    "prepublishOnly": "npm run check:no-style-imports && npm run check:no-tooling-imports && npm run check:slot-prose && npm run check:overlay-portal && npm run check:editor-font-isolation && npm run check:component-defaults && npm run check:production-is-default && npm run check:docs-content && npm run build:lib && npm run check:token-contract && npm run check:preset-themes && npm run check:skills && npm run check:smoke-install && npm run check:smoke-create"
   },
   "peerDependencies": {
     "@sveltejs/vite-plugin-svelte": "^7.0",

package/src/editor/core/fonts/applyFontPairing.ts

@@ -0,0 +1,158 @@
+import type {
+  ColorsAndType,
+  FontFamily,
+  FontSource,
+  FontStack,
+  FontStackVariable,
+} from '../themes/themeTypes';
+import { parseGoogleFontsUrl } from './fontParse';
+import { familyIndex, resolvedFaceName } from './fontPairing';
+
+export type PairingSlot = 'display' | 'body' | 'serif' | 'mono' | 'editorial';
+
+export interface PairingFace {
+  name: string;
+  url: string;
+  weights?: number[];
+  italics?: boolean;
+}
+
+export type FontPairing = Partial<Record<PairingSlot, PairingFace>>;
+
+export interface PairingChange {
+  slot: PairingSlot;
+  variable: FontStackVariable;
+  from: string | null;
+  to: string;
+}
+
+export interface DroppedSource {
+  id: string;
+  names: string[];
+}
+
+export interface FontPairingReport {
+  changes: PairingChange[];
+  dropped: DroppedSource[];
+  changed: boolean;
+}
+
+export interface FontPairingResult {
+  colorsAndType: ColorsAndType;
+  report: FontPairingReport;
+}
+
+/** Slot order is also the order stamped sources land in `fontSources`;
+ *  `check:preset-themes` reads the preset pair back out positionally. */
+export const SLOT_ORDER: PairingSlot[] = ['display', 'body', 'serif', 'mono', 'editorial'];
+
+export const SLOT_VARIABLES: Record<PairingSlot, FontStackVariable> = {
+  display: '--font-display',
+  body: '--font-sans',
+  serif: '--font-serif',
+  mono: '--font-mono',
+  editorial: '--font-editorial',
+};
+
+export function slugifyFamily(name: string): string {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+}
+
+function weightsFor(face: PairingFace): Pick<FontFamily, 'weights' | 'italics'> {
+  if (face.weights) {
+    return { weights: face.weights, ...(face.italics ? { italics: true } : {}) };
+  }
+  const parsed = parseGoogleFontsUrl(face.url)?.[0];
+  return {
+    ...(parsed?.weights ? { weights: parsed.weights } : {}),
+    ...(face.italics || parsed?.italics ? { italics: true } : {}),
+  };
+}
+
+function sourceFor(face: PairingFace, idPrefix: string): FontSource {
+  const id = `${idPrefix}${slugifyFamily(face.name)}`;
+  return {
+    id,
+    kind: 'google',
+    url: face.url,
+    label: 'Google Fonts',
+    families: [
+      {
+        id: `${id}:${slugifyFamily(face.name)}`,
+        name: face.name,
+        cssName: `"${face.name}"`,
+        ...weightsFor(face),
+      },
+    ],
+  };
+}
+
+function rewriteStack(stacks: FontStack[], variable: FontStackVariable, familyId: string): FontStack[] {
+  const stack = stacks.find((s) => s.variable === variable);
+  if (!stack) throw new Error(`colors and type have no ${variable} stack to rewrite`);
+  return stacks.map((s) =>
+    s === stack
+      ? { ...s, slots: [{ kind: 'project' as const, familyId }, ...s.slots.filter((slot) => slot.kind !== 'project')] }
+      : s,
+  );
+}
+
+export interface ApplyFontPairingOptions {
+  /** `src_preset_` for the shipped presets, so `check:preset-themes` can still
+   *  tell a stamped source from one the user added. */
+  idPrefix?: string;
+}
+
+/**
+ * Bind each named slot to a Google Fonts family: stamp the source, put that
+ * family at the head of the slot's stack, and keep every fallback behind it.
+ * Slots the pairing omits are left exactly as they are.
+ */
+export function applyFontPairing(
+  colorsAndType: ColorsAndType,
+  pairing: FontPairing,
+  { idPrefix = 'src_google_' }: ApplyFontPairingOptions = {},
+): FontPairingResult {
+  const slots = SLOT_ORDER.filter((slot) => pairing[slot]);
+  if (slots.length === 0) throw new Error('pairing names no slot to change');
+
+  const before = colorsAndType.fontStacks ?? [];
+  const beforeSources = colorsAndType.fontSources ?? [];
+  const beforeIndex = familyIndex(beforeSources);
+
+  const stamped = slots.map((slot) => ({ slot, source: sourceFor(pairing[slot]!, idPrefix) }));
+  const stampedIds = new Set(stamped.map((s) => s.source.id));
+
+  let stacks = before;
+  const changes: PairingChange[] = [];
+  for (const { slot, source } of stamped) {
+    const variable = SLOT_VARIABLES[slot];
+    const from = resolvedFaceName(before.find((s) => s.variable === variable), beforeIndex);
+    stacks = rewriteStack(stacks, variable, source.families[0].id);
+    changes.push({ slot, variable, from, to: source.families[0].name });
+  }
+
+  // A source displaced from a rewritten stack would still ship as a
+  // render-blocking @import in every consumer's fonts.css, so drop any source
+  // no remaining stack references.
+  const referenced = new Set(
+    stacks
+      .flatMap((s) => s.slots)
+      .filter((s) => s.kind === 'project')
+      .map((s) => s.familyId),
+  );
+  const kept = [...beforeSources.filter((s) => !stampedIds.has(s.id)), ...stamped.map((s) => s.source)];
+  const sources = kept.filter((s) => s.families.some((f) => referenced.has(f.id)));
+  const dropped = kept
+    .filter((s) => !sources.includes(s))
+    .map((s) => ({ id: s.id, names: s.families.map((f) => f.name) }));
+
+  const next: ColorsAndType = { ...colorsAndType, fontSources: sources, fontStacks: stacks };
+  const changed =
+    JSON.stringify([beforeSources, before]) !== JSON.stringify([sources, stacks]);
+
+  return {
+    colorsAndType: next,
+    report: { changes: changes.filter((c) => c.from !== c.to), dropped, changed },
+  };
+}

package/src/editor/core/fonts/fontLoader.ts

@@ -20,6 +20,7 @@ const FONT_STACK_VARIABLES: FontStackVariable[] = [
   '--font-sans',
   '--font-serif',
   '--font-mono',
+  '--font-editorial',
 ];
 
 const LINK_ATTR = 'data-font-source-id';

package/src/editor/core/fonts/fontMigration.ts

@@ -115,9 +115,37 @@ export function defaultFontStacks(sources: FontSource[]): FontStack[] {
         { kind: 'generic', value: 'monospace' },
       ],
     },
+    {
+      variable: '--font-editorial',
+      slots: [
+        ...pick('Manrope'),
+        { kind: 'system', preset: 'system-ui-sans' },
+        { kind: 'generic', value: 'sans-serif' },
+      ],
+    },
   ];
 }
 
+/**
+ * Seed `--font-editorial` from `--font-sans` on files written before the
+ * editorial role existed. The role ships as "the body face until a consumer
+ * repoints it", so cloning the body stack is the migration: a theme that never
+ * touches editorial keeps rendering exactly as it did.
+ *
+ * Presence-based like the rest of this module, so re-running is a no-op and no
+ * schemaVersion step is needed.
+ */
+function ensureEditorialStack(stacks: FontStack[]): boolean {
+  if (stacks.some((s) => s.variable === '--font-editorial')) return false;
+  const sans = stacks.find((s) => s.variable === '--font-sans');
+  if (!sans) return false;
+  stacks.push({
+    variable: '--font-editorial',
+    slots: sans.slots.map((slot) => ({ ...slot })),
+  });
+  return true;
+}
+
 // Older themes have `kind: 'font-face'` sources with embedded cssText that
 // references local woff2 files. The url() resolution for those embedded refs
 // is fragile in consumers, so swap any font-face source whose cssText is for
@@ -161,9 +189,11 @@ export function migrateColorsAndTypeFonts(colorsAndType: ColorsAndType): { migra
   if (!colorsAndType.fontStacks || colorsAndType.fontStacks.length === 0) {
     colorsAndType.fontStacks = defaultFontStacks(colorsAndType.fontSources);
     migrated = true;
+  } else if (ensureEditorialStack(colorsAndType.fontStacks)) {
+    migrated = true;
   }
   if (colorsAndType.cssVariables) {
-    for (const key of ['--font-display', '--font-sans', '--font-serif', '--font-mono']) {
+    for (const key of ['--font-display', '--font-sans', '--font-serif', '--font-mono', '--font-editorial']) {
       if (key in colorsAndType.cssVariables) {
         delete colorsAndType.cssVariables[key];
         migrated = true;

package/src/editor/core/fonts/fontPairing.ts

@@ -8,7 +8,17 @@ import type { FontFamily, FontSource, FontStack, FontStackVariable } from '../th
 
 const PAIRING: FontStackVariable[] = ['--font-display', '--font-sans'];
 
-function slotLabel(
+export function familyIndex(sources: FontSource[]): Map<string, FontFamily> {
+  const familyById = new Map<string, FontFamily>();
+  for (const source of sources) {
+    for (const family of source.families) familyById.set(family.id, family);
+  }
+  return familyById;
+}
+
+/** The face the page actually shows for one stack: the first slot that
+ *  resolves, named as the user named it. */
+export function resolvedFaceName(
   stack: FontStack | undefined,
   familyById: Map<string, FontFamily>,
 ): string | null {
@@ -25,11 +35,8 @@ function slotLabel(
 }
 
 export function fontPairingLabel(stacks: FontStack[], sources: FontSource[]): string {
-  const familyById = new Map<string, FontFamily>();
-  for (const source of sources) {
-    for (const family of source.families) familyById.set(family.id, family);
-  }
-  return PAIRING.map((variable) => slotLabel(stacks.find((s) => s.variable === variable), familyById))
+  const familyById = familyIndex(sources);
+  return PAIRING.map((variable) => resolvedFaceName(stacks.find((s) => s.variable === variable), familyById))
     .filter((label): label is string => label !== null)
     .join(' / ');
 }

package/src/editor/core/fonts/googleFontsUrl.ts

@@ -0,0 +1,123 @@
+import { parseFontFaceText } from './fontParse';
+
+export interface CssResponse {
+  ok: boolean;
+  status: number;
+  text: () => Promise<string>;
+}
+
+export type CssFetcher = (url: string) => Promise<CssResponse>;
+
+export interface ResolvedGoogleFont {
+  /** As Google spells it in the returned CSS, not as the caller typed it. */
+  name: string;
+  url: string;
+  weights: number[];
+  italics: boolean;
+  probeUrl: string;
+}
+
+/** The shipped `--font-weight-*` scale runs 100 to 900 in hundreds, so probing
+ *  that ladder discovers every weight a theme can ask for. */
+const LADDER = [100, 200, 300, 400, 500, 600, 700, 800, 900];
+
+function familyParam(name: string): string {
+  return name.trim().replace(/\s+/g, '+');
+}
+
+function url(name: string, spec?: string): string {
+  const family = spec ? `${familyParam(name)}:${spec}` : familyParam(name);
+  return `https://fonts.googleapis.com/css2?family=${family}&display=swap`;
+}
+
+/**
+ * Ask for every weight in both styles. Google silently drops the ones a family
+ * does not have and answers 200 anyway, so the returned CSS is a census of the
+ * family rather than a yes/no on the request. A 400 here means the family
+ * itself is not on Google Fonts.
+ */
+export function discoveryUrl(name: string): string {
+  const pairs = [
+    ...LADDER.map((w) => `0,${w}`),
+    ...LADDER.map((w) => `1,${w}`),
+  ];
+  return url(name, `ital,wght@${pairs.join(';')}`);
+}
+
+function isContiguous(weights: number[]): boolean {
+  return weights.length > 1 && weights.every((w, i) => i === 0 || w - weights[i - 1] === 100);
+}
+
+/** The narrowest URL that still delivers everything the family has. A range
+ *  serves one variable file; an enumeration serves one file per weight. */
+export function persistUrlFor(name: string, weights: number[], italics: boolean): string {
+  if (weights.length === 0 || (weights.length === 1 && weights[0] === 400 && !italics)) {
+    return url(name);
+  }
+  if (isContiguous(weights)) {
+    const range = `${weights[0]}..${weights[weights.length - 1]}`;
+    return url(name, italics ? `ital,wght@0,${range};1,${range}` : `wght@${range}`);
+  }
+  const spec = italics
+    ? `ital,wght@${[...weights.map((w) => `0,${w}`), ...weights.map((w) => `1,${w}`)].join(';')}`
+    : `wght@${weights.join(';')}`;
+  return url(name, spec);
+}
+
+function censusFrom(css: string, requested: string): { name: string; weights: number[]; italics: boolean } {
+  const families = parseFontFaceText(css);
+  if (families.length === 0) {
+    throw new Error(`Google Fonts returned no @font-face rules for "${requested}".`);
+  }
+  const family = families[0];
+  return {
+    name: family.name,
+    weights: family.weights ?? [],
+    italics: family.italics === true,
+  };
+}
+
+/**
+ * Verify a family exists on Google Fonts and settle on the URL to persist.
+ * Two requests in the common case: one to take the census, one to confirm the
+ * narrower URL built from it. A range that the family's axis cannot serve
+ * answers 400, so the enumerated form is the fallback rather than the guess.
+ */
+export async function resolveGoogleFont(name: string, fetcher: CssFetcher): Promise<ResolvedGoogleFont> {
+  const probeUrl = discoveryUrl(name);
+  const probe = await fetcher(probeUrl);
+  if (!probe.ok) {
+    throw new Error(
+      `"${name}" is not on Google Fonts (the API answered ${probe.status}). ` +
+        `Check the spelling against fonts.google.com.`,
+    );
+  }
+  const census = censusFrom(await probe.text(), name);
+
+  const candidates = [persistUrlFor(census.name, census.weights, census.italics)];
+  const enumerated = census.weights.length > 0
+    ? url(
+        census.name,
+        census.italics
+          ? `ital,wght@${[...census.weights.map((w) => `0,${w}`), ...census.weights.map((w) => `1,${w}`)].join(';')}`
+          : `wght@${census.weights.join(';')}`,
+      )
+    : null;
+  if (enumerated && !candidates.includes(enumerated)) candidates.push(enumerated);
+  const bare = url(census.name);
+  if (!candidates.includes(bare)) candidates.push(bare);
+
+  for (const candidate of candidates) {
+    const res = await fetcher(candidate);
+    if (!res.ok) continue;
+    const served = censusFrom(await res.text(), census.name);
+    return {
+      name: census.name,
+      url: candidate,
+      weights: served.weights,
+      italics: served.italics,
+      probeUrl,
+    };
+  }
+  throw new Error(`Could not build a working Google Fonts URL for "${census.name}".`);
+}

package/src/editor/core/fonts/weightCoverage.ts

@@ -0,0 +1,92 @@
+import type { FontStackVariable } from '../themes/themeTypes';
+import { inferFontFamilyVariable } from './fontWeightAvailability';
+
+export interface WeightRequirement {
+  variable: string;
+  stack: FontStackVariable;
+  weight: number;
+}
+
+export interface FaceCoverage {
+  stack: FontStackVariable;
+  family: string;
+  required: number[];
+  available: number[];
+  missing: number[];
+  italics: boolean;
+}
+
+const STACK_REF = /var\(\s*(--font-(?:display|sans|serif|mono))\s*\)/;
+const VAR_REF = /var\(\s*(--[a-z0-9-]+)/i;
+
+function declarations(css: string): Map<string, string> {
+  const decls = new Map<string, string>();
+  for (const [, name, value] of css.matchAll(/(--[a-z0-9-]+)\s*:\s*([^;{}]+);/gi)) {
+    decls.set(name, value.trim());
+  }
+  return decls;
+}
+
+/**
+ * Every weight the token contract asks of each font stack, read off the
+ * `-font-family` / `-font-weight` pairing that typography tokens follow.
+ * `overrides` takes a theme's own `cssVariables`, so component tokens count
+ * the same as the shipped text styles.
+ */
+export function requiredWeights(
+  tokensCss: string,
+  overrides: Record<string, string> = {},
+): WeightRequirement[] {
+  const decls = declarations(tokensCss);
+  for (const [name, value] of Object.entries(overrides)) decls.set(name, String(value).trim());
+
+  const scale = new Map<string, number>();
+  for (const [name, value] of decls) {
+    if (name.startsWith('--font-weight-') && /^\d+$/.test(value)) scale.set(name, Number(value));
+  }
+
+  const seen = new Set<string>();
+  const out: WeightRequirement[] = [];
+  for (const [name, value] of decls) {
+    const familyVariable = inferFontFamilyVariable(name);
+    if (!familyVariable) continue;
+    const stack = decls.get(familyVariable)?.match(STACK_REF)?.[1] as FontStackVariable | undefined;
+    if (!stack) continue;
+
+    const weight = /^\d+$/.test(value) ? Number(value) : scale.get(value.match(VAR_REF)?.[1] ?? '');
+    if (weight === undefined) continue;
+
+    const key = `${stack}:${weight}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push({ variable: name, stack, weight });
+  }
+  return out;
+}
+
+export interface CoveredFace {
+  name: string;
+  weights: number[];
+  italics: boolean;
+}
+
+export function weightCoverage(
+  requirements: WeightRequirement[],
+  faces: Partial<Record<FontStackVariable, CoveredFace>>,
+): FaceCoverage[] {
+  const out: FaceCoverage[] = [];
+  for (const [stack, face] of Object.entries(faces) as [FontStackVariable, CoveredFace][]) {
+    const required = [...new Set(requirements.filter((r) => r.stack === stack).map((r) => r.weight))].sort(
+      (a, b) => a - b,
+    );
+    out.push({
+      stack,
+      family: face.name,
+      required,
+      available: face.weights,
+      missing: required.filter((w) => !face.weights.includes(w)),
+      italics: face.italics,
+    });
+  }
+  return out;
+}

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

@@ -13,7 +13,7 @@
  * derives the same CSS vars from the persisted config.
  */
 
-import { cssColorToOklch, oklchToCssClamped, gamutClamp, type Oklch } from './oklch';
+import { cssColorToOklch, oklchToCss, gamutClamp, type Oklch } from './oklch';
 import { type CurveAnchor, sampleCurve, makeAnchor, tangentAnchor, resmoothAutoCurve } from '../../ui/curveEngine';
 import type { PaletteConfig } from '../themes/themeTypes';
 
@@ -204,7 +204,14 @@ export type DerivedValue =
  *  then serialized as `oklch()`. Idempotent on the already-in-gamut per-step
  *  derivation output. `raw` passes through untouched. */
 export function serializeDerivedValue(value: DerivedValue): string {
-  return value.kind === 'raw' ? value.css : oklchToCssClamped(value.l, value.c, value.h);
+  // Emitted unclamped: the stored basis is OKLCH, and clamping into sRGB threw
+  // away chroma a wide-gamut display can actually show. Values already inside
+  // sRGB serialize identically (`gamutClamp` returns them untouched), so this
+  // moves nothing in an existing theme; only intent authored beyond sRGB — a
+  // Tailwind v4 ramp, say — now survives to the browser, which does its own
+  // gamut mapping at paint. `oklchToCssClamped` still backs the hex readouts,
+  // where a clamped projection is the whole point.
+  return value.kind === 'raw' ? value.css : oklchToCss(value.l, value.c, value.h);
 }
 
 export function computePaletteOklch(