@threadlabs/looma 0.35.1 → 0.36.0

package/docs/fonts.mjs

@@ -0,0 +1,45 @@
+/** A focused searchable Google Fonts collection; system fonts never require a request. */
+export const googleFonts = Object.fromEntries([
+  ['Inter', 'sans-serif'], ['Roboto', 'sans-serif'], ['Open Sans', 'sans-serif'],
+  ['Source Sans 3', 'sans-serif'], ['Lato', 'sans-serif'], ['Nunito Sans', 'sans-serif'],
+  ['DM Sans', 'sans-serif'], ['Manrope', 'sans-serif'], ['Work Sans', 'sans-serif'],
+  ['IBM Plex Sans', 'sans-serif'], ['Public Sans', 'sans-serif'], ['Atkinson Hyperlegible', 'sans-serif'],
+  ['Outfit', 'sans-serif'], ['Merriweather', 'serif'], ['Lora', 'serif'],
+  ['Source Serif 4', 'serif'], ['Libre Baskerville', 'serif'], ['Crimson Pro', 'serif'],
+  ['EB Garamond', 'serif'], ['Playfair Display', 'serif'], ['Roboto Mono', 'monospace'],
+  ['IBM Plex Mono', 'monospace'], ['JetBrains Mono', 'monospace'], ['Fira Code', 'monospace'],
+].map(([family, category]) => [family, { family, category, weights: ['Lato', 'Atkinson Hyperlegible', 'Libre Baskerville'].includes(family) ? '400;700' : '400;500;600;700' }]));
+
+export const systemFont = 'system-ui, sans-serif';
+export const googleFontStack = family => `"${family}", ${googleFonts[family].category}`;
+export function googleFontURL(fonts = {}) {
+  const families = [...new Set(Object.values(fonts))].sort();
+  if (!families.length) return '';
+  return 'https://fonts.googleapis.com/css2?' + families.map(family => {
+    if (!Object.hasOwn(googleFonts, family)) throw new Error('Choose a supported Google font.');
+    return 'family=' + encodeURIComponent(family).replaceAll('%20', '+') + ':wght@' + googleFonts[family].weights;
+  }).join('&') + '&display=swap';
+}
+
+/** Load and confirm actual faces before reporting a selected font as ready. */
+const fontLoads = new WeakMap();
+export async function loadGoogleFonts(document, fonts) {
+  const url = googleFontURL(fonts);
+  let link = document.head.querySelector('link[data-looma-google-fonts]');
+  if (!url) { fontLoads.get(link)?.cancel(); link?.remove(); return; }
+  if (link?.href !== url) {
+    fontLoads.get(link)?.cancel(); link?.remove(); link = document.createElement('link');
+    link.rel = 'stylesheet'; link.dataset.loomaGoogleFonts = '';
+    let cancel;
+    const loaded = new Promise((resolve, reject) => {
+      cancel = () => resolve(false);
+      link.onload = () => resolve(true); link.onerror = () => reject(new Error('The Google font could not load. Check your connection or select the system font.'));
+    });
+    fontLoads.set(link, { loaded, cancel }); link.href = url; document.head.append(link);
+  }
+  if (await fontLoads.get(link)?.loaded === false) return;
+  for (const family of new Set(Object.values(fonts))) {
+    const faces = await document.fonts.load(`400 16px "${family}"`);
+    if (!faces.length) throw new Error(`${family} is unavailable; the fallback is currently displayed.`);
+  }
+}

package/docs/index.d.ts

@@ -17,8 +17,8 @@ export interface DocumentationCatalog {
   resources?: { tag: string; package: string; resource: string }[]; components: DocumentationComponent[];
 }
 export interface DiscoveryRoot { directory: string; packageName: string; groups?: DocumentationGroup[] }
-export interface ThemeRecipe { schemaVersion: 1; values: Record<string, string>; presets?: Partial<Record<'material' | 'palette', string>> }
-export interface ThemeField { family: string; id: string; label: string; property: string; type: string; defaultValue: string; description: string; min?: number; max?: number }
+export interface ThemeRecipe { schemaVersion: 1; values: Record<string, string>; origin?: string; fonts?: Partial<Record<'body-font' | 'display-font', string>>; presets?: Partial<Record<'material' | 'palette', string>> }
+export interface ThemeField { family: string; id: string; label: string; property: string | null; type: string; defaultValue: string; description: string; min?: number; max?: number; choices?: Record<string, string> }
 export interface DocumentationConfiguration {
   title?: string; base?: string; origin?: string; outDir?: string; content?: string;
   logo?: string | { light: string; dark?: string }; nav?: { label: string; href: string }[];

package/docs/palette.mjs

@@ -0,0 +1,67 @@
+// Perceptual palette operations use Oklab/OKLCH; output remains portable sRGB hex.
+const linear = value => value <= .04045 ? value / 12.92 : ((value + .055) / 1.055) ** 2.4;
+const encoded = value => value <= .0031308 ? value * 12.92 : 1.055 * value ** (1 / 2.4) - .055;
+const clamp = (value, min = 0, max = 1) => Math.max(min, Math.min(max, value));
+export function toLch(hex) {
+  const [r, g, b] = [1, 3, 5].map(i => linear(parseInt(hex.slice(i, i + 2), 16) / 255));
+  const l = Math.cbrt(.4122214708 * r + .5363325363 * g + .0514459929 * b);
+  const m = Math.cbrt(.2119034982 * r + .6806995451 * g + .1073969566 * b);
+  const s = Math.cbrt(.0883024619 * r + .2817188376 * g + .6299787005 * b);
+  const a = 1.9779984951 * l - 2.428592205 * m + .4505937099 * s;
+  const bb = .0259040371 * l + .7827717662 * m - .808675766 * s;
+  return [.2104542553 * l + .793617785 * m - .0040720468 * s, Math.hypot(a, bb), (Math.atan2(bb, a) * 180 / Math.PI + 360) % 360];
+}
+const channels = ([lightness, chroma, hue]) => {
+  const a = chroma * Math.cos(hue * Math.PI / 180), b = chroma * Math.sin(hue * Math.PI / 180);
+  const l = (lightness + .3963377774 * a + .2158037573 * b) ** 3;
+  const m = (lightness - .1055613458 * a - .0638541728 * b) ** 3;
+  const s = (lightness - .0894841775 * a - 1.291485548 * b) ** 3;
+  return [4.0767416621 * l - 3.3077115913 * m + .2309699292 * s, -1.2684380046 * l + 2.6097574011 * m - .3413193965 * s, -.0041960863 * l - .7034186147 * m + 1.707614701 * s];
+};
+export function fromLch([lightness, chroma, hue]) {
+  lightness = clamp(lightness); chroma = Math.max(0, chroma);
+  let rgb = channels([lightness, chroma, hue]);
+  if (rgb.some(n => n < -.000001 || n > 1.000001)) {
+    // Reduce chroma at fixed hue/lightness instead of clipping individual channels.
+    let low = 0, high = chroma;
+    for (let i = 0; i < 18; i++) {
+      const middle = (low + high) / 2;
+      if (channels([lightness, middle, hue]).every(n => n >= 0 && n <= 1)) low = middle;
+      else high = middle;
+    }
+    rgb = channels([lightness, low, hue]);
+  }
+  return '#' + rgb.map(n => Math.round(clamp(encoded(n)) * 255).toString(16).padStart(2, '0')).join('');
+}
+export function mixColour(a, b, weight) {
+  // Cartesian Oklab mixing avoids a hue discontinuity around 0/360 degrees.
+  const cartesian = hex => { const [l, c, h] = toLch(hex); return [l, c * Math.cos(h * Math.PI / 180), c * Math.sin(h * Math.PI / 180)]; };
+  const first = cartesian(a), second = cartesian(b), mixed = first.map((n, i) => n * weight + second[i] * (1 - weight));
+  return fromLch([mixed[0], Math.hypot(mixed[1], mixed[2]), Math.atan2(mixed[2], mixed[1]) * 180 / Math.PI]);
+}
+export function paletteSeeds(values) {
+  const intensity = Number(values['color-intensity']) * 2, warmth = (Number(values.warmth) - .5) * 2;
+  const relationship = values['palette-relationship'];
+  const brandHue = toLch(values.action)[2];
+  return Object.fromEntries(['action', 'canvas', 'surface', 'text'].map(key => {
+    if (intensity === 1 && warmth === 0 && relationship === 'preserve') return [key, values[key]];
+    let [l, c, h] = toLch(values[key]);
+    if (key !== 'action') {
+      const tint = Math.max(Math.abs(warmth), relationship === 'preserve' ? 0 : .5);
+      if (tint) l = clamp(l, .08 * tint, 1 - .03 * tint);
+      if (relationship !== 'preserve') { h = brandHue + (relationship === 'neighboring' ? 30 : 180); c = Math.max(c, .018); }
+      if (warmth !== 0) {
+        const target = warmth > 0 ? 85 : 255;
+        const delta = ((target - h + 540) % 360) - 180;
+        h += delta * Math.abs(warmth); c = Math.max(c, .035 * Math.abs(warmth));
+      }
+    }
+    return [key, fromLch([l, c * intensity, h])];
+  }));
+}
+
+export function companionSurface(seed, mode) {
+  const [l, c, h] = toLch(seed);
+  // Retain hue and restrained colorfulness; convert the tonal role, not the identity.
+  return fromLch([mode === 'dark' ? .16 + (1 - l) * .12 : .94 + (1 - l) * .045, Math.min(c, .045), h]);
+}

package/docs/site.mjs

@@ -86,7 +86,7 @@ export async function prepareDocumentation({ root, config = {}, catalog }) {
   await cp(own('catalog-view.js'), path.join(generated, 'catalog-view.js'));
   await cp(own('preview.js'), path.join(generated, 'preview.js'));
   for (const file of ['reference.html', 'reference.js']) await cp(own(file), path.join(generated, file));
-  for (const file of ['customizer.js', 'theme.mjs', 'theme-session.mjs', 'value-editors.mjs']) await cp(own(file), path.join(generated, file));
+  for (const file of ['customizer.js', 'theme.mjs', 'theme-session.mjs', 'value-editors.mjs', 'palette.mjs', 'fonts.mjs']) await cp(own(file), path.join(generated, file));
   const write = async (file, source) => { await mkdir(path.dirname(file), { recursive: true }); await writeFile(file, source); };
   const examples = [];
   // HTMLKit route groups retain their labels/order in navigation without changing public URLs.

package/docs/theme-session.mjs

@@ -4,10 +4,11 @@ const identity = Symbol.for('looma.documentation.theme');
 export const themeEvent = 'looma-documentation-theme';
 
 /** Browser choices belong to one documentation base; repository writes stay explicit. */
-export function createThemeSession(view, { base, baseline, systemCSS }) {
+export function createThemeSession(view, { base, baseline, systemCSS, historyLimit = 100 }) {
   const key = `looma:documentation-theme:v1:${base}`;
   let original = validateRecipe(baseline);
-  let selected;
+  let selected, draft, comparison;
+  const past = [], future = [];
   let portableCSS = '';
   let storageAvailable = true;
   const style = view.document.createElement('style');
@@ -16,29 +17,47 @@ export function createThemeSession(view, { base, baseline, systemCSS }) {
   const read = value => { try { return value ? validateRecipe(JSON.parse(value)) : undefined; } catch { return undefined; } };
   try { selected = read(view.localStorage.getItem(key)); } catch { storageAvailable = false; }
   const paint = () => {
-    portableCSS = selected ? themeCSS(selected, systemCSS) : '';
-    view.document.documentElement.toggleAttribute('data-looma-documentation-theme', Boolean(selected));
-    style.textContent = selected ? themeCSS(selected, systemCSS, { scope: 'documentation' }) : '';
+    const displayed = comparison ?? draft ?? selected;
+    portableCSS = displayed ? themeCSS(displayed, systemCSS) : '';
+    view.document.documentElement.toggleAttribute('data-looma-documentation-theme', Boolean(displayed));
+    style.textContent = displayed ? themeCSS(displayed, systemCSS, { scope: 'documentation' }) : '';
     view.dispatchEvent(new view.CustomEvent(themeEvent, { detail: { css: portableCSS } }));
   };
   const persist = () => {
     try { if (selected) view.localStorage.setItem(key, JSON.stringify(selected)); else view.localStorage.removeItem(key); storageAvailable = true; } catch { storageAvailable = false; }
     paint();
   };
+  const remember = () => {
+    past.push(structuredClone(selected));
+    if (past.length > historyLimit) past.shift();
+    future.length = 0;
+  };
   const session = {
-    get recipe() { return structuredClone(selected ?? original); },
+    get recipe() { return structuredClone(draft ?? selected ?? original); },
     get hasOverride() { return selected !== undefined; },
     get storageAvailable() { return storageAvailable; },
     get css() { return portableCSS; },
-    apply(recipe) { selected = validateRecipe(recipe); persist(); },
-    reset() { selected = undefined; persist(); return structuredClone(original); },
+    get canUndo() { return past.length > 0; },
+    get canRedo() { return future.length > 0; },
+    preview(recipe) { draft = validateRecipe(recipe); paint(); },
+    commit() { if (draft) session.apply(draft); },
+    cancel() { draft = undefined; paint(); },
+    compare(recipe) { comparison = recipe === undefined ? undefined : validateRecipe(recipe); paint(); },
+    undo() { if (!past.length) return; future.push(structuredClone(selected)); selected = past.pop(); draft = comparison = undefined; persist(); },
+    redo() { if (!future.length) return; past.push(structuredClone(selected)); selected = future.pop(); draft = comparison = undefined; persist(); },
+    apply(recipe) {
+      const next = validateRecipe(recipe);
+      if (JSON.stringify(next) !== JSON.stringify(selected)) remember();
+      selected = next; draft = comparison = undefined; persist();
+    },
+    reset() { if (selected !== undefined) remember(); selected = draft = comparison = undefined; persist(); return structuredClone(original); },
     baseline(recipe) { original = validateRecipe(recipe); },
   };
   view.addEventListener('storage', event => {
     if (event.key !== key && event.key !== null) return;
     const next = read(event.newValue);
     if (event.newValue !== null && !next) return;
-    selected = next; paint();
+    selected = next; draft = comparison = undefined; past.length = future.length = 0; paint();
   });
   paint();
   return session;

package/docs/theme.mjs

@@ -1,6 +1,9 @@
+import { googleFonts, googleFontStack, googleFontURL } from './fonts.mjs';
+import { mixColour as mix, paletteSeeds, companionSurface, toLch, fromLch } from './palette.mjs';
+
 const bounds = {
-  'text-size': [14, 24], 'control-size': [32, 64], 'corner-roundness': [0, 32],
-  'line-weight': [.5, 3], density: [.75, 1.5], 'scale-contrast': [1, 1.5],
+  'text-size': [14, 24], 'control-roominess': [2, 4], 'corner-roundness': [0, 32],
+  'line-weight': [.5, 3], spacing: [.75, 1.5], 'scale-contrast': [1, 1.5],
   'space-curve': [.5, 2], 'text-weight': [400, 700], 'outer-depth': [0, 2], 'inner-depth': [0, 2],
   'response-time': [0, 600],
 };
@@ -11,13 +14,16 @@ export const themeFields = [
   ['Colour', 'canvas', 'Canvas', '--ui-surface', 'colour', '#f6f6f8', 'The ground behind surfaces.'],
   ['Colour', 'surface', 'Surface', '--ui-surface-raised', 'colour', '#ffffff', 'Fields, cards and floating surfaces.'],
   ['Colour', 'text', 'Text', '--ui-text', 'colour', '#1a1a1a', 'Readable content; supporting text follows this and Surface.'],
+  ['Colour', 'warmth', 'Surface warmth', null, 'fraction', '0.5', '0% cool, 50% original, 100% warm paper and ink; your brand hue stays independent.'],
+  ['Colour', 'color-intensity', 'Color intensity', null, 'fraction', '0.5', '0% quiet, 50% original, 100% vivid, coordinated across surfaces, actions and status colors.'],
+  ['Colour', 'palette-relationship', 'Palette relationship', null, 'choice', 'preserve', 'Keep seed hues, or relate quiet surfaces to the brand through neighboring or complementary hues.'],
   ['Type', 'body-font', 'Body font', '--ui-font-sans', 'font', 'system-ui, sans-serif', 'The shared interface typeface.'],
   ['Type', 'display-font', 'Display font', '--ui-font-display', 'font', 'system-ui, sans-serif', 'The heading typeface.'],
-  ['Type', 'text-size', 'Text size', '--ui-font-size', 'positive-length', '16px', 'Base type and choice-mark size. Accepts native CSS lengths, such as 1rem.'],
+  ['Type', 'text-size', 'Text size', '--ui-font-size', 'positive-length', '1rem', 'Base type and choice-mark size. Accepts native CSS lengths, such as 1rem.'],
   ['Type', 'text-weight', 'Emphasis weight', '--ui-font-medium', 'weight', '500', 'Control-label emphasis; body and headings keep their roles.'],
-  ['Size & spacing', 'control-size', 'Control size', '--ui-control-size', 'positive-length', '40px', 'One shared height for buttons, fields and swatches.'],
-  ['Size & spacing', 'density', 'Density', '--ui-density', 'positive', '1', 'More or less breathing room throughout the interface.'],
-  ['Size & spacing', 'scale-contrast', 'Size ratio', '--ui-scale-ratio', 'ratio', '1.2', 'The multiplier between small, medium and large controls.'],
+  ['Size & spacing', 'control-roominess', 'Control roominess', '--ui-control-roominess', 'positive', '2.5', 'Shared control height as a multiple of base text size; buttons, fields and swatches stay aligned.'],
+  ['Size & spacing', 'spacing', 'Spacing', '--ui-spacing', 'positive', '1', 'More or less breathing room throughout the interface.'],
+  ['Size & spacing', 'scale-contrast', 'Size ratio', '--ui-scale-ratio', 'ratio', '1.2', 'The multiplier between small, medium and large controls. At 1 the sizes are equal; higher values separate them.'],
   ['Size & spacing', 'space-curve', 'Spacing curve', '--ui-space-curve', 'nonnegative', '1', 'Spacing growth: 1 is linear, 2 is quadratic. Independent of control sizes.'],
   ['Size & spacing', 'corner-roundness', 'Corner roundness', '--ui-radius-md', 'length', '8px', 'One corner family across controls and surfaces.'],
   ['Size & spacing', 'line-weight', 'Line weight', '--ui-border-width', 'length', '1px', 'Shared edge weight; focus stays independently visible.'],
@@ -35,20 +41,20 @@ export const themeFields = [
   ['Material', 'light-strength', 'Light strength', '--ui-light-strength', 'fraction', '0.65', 'Shared illumination; each material and component role determines its response.'],
   ['Motion', 'response-time', 'Response time', '--ui-motion-fast', 'time', '120ms', 'Shared feedback pace; floating transitions take proportionally longer.'],
   ['Motion', 'response-curve', 'Response curve', '--ui-motion-ease', 'easing', 'cubic-bezier(0.2,0,0.2,1)', 'How movement accelerates and settles.'],
-].map(([family, id, label, property, type, defaultValue, description]) => Object.freeze({ family, id, label, property, type, defaultValue, description, ...(bounds[id] ? { min: bounds[id][0], max: bounds[id][1] } : type === 'fraction' ? { min: 0, max: 1 } : {}) }));
+].map(([family, id, label, property, type, defaultValue, description]) => Object.freeze({ family, id, label, property, type, defaultValue, description, ...(type === 'choice' ? { choices: { preserve: 'Preserve seed hues', neighboring: 'Neighboring hues', complementary: 'Complementary hues' } } : {}), ...(bounds[id] ? { min: bounds[id][0], max: bounds[id][1] } : type === 'fraction' ? { min: 0, max: 1 } : {}) }));
 
 export const defaultRecipe = () => ({ schemaVersion: 1, values: Object.fromEntries(themeFields.map(field => [field.id, field.defaultValue])) });
 const starting = values => ({ schemaVersion: 1, values: { ...defaultRecipe().values, ...values } });
 export const startingPoints = {
   clear: defaultRecipe(),
-  bookish: starting({ action: '#2e1228', canvas: '#f7f7f5', surface: '#fffefd', text: '#0d0c0c', 'body-font': 'Arial, sans-serif', 'display-font': 'Georgia, serif', 'text-weight': '400', 'control-size': '42px', 'scale-contrast': '1.18', 'outer-depth': '1', 'inner-depth': '1', glassiness: '0.8', 'surface-separation': '0.65', translucency: '0.18', 'edge-light': '1', finish: '0.85', glow: '0.3', 'light-spread': '0.3', 'light-strength': '0.9', 'response-time': '150ms', 'response-curve': 'ease' }),
-  wiki: starting({ action: '#4f46e5', canvas: '#ffffff', surface: '#ffffff', text: '#1a1a1a', 'control-size': '34px', density: '0.85', 'scale-contrast': '1.15', 'corner-roundness': '6px', 'outer-depth': '0.35', 'inner-depth': '0', 'response-time': '110ms' }),
+  bookish: starting({ action: '#2e1228', canvas: '#f7f7f5', surface: '#fffefd', text: '#0d0c0c', 'body-font': 'Arial, sans-serif', 'display-font': 'Georgia, serif', 'text-weight': '400', 'control-roominess': '2.625', 'scale-contrast': '1.18', 'outer-depth': '1', 'inner-depth': '1', glassiness: '0.8', 'surface-separation': '0.65', translucency: '0.18', 'edge-light': '1', finish: '0.85', glow: '0.3', 'light-spread': '0.3', 'light-strength': '0.9', 'response-time': '150ms', 'response-curve': 'ease' }),
+  wiki: starting({ action: '#4f46e5', canvas: '#ffffff', surface: '#ffffff', text: '#1a1a1a', 'control-roominess': '2.125', spacing: '0.85', 'scale-contrast': '1.15', 'corner-roundness': '6px', 'outer-depth': '0.35', 'inner-depth': '0', 'response-time': '110ms' }),
   editorial: starting({ action: '#182c24', canvas: '#eee9dc', surface: '#fffdf5', text: '#182c24', 'corner-roundness': '0px', 'outer-depth': '0', 'inner-depth': '0', 'body-font': 'Georgia, serif', 'display-font': 'Georgia, serif', 'text-weight': '400', 'line-weight': '2px', 'response-time': '90ms', 'response-curve': 'linear' }),
   night: starting({ action: '#a7b8ff', canvas: '#11141c', surface: '#202634', text: '#edf1fb', 'corner-roundness': '12px', 'outer-depth': '1.4', 'inner-depth': '0.45', translucency: '0.2', 'edge-light': '0.65', 'response-time': '210ms', 'response-curve': 'cubic-bezier(0.2,0.8,0.2,1)' }),
-  garden: starting({ action: '#256342', canvas: '#eef5e7', surface: '#fcfff6', text: '#173121', 'corner-roundness': '22px', 'outer-depth': '0.35', 'inner-depth': '0', 'edge-light': '0.2', 'control-size': '46px', 'scale-contrast': '1.24', density: '1.05', 'response-time': '180ms', 'response-curve': 'cubic-bezier(0.16,1,0.3,1)' }),
+  garden: starting({ action: '#256342', canvas: '#eef5e7', surface: '#fcfff6', text: '#173121', 'corner-roundness': '22px', 'outer-depth': '0.35', 'inner-depth': '0', 'edge-light': '0.2', 'control-roominess': '2.875', 'scale-contrast': '1.24', spacing: '1.05', 'response-time': '180ms', 'response-curve': 'cubic-bezier(0.16,1,0.3,1)' }),
 };
 export const startingPointLabels = { clear: 'Clear', bookish: 'Bookish', wiki: 'Wiki', editorial: 'Editorial', night: 'Night', garden: 'Garden' };
-const paletteKeys = ['action', 'canvas', 'surface', 'text'];
+const paletteKeys = themeFields.filter(field => field.family === 'Colour').map(field => field.id);
 // Palette choices move only the shared color seeds; size, material and motion stay independent.
 export const themePalettes = Object.fromEntries([
   ['clear', 'Indigo & mist'], ['bookish', 'Plum & paper'], ['wiki', 'Indigo & chalk'],
@@ -88,6 +94,24 @@ export function paletteFor(input) {
   return Object.entries(themePalettes).find(([, palette]) => paletteKeys.every(key => values[key].toLowerCase() === palette.values[key].toLowerCase()))?.[0] ?? 'custom';
 }
 
+export const themeVariations = { warmer: 'Warmer', quieter: 'Quieter', expressive: 'More expressive', compact: 'More compact' };
+/** Nearby choices reuse the same bounded semantics; locks protect whole decision families. */
+export function nearbyVariation(input, kind, locks = []) {
+  const recipe = validateRecipe(input);
+  if (!Object.hasOwn(themeVariations, kind)) throw new Error('Unknown theme variation.');
+  const deltas = {
+    warmer: { warmth: .15 }, quieter: { 'color-intensity': -.12, glow: -.1, 'outer-depth': -.15 },
+    expressive: { finish: .15, 'edge-light': .15, glow: .1 }, compact: { 'control-roominess': -.15, spacing: -.1 },
+  }[kind];
+  const values = { ...recipe.values };
+  for (const [id, delta] of Object.entries(deltas)) {
+    const field = themeFields.find(item => item.id === id);
+    const family = field.family === 'Colour' ? 'palette' : field.family === 'Material' ? 'material' : 'type';
+    if (!locks.includes(family)) values[id] = String(Number(Math.max(field.min, Math.min(field.max, Number(values[id]) + delta)).toFixed(3)));
+  }
+  return validateRecipe({ ...recipe, values });
+}
+
 const scalar = /^[+]?(?:\d+(?:\.\d*)?|\.\d+)$/;
 const length = /^(?:0|[+]?(?:\d+(?:\.\d*)?|\.\d+)(?:px|rem|em|ex|ch|cap|ic|lh|rlh|vw|vh|vi|vb|vmin|vmax|svw|svh|lvw|lvh|dvw|dvh|cm|mm|Q|in|pt|pc))$/;
 const font = /^(?:"[^"\\;{}<>@\x00-\x1f]+"|'[^'\\;{}<>@\x00-\x1f]+'|[\p{L}_-][\p{L}\p{N}_ -]*)(?:\s*,\s*(?:"[^"\\;{}<>@\x00-\x1f]+"|'[^'\\;{}<>@\x00-\x1f]+'|[\p{L}_-][\p{L}\p{N}_ -]*))*$/u;
@@ -122,6 +146,7 @@ export function validateRecipe(input) {
     const value = values[field.id];
     let valid = typeof value === 'string' && value.length > 0;
     if (valid) switch (field.type) {
+      case 'choice': valid = Object.hasOwn(field.choices, value); break;
       case 'colour': valid = /^#[\da-f]{6}$/i.test(value); break;
       case 'font': valid = font.test(value); break;
       case 'length': valid = length.test(value) && Number.isFinite(parseFloat(value)); break;
@@ -143,7 +168,9 @@ export function validateRecipe(input) {
     }
   }
   if (input.presets !== undefined && (!input.presets || typeof input.presets !== 'object' || Array.isArray(input.presets) || Object.entries(input.presets).some(([family, id]) => !Object.hasOwn(refinementPresets(family) ?? {}, id)))) throw new Error('Unknown refinement preset.');
-  return { schemaVersion: 1, values, ...(input.presets === undefined ? {} : { presets: { ...input.presets } }) };
+  if (input.fonts !== undefined && (!input.fonts || typeof input.fonts !== 'object' || Array.isArray(input.fonts) || Object.entries(input.fonts).some(([key, family]) => !['body-font', 'display-font'].includes(key) || !Object.hasOwn(googleFonts, family) || values[key] !== googleFontStack(family)))) throw new Error('Choose a Google font with its matching font stack.');
+  if (input.origin !== undefined && !Object.hasOwn(startingPoints, input.origin)) throw new Error('Unknown theme origin.');
+  return { schemaVersion: 1, values, ...(input.fonts === undefined ? {} : { fonts: { ...input.fonts } }), ...(input.origin === undefined ? {} : { origin: input.origin }), ...(input.presets === undefined ? {} : { presets: { ...input.presets } }) };
 }
 
 /** Match presets by their complete semantic recipe, including locally saved themes. */
@@ -153,7 +180,6 @@ export function startingPointFor(input) {
 }
 
 const rgb = hex => [1, 3, 5].map(i => parseInt(hex.slice(i, i + 2), 16));
-const mix = (a, b, weight) => '#' + rgb(a).map((n, i) => Math.round(n * weight + rgb(b)[i] * (1 - weight)).toString(16).padStart(2, '0')).join('');
 const luminance = hex => rgb(hex).map(n => { const s = n / 255; return s <= .04045 ? s / 12.92 : ((s + .055) / 1.055) ** 2.4; }).reduce((sum, n, i) => sum + n * [.2126, .7152, .0722][i], 0);
 const contrast = (a, b) => (Math.max(luminance(a), luminance(b)) + .05) / (Math.min(luminance(a), luminance(b)) + .05);
 // The brightest reflection stop is itself readable. Interpolating it over a readable
@@ -177,29 +203,38 @@ function readableColour(seed, surfaces, minimum, endpoint) {
 }
 
 /** Resolve editable colour seeds into a coordinated set of readable semantic roles. */
+const paletteCache = new Map();
 export function deriveTheme(input, { mode } = {}) {
   if (mode !== undefined && !['light', 'dark'].includes(mode)) throw new Error('Unknown theme color mode.');
   const { values } = validateRecipe(input);
-  const tokens = Object.fromEntries(themeFields.map(field => [field.property, values[field.id]]));
+  const tokens = Object.fromEntries(themeFields.filter(field => field.property).map(field => [field.property, values[field.id]]));
   for (const field of themeFields.filter(field => field.type.includes('length') && Object.hasOwn(bounds, field.id))) {
     if (boundedNumber(field, values[field.id]) === undefined) {
-      const [min, max] = bounds[field.id]; tokens[field.property] = `clamp(${min}px, ${values[field.id]}, ${max}px)`;
+      const [min, max] = bounds[field.id]; tokens[field.property] = `clamp(${min / 16}rem, ${values[field.id]}, ${max / 16}rem)`;
     }
   }
+  const cacheKey = JSON.stringify([mode, ...paletteKeys.map(key => values[key])]);
+  if (paletteCache.has(cacheKey)) {
+    const cached = paletteCache.get(cacheKey);
+    return { tokens: { ...tokens, ...cached.tokens }, adjustments: cached.adjustments.map(item => ({ ...item })) };
+  }
+  const geometry = new Set(Object.keys(tokens));
+  const seeds = paletteSeeds(values);
   const adjustments = [];
-  const nativeInk = foreground(values.canvas, '#ffffff', '#000000');
+  const nativeInk = foreground(seeds.canvas, '#ffffff', '#000000');
   const ink = mode === 'light' ? '#000000' : mode === 'dark' ? '#ffffff' : nativeInk;
   const paper = ink === '#000000' ? '#ffffff' : '#000000';
   // Preserve the requested palette in its native mode. The companion keeps a restrained
   // tint of the same surface seeds; contrast resolution below governs all usable roles.
-  const companionSurface = mix(values.text, paper, .8);
-  const surface = seed => readableColour(nativeInk === ink ? seed : mix(seed, companionSurface, .02), [ink], 7, paper);
-  tokens['--ui-surface'] = surface(values.canvas);
-  tokens['--ui-surface-raised'] = surface(values.surface);
+  const surface = seed => readableColour(nativeInk === ink ? seed : companionSurface(seed, mode ?? (ink === '#000000' ? 'light' : 'dark')), [ink], 7, paper);
+  tokens['--ui-surface'] = surface(seeds.canvas);
+  tokens['--ui-surface-raised'] = surface(seeds.surface);
   tokens['--ui-surface-sunken'] = surface(mix(tokens['--ui-surface-raised'], tokens['--ui-surface'], .92));
   const surfaces = ['--ui-surface', '--ui-surface-raised', '--ui-surface-sunken'].map(name => tokens[name]);
-  const tones = { accent: values.action, danger: '#c92d1e', success: '#007a33', warning: '#ba5b0b', info: '#0066cc' };
-  for (const [tone, seed] of Object.entries(tones)) {
+  const tones = { accent: seeds.action, danger: '#c92d1e', success: '#007a33', warning: '#ba5b0b', info: '#0066cc' };
+  for (const [tone, original] of Object.entries(tones)) {
+    const [l, c, h] = toLch(original);
+    const seed = tone === 'accent' ? original : fromLch([l, c * (.6 + Number(values['color-intensity']) * .8), h]);
     const fill = readableColour(seed, surfaces, 5, ink);
     tokens[`--ui-${tone}`] = fill;
     tokens[`--ui-on-${tone}`] = foreground(fill, '#ffffff', '#000000');
@@ -214,7 +249,7 @@ export function deriveTheme(input, { mode } = {}) {
   for (const tone of Object.keys(tones)) {
     tokens[`--ui-${tone}-subtle-text`] = readableColour(tokens[`--ui-${tone}`], readingSurfaces, 4.5, ink);
   }
-  const textSeed = nativeInk === ink ? values.text : mix(values.text, ink, .08);
+  const textSeed = nativeInk === ink ? seeds.text : mix(seeds.text, ink, .08);
   tokens['--ui-text'] = readableColour(textSeed, readingSurfaces, 4.5, ink);
   tokens['--ui-text-secondary'] = readableColour(mix(tokens['--ui-text'], tokens['--ui-surface-raised'], .72), readingSurfaces, 4.5, ink);
   tokens['--ui-text-muted'] = tokens['--ui-text-secondary'];
@@ -232,16 +267,19 @@ export function deriveTheme(input, { mode } = {}) {
   tokens['--ui-control-border'] = readableColour(mix(tokens['--ui-text'], tokens['--ui-surface-raised'], .43), readingSurfaces, 3, ink);
   tokens['--ui-control-border-hover'] = tokens['--ui-control-border'];
   tokens['--ui-border-strong'] = tokens['--ui-control-border'];
-  tokens['--ui-disabled-text'] = tokens['--ui-text-secondary'];
+  tokens['--ui-disabled-text'] = mix(tokens['--ui-text'], tokens['--ui-surface-raised'], .45);
   tokens['--ui-disabled-surface'] = tokens['--ui-surface-sunken'];
-  tokens['--ui-disabled-border'] = tokens['--ui-control-border'];
+  tokens['--ui-disabled-border'] = mix(tokens['--ui-text'], tokens['--ui-surface-raised'], .2);
   tokens['--ui-focus-ring'] = readableColour(tokens['--ui-accent'], readingSurfaces, 3, ink);
   tokens['--ui-focus-width'] = 'max(2px, calc(var(--ui-border-width) * 2))';
   tokens['color-scheme'] = ink === '#000000' ? 'light' : 'dark';
   for (const [id, property] of [['action', '--ui-accent'], ['canvas', '--ui-surface'], ['surface', '--ui-surface-raised'], ['text', '--ui-text']]) {
     if (tokens[property].toLowerCase() !== values[id].toLowerCase()) adjustments.push({ id, requested: values[id], resolved: tokens[property], reason: 'Adjusted to keep the shared palette readable.' });
   }
-  return { tokens, adjustments };
+  const colors = Object.fromEntries(Object.entries(tokens).filter(([key]) => !geometry.has(key) || /^#[\da-f]{6}$/i.test(tokens[key])));
+  paletteCache.set(cacheKey, { tokens: colors, adjustments });
+  if (paletteCache.size > 16) paletteCache.delete(paletteCache.keys().next().value);
+  return { tokens, adjustments: adjustments.map(item => ({ ...item })) };
 }
 
 /** Shared public seeds; combine with theme-system.css for a standalone exported theme. */
@@ -251,6 +289,8 @@ export function themeCSS(input, systemCSS = '', { scope = 'portable' } = {}) {
   const selector = scope === 'documentation'
     ? ':root[data-looma-documentation-theme], :root[data-looma-documentation-theme] [data-theme], :root[data-looma-documentation-theme] [data-contrast]'
     : ':root, [data-theme], [data-contrast]';
+  const fontURL = googleFontURL(validateRecipe(input).fonts);
+  const imports = fontURL ? `@import url("${fontURL}");\n` : '';
   const light = deriveTheme(input, { mode: 'light' }).tokens;
   const dark = deriveTheme(input, { mode: 'dark' }).tokens;
   const palette = [], geometry = [];
@@ -269,5 +309,5 @@ export function themeCSS(input, systemCSS = '', { scope = 'portable' } = {}) {
   // Resolve colors at their point of use, so a nearer mode boundary wins independently
   // of the selector specificity needed to restore an early documentation theme.
   // Keep the first comment stable: the local writer recognizes its generated files by this marker.
-  return `/* Looma shared semantic theme. */\n/* Always includes light and dark.\n   Set data-theme="light" or "dark" on any element to fix that subtree's mode.\n   Leave the root attribute unset to follow the system; a switch can set/remove it. */\n${systemCSS}\n${geometrySelector} {\n${geometry.join('\n')}\n}\n${selector} {\n${palette.join('\n')}\n}\n${chevrons}\n:root:not([data-theme]) { color-scheme: light dark; }\n[data-theme="light"] { color-scheme: light; }\n[data-theme="dark"] { color-scheme: dark; }\n@media (prefers-reduced-motion: reduce) {\n  ${selector} { --ui-motion-fast: 0ms; --ui-motion-base: 0ms; --ui-motion-press: 0ms; --ui-press-scale: 1; }\n}\n@media (prefers-reduced-transparency: reduce), (forced-colors: active) {\n  ${selector} { --ui-finish: 0; --ui-glow: 0; }\n}\n`;
+  return `/* Looma shared semantic theme. */\n/* Always includes light and dark.\n   Set data-theme="light" or "dark" on any element to fix that subtree's mode.\n   Leave the root attribute unset to follow the system; a switch can set/remove it. */\n${imports}${systemCSS}\n${geometrySelector} {\n${geometry.join('\n')}\n}\n${selector} {\n${palette.join('\n')}\n}\n${chevrons}\n:root:not([data-theme]) { color-scheme: light dark; }\n[data-theme="light"] { color-scheme: light; }\n[data-theme="dark"] { color-scheme: dark; }\n@media (prefers-reduced-motion: reduce) {\n  ${selector} { --ui-motion-fast: 0ms; --ui-motion-base: 0ms; --ui-motion-press: 0ms; --ui-press-scale: 1; }\n}\n@media (prefers-reduced-transparency: reduce), (forced-colors: active) {\n  ${selector} { --ui-finish: 0; --ui-glow: 0; }\n}\n`;
 }

package/docs/value-editors.mjs

@@ -3,26 +3,28 @@ const lengthUnits = { px: 1, rem: 16, em: 16, cm: 96 / 2.54, mm: 96 / 25.4, Q: 9
 const timeUnits = { ms: 1, s: 1000 };
 const rounded = value => String(Number(Number(value).toFixed(6)));
 
-export function valueEditor(field, value, { remPixels = 16 } = {}) {
+export function valueEditor(field, value) {
+  if (field.type === 'choice') return { kind: 'choice', value };
   if (field.type === 'easing') return { kind: /^step-/.test(value) ? 'text' : 'curve', value };
   if (['colour', 'font'].includes(field.type)) return { kind: 'text', value };
   if (field.type.includes('length') || field.type === 'time') {
     const unit = value.match(/[a-z]+$/i)?.[0] ?? 'px';
-    const units = field.type === 'time' ? timeUnits : { ...lengthUnits, rem: remPixels, em: remPixels };
+    // Relative limits stay root-scaled when the user enlarges their default font.
+    const units = field.type === 'time' ? timeUnits : lengthUnits;
     const factor = units[unit];
     return { kind: 'number', value: value === '0' ? '0px' : value, unit,
       min: factor ? field.min / factor : .001, max: factor ? field.max / factor : 1000000,
       step: (field.type === 'time' ? 10 : field.id === 'line-weight' ? .25 : 1) / (factor ?? 1),
       units: field.type === 'time' ? ['ms', 's'] : ['px', 'rem'], convertible: Boolean(factor) };
   }
-  const scale = field.type === 'fraction' || field.id === 'density' ? 100 : 1;
+  const scale = field.type === 'fraction' || field.id === 'spacing' ? 100 : 1;
   return { kind: field.type === 'weight' ? 'number' : 'slider', value: field.type === 'weight' ? value : Number(value) * scale,
     min: field.min * scale, max: field.max * scale, step: field.type === 'weight' ? 50 : scale === 100 ? 1 : .01,
     unit: scale === 100 ? '%' : '', scale };
 }
 
 export function editorValue(field, value) {
-  return field.type === 'fraction' || field.id === 'density' ? rounded(Number(value) / 100) : String(value);
+  return field.type === 'fraction' || field.id === 'spacing' ? rounded(Number(value) / 100) : String(value);
 }
 
 export function convertValueUnit(value, nextUnit, { remPixels = 16 } = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@threadlabs/looma",
-  "version": "0.35.1",
+  "version": "0.36.0",
   "type": "module",
   "description": "Looma components as HTML, Vue, and plain DOM, with design tokens.",
   "license": "MIT",
@@ -127,7 +127,7 @@
     "@tiptap/pm": ">=2 <3",
     "@tiptap/vue-3": ">=2 <3",
     "vue": "^3.5.43",
-    "markupress": "^0.8.5",
+    "markupress": "^0.8.6",
     "@nextwebwg/htmlkit": "1.0.0-alpha.69",
     "vite": "^8.3.4"
   },

package/styles/ui-button.css

@@ -145,7 +145,9 @@
       line-height: var(--ui-line-height-tight);
       padding: var(--ui-control-inset-block-md, var(--ui-space-2)) var(--ui-action-inset-md, var(--ui-space-3)) !important;
       background-image: var(--ui-surface-highlight, none);
-      box-shadow: var(--ui-button-shadow, var(--ui-action-shadow, var(--_ui-action-shadow))), var(--_tone-glow);
+      box-shadow:
+        var(--ui-button-shadow, var(--ui-action-shadow, var(--_ui-action-shadow))),
+        var(--_tone-glow);
       cursor: pointer;
       transition:
         scale var(--ui-motion-press, var(--ui-motion-fast)) var(--ui-motion-ease),
@@ -278,7 +280,9 @@
       background-color: var(--_tone);
       color: var(--_on-tone);
       background-image: var(--_tone-highlight);
-      box-shadow: var(--ui-button-solid-shadow, var(--ui-action-shadow, var(--_ui-action-shadow))), var(--_tone-glow);
+      box-shadow:
+        var(--ui-button-solid-shadow, var(--ui-action-shadow, var(--_ui-action-shadow))),
+        var(--_tone-glow);
     }
 
     :is(:scope:where([data-component~="ui-button"])[data-appearance="solid"], :scope:where([data-component~="ui-button"])[data-appearance="danger"]):hover:not(:disabled, [aria-disabled="true"]) {
@@ -448,8 +452,11 @@
 
     /* The size states outrank :host, so sm is named too, or a small button would stay small. */
     @media (pointer: coarse) {
-      :scope:where([data-component~="ui-button"]), :scope:where([data-component~="ui-button"])[data-ui-button-state~="size=sm"] {
-        min-block-size: var(--ui-control-min-block-size);
+      :scope:where([data-component~="ui-button"]) {
+        min-block-size: max(var(--ui-control-size-md), var(--ui-control-min-block-size));
+      }
+      :scope:where([data-component~="ui-button"])[data-ui-button-state~="size=sm"] {
+        min-block-size: max(var(--ui-control-size-sm), var(--ui-control-min-block-size));
       }
     }
 

package/styles/ui-color-picker.css

@@ -109,7 +109,7 @@
         --_size: max(var(--ui-control-size-md), var(--ui-control-min-block-size));
       }
       :scope:where([data-component~="ui-color-picker"])[data-ui-color-picker-state~="size=sm"] {
-        --_size: var(--ui-control-min-block-size);
+        --_size: max(var(--ui-control-size-sm), var(--ui-control-min-block-size));
         --_font: var(--ui-font-size-md);
       }
     }

package/styles/ui-combobox.css

@@ -320,7 +320,7 @@
       /* Under touch a small field is still a touch-sized target, as a small button is, and keeps
          body-size text: below 16px, iOS zooms the page into the focused field. */
       :scope:where([data-component~="ui-combobox"])[data-ui-combobox-state~="size=sm"] {
-        --_row: var(--ui-control-min-block-size);
+        --_row: max(var(--ui-control-size-sm), var(--ui-control-min-block-size));
       }
       :scope:where([data-component~="ui-combobox"])[data-ui-combobox-state~="size=sm"] input {
         font-size: inherit;
@@ -732,7 +732,7 @@
       /* Under touch a small field is still a touch-sized target, as a small button is, and keeps
          body-size text: below 16px, iOS zooms the page into the focused field. */
       :where([data-component~="ui-combobox"])[data-ui-combobox-state~="size=sm"]:where(:scope, :not([data-component], [data-slotted]:not([data-slotted~="ui-combobox"]))) {
-        --_row: var(--ui-control-min-block-size);
+        --_row: max(var(--ui-control-size-sm), var(--ui-control-min-block-size));
       }
       :where([data-component~="ui-combobox"])[data-ui-combobox-state~="size=sm"] input:where(:scope, :not([data-component], [data-slotted]:not([data-slotted~="ui-combobox"]))) {
         font-size: inherit;

package/styles/ui-input.css

@@ -117,7 +117,10 @@
       }
 
       :scope:where([data-component~="ui-input"])[data-ui-input-state~="size=sm"] {
-        min-block-size: var(--ui-input-min-block-size, var(--_ui-default-input-min-block-size, var(--ui-control-min-block-size)));
+        min-block-size: var(
+          --ui-input-min-block-size,
+          var(--_ui-default-input-min-block-size, max(var(--ui-control-size-sm), var(--ui-control-min-block-size)))
+        );
       }
     }