@threadlabs/looma 0.39.1 → 0.39.2

package/docs/README.md

@@ -86,17 +86,28 @@ The generated values follow rules. The medium control height is base text size t
 
 Choose a coordinated palette, then refine surface warmth, color intensity and palette relationship. Warmth runs from cool to warm paper and ink, with 0.5 neutral; intensity runs from quiet to vivid, with 0.5 retaining original seed intensity. Keep my colors preserves the base hues; Related colors and Contrasting colors tint quiet surfaces toward neighboring and opposite hues. These decisions regenerate paired light/dark colors through Oklab/OKLCH operations, gamut repair and readability checks. They do not transform existing CSS colors live. Four Base colors remain visible for precise edits; the light/dark range previews and resolved values explain adjustments.
 
-The customizer uses Starting point, Palette and Material as its controls sidebar, with documentation navigation left out of this workspace. Detailed type, size and motion controls, example selection and exports open when needed.
+Documentation navigation stays out of the customization workspace. **Material & light** opens a movable light source, real component samples and bounded surface controls. **Palette** opens the coordinated light/dark ranges and their four Base colors. Each editor changes the same persistent theme. Returning to the overview, navigating to a component, or reloading keeps the result.
 
-The main customizer offers Material and Palette presets. **Refine material & light** opens a focused view with a movable light source, real component samples and bounded surface controls. **Refine palette** opens the coordinated light/dark ranges and their four Base colors. Both views edit the same theme as the main customizer. Returning to the overview, navigating to a component, or reloading keeps the result.
+A refined preset keeps its name with “customized” beside it. **Reset material** resets only material and light; **Reset palette** resets only the palette. These family choices are recorded in the recipe's optional `presets` mapping. The `values` mapping remains the complete source of the generated theme; a preset is a named combination of those values.
 
-A refined preset keeps its name with “customized” beside it. **Restore material preset** resets only material and light; **Restore palette preset** resets only the palette. These family choices are recorded in the recipe's optional `presets` mapping. The `values` mapping remains the complete source of the generated theme; a preset is a named combination of those values.
-
-Number controls accept arithmetic such as `1rem / 1.2` or `150ms * 2`, calculate on entry and show the result. Unit changes preserve the quantity. Sliders include exact entry, and curve handles support dragging and arrow keys alongside numeric coordinates. Light and curve drags preserve the grab offset; Escape or pointer cancellation restores the gesture start without creating a saved edit.
+Number controls accept arithmetic such as `1rem / 1.2` or `150ms * 2`, calculate on entry and show the result. Unit changes preserve the quantity. Sliders include exact entry, and curve handles support dragging and arrow keys alongside numeric coordinates. LightEditor keeps its coordinate fields under **Exact position**. Light and curve drags preserve the grab offset; Escape or pointer cancellation restores the gesture start without creating a saved edit.
 
 Lengths retain their CSS units, such as `rem`; times retain `ms` or `s`. The downloaded CSS includes the canonical shared CSS derivation rules as well as resolved theme values. Download JSON separately to retain editable decisions and font/preset provenance. Import a downloaded JSON recipe to continue editing it. Keep hand-written CSS in a separate overrides file so regenerating the theme does not replace it.
 
-Undo and Redo move through accepted recipe changes. There is no page-entry comparison state: reopening the customizer does not create a hidden before/after reference. **Explore nearby styles** previews Warmer, Quieter, More expressive or More compact before you apply it. Palette, Material and Type & spacing locks preserve those families during variations. Cancel preview returns to the current recipe.
+The customizer opens on a dashboard summarizing the current starting theme, palette,
+material, typography, spacing and motion. Open a summary to edit that subject; use
+**Overview** to return to the same dashboard position. Only the active editor shows
+its controls. Precise adjustments sit inside the relevant editor's detail sections.
+
+Typography pairs font selection with headings and body text. Size & spacing shows
+the shared control ladder and grouped content. Motion keeps a replayable study and
+a real popover beside duration and curve editing; the study follows the shared
+curve, travels at three times the feedback duration, and respects reduced motion.
+**Browse components** searches the complete catalog, with previews loaded in batches.
+**Export & save** contains downloads, recipe import and local repository saving.
+
+Edits apply immediately. Undo and Redo move through completed changes; Reset restores
+the current starting theme. There is no separate variation preview or apply step.
 
 Changes apply throughout the documentation and remain in this browser across navigation and reload until reset. Repository files change only when you save locally. Starting points update the shell and all selected cards. Reset restores the selected starting theme’s values and remains undoable. Removing the header’s Custom theme chip instead clears the browser override and restores the repository baseline. Invalid input keeps the last valid preview and explains which decision needs attention.
 

package/docs/catalog.json

@@ -458,7 +458,7 @@
   ],
   "schemaVersion": 1,
   "package": "@threadlabs/looma",
-  "version": "0.39.1",
+  "version": "0.39.2",
   "groups": [
     {
       "id": "layout",
@@ -4220,7 +4220,7 @@
           "name": "99-theme-sampler",
           "title": "Theme sampler",
           "description": "A compact collection of real controls and a surface for judging a shared theme together.",
-          "markup": "<ui-card treatment=\"expressive\" padding=\"sm\"><ui-stack gap=\"s\">\n    <ui-cluster gap=\"xs\" justify=\"between\"><ui-text variant=\"eyebrow\">Fellowship office</ui-text><ui-badge tone=\"success\">Ready</ui-badge></ui-cluster>\n    <ui-text variant=\"heading\" as=\"h3\">Second breakfast, sorted.</ui-text>\n    <ui-text>Frodo plans. Sam follows through.</ui-text>\n    <ui-text variant=\"caption\">Briefing at nine · Bring the maps.</ui-text>\n    <ui-cluster gap=\"s\">\n      <ui-button size=\"sm\" variant=\"solid\" tone=\"accent\">Solid accent</ui-button>\n      <ui-button size=\"sm\" variant=\"outline\" tone=\"accent\">Outline accent</ui-button>\n      <ui-button size=\"sm\" variant=\"solid\" tone=\"neutral\">Solid neutral</ui-button>\n      <ui-button size=\"sm\" variant=\"outline\" tone=\"neutral\">Outline neutral</ui-button>\n      <ui-icon-button size=\"sm\" variant=\"outline\" tone=\"neutral\" match-button label=\"Acknowledge memo\"><ui-icon name=\"circle-check\"></ui-icon></ui-icon-button>\n      <ui-button size=\"sm\" variant=\"ghost\" tone=\"neutral\">Ghost</ui-button>\n    </ui-cluster>\n    <ui-input-group><ui-icon slot=\"prefix\" name=\"search\"></ui-icon><ui-input\n        size=\"sm\"\n        aria-label=\"Search office\"\n        placeholder=\"Search Fellowship office\"\n      ></ui-input></ui-input-group>\n    <ui-cluster gap=\"s\"><ui-checkbox size=\"sm\" checked>Notify Sam</ui-checkbox><ui-switch size=\"sm\" checked>Available</ui-switch><ui-badge tone=\"accent\"\n      >Draft</ui-badge></ui-cluster>\n  </ui-stack></ui-card>",
+          "markup": "<ui-card treatment=\"expressive\"><ui-stack gap=\"l\">\n    <ui-cluster gap=\"xs\" justify=\"between\"><ui-text variant=\"eyebrow\">Fellowship office</ui-text><ui-badge tone=\"success\">Ready</ui-badge></ui-cluster>\n    <ui-stack gap=\"s\"><ui-text variant=\"heading\" as=\"h3\">Second breakfast, sorted.</ui-text>\n      <ui-text>Frodo plans. Sam follows through.</ui-text>\n      <ui-text variant=\"caption\">Briefing at nine · Bring the maps.</ui-text></ui-stack>\n    <ui-cluster>\n      <ui-button variant=\"solid\" tone=\"accent\" title=\"Solid accent\">Send</ui-button>\n      <ui-button variant=\"outline\" tone=\"accent\" title=\"Outline accent\">Save</ui-button>\n      <ui-button variant=\"solid\" tone=\"neutral\" title=\"Solid neutral\">File</ui-button>\n      <ui-button variant=\"outline\" tone=\"neutral\" title=\"Outline neutral\">Archive</ui-button>\n      <ui-icon-button variant=\"outline\" tone=\"neutral\" match-button label=\"Acknowledge memo\"><ui-icon name=\"circle-check\"></ui-icon></ui-icon-button>\n      <ui-button variant=\"ghost\" tone=\"neutral\" title=\"Ghost neutral\">Later</ui-button>\n    </ui-cluster>\n    <ui-input-group><ui-icon slot=\"prefix\" name=\"search\"></ui-icon><ui-input\n        aria-label=\"Search office\"\n        placeholder=\"Search Fellowship office\"\n      ></ui-input></ui-input-group>\n    <ui-cluster><ui-checkbox checked>Notify Sam</ui-checkbox><ui-switch checked>Available</ui-switch><ui-badge tone=\"accent\">Draft</ui-badge></ui-cluster>\n  </ui-stack></ui-card>",
           "resizable": false,
           "bindings": "",
           "frameworks": {}

package/docs/customizer-render.mjs

@@ -2,7 +2,7 @@ import { googleFonts, systemFont } from './fonts.mjs';
 import { escapeHtml as escape } from './catalog.mjs';
 import { componentPath, previewPath } from './render.mjs';
 import { valueEditor } from './value-editors.mjs';
-import { defaultRecipe, themeFields, startingPoints, startingPointLabels, startingPointFor, deriveTheme, applyRefinement, themeCSS, validateRecipe, themePalettes, materialPresets, refinementState, themeVariations } from './theme.mjs';
+import { defaultRecipe, themeFields, startingPoints, startingPointLabels, startingPointFor, deriveTheme, applyRefinement, themeCSS, validateRecipe, themePalettes, materialPresets, refinementState } from './theme.mjs';
 
 export function customizerResource(site, input = defaultRecipe()) {
   const recipe = validateRecipe(input);
@@ -21,7 +21,7 @@ export function customizerResource(site, input = defaultRecipe()) {
     let control;
     if (field.type === 'font') {
       const selected = field.id === 'display-font' && value === recipe.values['body-font'] ? 'inherit' : recipe.fonts?.[field.id] ?? (value === systemFont ? 'system' : 'custom');
-      control = `<ui-combobox id="theme-${field.id}" data-font-picker="${field.id}" label="${escape(field.label)}" value="${escape(selected)}" placeholder="Search Google Fonts…" disclosure>${field.id === 'display-font' ? '<option value="inherit">Same as main font</option>' : ''}<option value="system">System font</option><option value="custom" disabled>Custom font stack</option>${Object.values(googleFonts).map(font => `<option value="${escape(font.family)}" data-description="Google Fonts · ${font.category}">${escape(font.family)}</option>`).join('')}</ui-combobox><ui-text variant="${field.id === 'display-font' ? 'heading' : 'body'}">Frodo’s quarterly review · Aa 0123</ui-text><ui-text variant="caption" data-font-status="${field.id}" role="status">System fonts need no download. Google selections load in this preview and travel in your CSS.</ui-text><ui-disclosure summary="Custom font stack"><ui-input id="theme-${field.id}-custom" ${common} value="${escape(value)}" aria-label="${escape(field.label)} stack"></ui-input><ui-text variant="caption">For an already loaded or self-hosted font.</ui-text></ui-disclosure>`;
+      control = `<ui-combobox id="theme-${field.id}" data-font-picker="${field.id}" label="${escape(field.label)}" value="${escape(selected)}" placeholder="Search Google Fonts…" disclosure>${field.id === 'display-font' ? '<option value="inherit">Same as main font</option>' : ''}<option value="system">System font</option><option value="custom" disabled>${escape(value.split(',')[0].replaceAll('"', '').trim())}</option>${Object.values(googleFonts).map(font => `<option value="${escape(font.family)}" data-description="Google Fonts · ${font.category}">${escape(font.family)}</option>`).join('')}</ui-combobox><ui-text variant="caption" data-font-status="${field.id}" role="status">Google fonts preview here and are included in your CSS.</ui-text><ui-disclosure summary="Custom font stack"><ui-input id="theme-${field.id}-custom" ${common} value="${escape(value)}" aria-label="${escape(field.label)} stack"></ui-input><ui-text variant="caption">For an already loaded or self-hosted font.</ui-text></ui-disclosure>`;
     } else if (field.type === 'choice') {
       control = `<ui-select id="theme-${field.id}" ${common} value="${escape(value)}">${Object.entries(field.choices).map(([id,label]) => `<option value="${id}">${escape(label)}</option>`).join('')}</ui-select>`;
     } else if (field.type === 'easing') {
@@ -31,8 +31,9 @@ export function customizerResource(site, input = defaultRecipe()) {
       const numeric = `<${tag} id="theme-${field.id}" ${common} data-editor-kind="${editor.kind}" value="${escape(editor.value)}" unit="${editor.unit}" min="${editor.min}" max="${editor.max}" step="${editor.step}"></${tag}>`;
       control = editor.units ? `<ui-cluster wrap="nowrap" gap="xs">${numeric}<ui-select size="sm" style="--ui-select-inline-size: auto" data-unit-for="${field.id}" aria-label="${escape(field.label)} unit" value="${editor.unit}">${[...new Set([...editor.units, editor.unit])].map(unit => `<option value="${unit}">${unit}</option>`).join('')}</ui-select></ui-cluster>` : numeric;
     } else {
-      control = `<ui-cluster wrap="nowrap" gap="xs">${field.type === 'colour' ? `<ui-color-picker size="sm" data-token="${field.id}" value="${escape(value)}" label="${escape(field.label)} colour picker"></ui-color-picker>` : ''}<ui-input id="theme-${field.id}" size="sm" data-token="${field.id}" value="${escape(value)}" aria-label="${escape(field.label)}"></ui-input></ui-cluster>`;
+      control = field.type === 'colour' ? `<ui-color-picker id="theme-${field.id}" data-token="${field.id}" value="${escape(value)}" label="${escape(field.label)} colour picker"></ui-color-picker>` : `<ui-input id="theme-${field.id}" ${common} value="${escape(value)}"></ui-input>`;
     }
+    if (field.type === 'font') return `<ui-stack gap="s">${control}</ui-stack>`;
     return `<ui-form-field><label slot="label" for="theme-${field.id}">${escape(field.label)}</label><span slot="help">${escape(field.description)}</span>${control}</ui-form-field>`;
   };
   const swatches = tokens => `<span class="palette-swatches" aria-hidden="true">${['--ui-accent','--ui-neutral-surface','--ui-surface','--ui-text'].map(token => `<span style="background:${escape(tokens ? tokens[token] : `var(${token})`)}"></span>`).join('')}</span>`;
@@ -52,52 +53,52 @@ export function customizerResource(site, input = defaultRecipe()) {
     ['neighboring', 'Related colors', 'Tint neutral surfaces with a neighboring hue for a closely coordinated palette.'],
     ['complementary', 'Contrasting colors', 'Tint neutral surfaces toward the opposite hue for warm–cool contrast.'],
   ].map(([id,label,description]) => `<ui-button variant="card" tone="neutral" data-action="palette-relationship" data-relationship="${id}" aria-pressed="${recipe.values['palette-relationship'] === id}"><ui-stack gap="xs"><ui-text variant="label">${label}</ui-text><span class="palette-range" data-relationship-preview="${id}" aria-hidden="true"><span class="palette-canvas"></span><span class="palette-content"></span><span class="palette-action"></span></span><ui-text variant="caption">${description}</ui-text></ui-stack><span slot="action" data-relationship-selected="${id}"${recipe.values['palette-relationship'] === id ? '' : ' hidden'}><ui-icon name="check"></ui-icon></span></ui-button>`).join('')}</ui-stack>`;
-  const supplements = {
-    'Colour': `${renderPreset('palette', 'overview')}<ui-text variant="caption">Colors only, in light and dark. Starting points also set type, shape, material and motion.</ui-text><ui-button data-action="refine-palette">Refine palette</ui-button>`,
-    'Material': `${renderPreset('material', 'overview')}<ui-text variant="caption">Material and light, shared everywhere.</ui-text><ui-button data-action="refine-material">Refine material & light</ui-button>`,
-    'Motion': `<ui-text variant="caption">Open and close this real documentation example to feel the response pace and curve. Reduced motion follows your system preference.</ui-text>${documentationCard('ui-popover')}`,
-    'Size & spacing': `<ui-text variant="caption">Shared size ladder: buttons, fields and swatches align at each step.</ui-text><ui-stack>${['sm','md','lg'].map((size,index) => `<ui-stack gap="xs" data-size-sample="${size}"><ui-text variant="caption">${['Small','Medium','Large'][index]}<span data-size-readout></span></ui-text><ui-cluster><ui-button size="${size}">Action</ui-button><ui-input size="${size}" style="--ui-input-inline-size: 10ch" label="${size} size sample" value="Frodo"></ui-input><ui-color-picker size="${size}" label="${size} swatch sample"></ui-color-picker></ui-cluster></ui-stack>`).join('')}</ui-stack><div class="spacing-samples" data-spacing-samples role="img" aria-label="Spacing progression"><span></span><span></span><span></span><span></span></div><ui-disclosure summary="How the scale grows"><ui-stack><ui-text>Control roominess relates every field and button to base text. Size ratio separates small from large. Visible proportions stay the same on touch; hit areas are a separate design choice. Spacing and its curve shape page rhythm independently.</ui-text>${themeFields.filter(item => ['scale-contrast','space-curve'].includes(item.id)).map(renderField).join('')}</ui-stack></ui-disclosure>`,
-  };
-  const families = [...new Set(themeFields.map(field => field.family))].filter(family => !['Colour', 'Material'].includes(family)).map(family => `<ui-disclosure summary="${family}"><ui-stack>${themeFields.filter(item => item.family === family && !['scale-contrast', 'space-curve'].includes(item.id)).map(renderField).join('')}${supplements[family] ?? ''}</ui-stack></ui-disclosure>`).join('');
-  const refinement = (family, content) => `<section data-refinement-view="${family}" hidden tabindex="-1" aria-label="${family === 'material' ? 'Material and light refinement' : 'Palette refinement'}"><ui-stack gap="l"><ui-cluster justify="between"><ui-button data-action="back">Back to customization</ui-button><ui-button data-action="restore-${family}">Restore ${family} preset</ui-button></ui-cluster><ui-stack gap="s"><ui-text variant="heading" as="h2">${family === 'material' ? 'Refine material & light' : 'Refine your palette'}</ui-text><ui-text>These are advanced refinements of the same persistent theme. Every change applies throughout your documentation.</ui-text></ui-stack>${renderPreset(family, 'refinement')}${content}</ui-stack></section>`;
-  const materialView = refinement('material', `<div class="refinement-layout"><ui-stack><ui-light-editor data-light-editor x="${recipe.values['light-x']}" y="${recipe.values['light-y']}" label="Theme light position"><ui-stack gap="s"><ui-cluster><ui-button preset="primary">Join briefing</ui-button><ui-button preset="standard">Read memo</ui-button></ui-cluster><ui-input label="Office search" placeholder="Search the Fellowship office"></ui-input></ui-stack></ui-light-editor><ui-cluster><ui-button size="sm" data-action="light-top">Top light</ui-button><ui-button size="sm" data-action="light-left">Upper left</ui-button><ui-button size="sm" data-action="light-center">Centered</ui-button></ui-cluster><ui-text variant="caption" data-material-dependencies role="status"></ui-text>${documentationCard('ui-card','/04-expressive-surface')}<ui-disclosure summary="Try floating surfaces"><ui-stack>${documentationCard('ui-tooltip')}${documentationCard('ui-popover')}${documentationCard('ui-dialog')}</ui-stack></ui-disclosure></ui-stack><ui-stack><ui-text variant="label">Surface response</ui-text>${themeFields.filter(field => ['finish','edge-light','glow'].includes(field.id)).map(renderField).join('')}<ui-text variant="label">Light source</ui-text>${themeFields.filter(field => ['light-spread','light-strength'].includes(field.id)).map(renderField).join('')}<ui-disclosure summary="Depth, glass and separation"><ui-stack>${themeFields.filter(field => ['outer-depth','inner-depth','glassiness','surface-separation','translucency'].includes(field.id)).map(renderField).join('')}</ui-stack></ui-disclosure></ui-stack></div>`);
-  const paletteView = refinement('palette', `<div class="refinement-layout"><div class="palette-preview"><ui-stack>${paletteDetails}</ui-stack></div><ui-stack><ui-text variant="heading" as="h3">Base colors</ui-text><ui-text variant="caption">The colors your theme’s light and dark palettes are built from.</ui-text>${themeFields.filter(field => field.type === 'colour').map(renderField).join('')}${themeFields.filter(field => field.family === 'Colour' && field.type !== 'colour' && field.id !== 'palette-relationship').map(renderField).join('')}${paletteRelationships}</ui-stack></div>`);
+  const sizePreview = `<ui-text variant="caption">Shared size ladder: buttons, fields and swatches align at each step.</ui-text><ui-stack>${['sm','md','lg'].map((size,index) => `<ui-stack gap="xs" data-size-sample="${size}"><ui-text variant="caption">${['Small','Medium','Large'][index]}<span data-size-readout></span></ui-text><ui-cluster><ui-button size="${size}">Action</ui-button><ui-input size="${size}" style="--ui-input-inline-size: 10ch" label="${size} size sample" value="Frodo"></ui-input><ui-color-picker size="${size}" label="${size} swatch sample"></ui-color-picker></ui-cluster></ui-stack>`).join('')}</ui-stack><div class="spacing-samples" data-spacing-samples role="img" aria-label="Spacing progression"><span></span><span></span><span></span><span></span></div>`;
+  const fieldsFor = ids => ids.map(id => renderField(themeFields.find(field => field.id === id))).join('');
+  const viewTitles = { material: 'Material & light', palette: 'Palette', typography: 'Typography', layout: 'Size & spacing', motion: 'Motion', themes: 'Starting theme', export: 'Export & save', components: 'Component library' };
+  const refinement = (family, content) => `<section id="${family}" data-refinement-view="${family}" hidden tabindex="-1" aria-label="${viewTitles[family]} editor"><ui-stack gap="l"><ui-cluster><ui-button data-action="back"><ui-icon name="arrow-left"></ui-icon>Overview</ui-button><ui-text variant="heading" as="h2">${viewTitles[family]}</ui-text></ui-cluster>${content}</ui-stack></section>`;
+  const editor = (family, preview, controls) => refinement(family, `<div class="refinement-layout"><div class="editor-preview" data-editor-preview="${family}">${preview}</div><ui-stack>${controls}</ui-stack></div>`);
+  const typographyView = editor('typography', `<ui-card><ui-stack><ui-text variant="heading" as="h2">There and back again.</ui-text><ui-text>Frodo plans the journey. Sam brings lunch. Clear notes keep the Fellowship moving.</ui-text><ui-text variant="label">Memo ready</ui-text><ui-text variant="caption">Notes by Sméagol · Updated today</ui-text></ui-stack></ui-card>`, `${fieldsFor(['body-font','text-size'])}<ui-disclosure summary="Heading font"><ui-stack>${fieldsFor(['display-font'])}</ui-stack></ui-disclosure><ui-disclosure summary="Label emphasis"><ui-stack>${fieldsFor(['text-weight'])}</ui-stack></ui-disclosure>`);
+  const layoutView = editor('layout', `<ui-stack>${sizePreview}</ui-stack>`, `${fieldsFor(['control-roominess','rhythm','spacing','corner-roundness'])}<ui-disclosure summary="Scale & edges"><ui-stack>${fieldsFor(['scale-contrast','space-curve','line-weight'])}</ui-stack></ui-disclosure>`);
+  const motionView = editor('motion', `<ui-stack><ui-card><ui-stack><ui-text variant="eyebrow">Motion study</ui-text><div class="motion-track"><span data-motion-object aria-hidden="true"></span></div><ui-cluster><ui-button data-action="replay-motion"><ui-icon name="play"></ui-icon>Replay motion</ui-button><ui-text variant="caption" data-motion-readout></ui-text></ui-cluster><ui-text variant="caption" data-motion-preference></ui-text></ui-stack></ui-card></ui-stack>`, `${fieldsFor(['response-time'])}<ui-disclosure summary="Shape the curve"><ui-stack>${fieldsFor(['response-curve'])}</ui-stack></ui-disclosure><ui-text variant="caption">Replay shows the shared curve. Try the popover to feel it in a real component. System reduced-motion preferences are respected.</ui-text><ui-disclosure summary="Try a popover">${documentationCard('ui-popover', null, true)}</ui-disclosure>`);
+  const materialView = editor('material', `<ui-stack><ui-light-editor data-light-editor x="${recipe.values['light-x']}" y="${recipe.values['light-y']}" label="Theme light position"><ui-stack gap="s"><ui-cluster><ui-button preset="primary">Join briefing</ui-button><ui-button preset="standard">Read memo</ui-button></ui-cluster><ui-input label="Office search" placeholder="Search the Fellowship office"></ui-input></ui-stack></ui-light-editor></ui-stack>`, `<ui-cluster>${renderPreset('material', 'refinement')}<ui-button data-action="restore-material">Reset material</ui-button></ui-cluster>${fieldsFor(['finish','edge-light','glow'])}<ui-text variant="caption" data-material-dependencies role="status"></ui-text><ui-disclosure summary="Light source"><ui-stack>${fieldsFor(['light-spread','light-strength'])}</ui-stack></ui-disclosure><ui-disclosure summary="Depth, glass and separation"><ui-stack>${fieldsFor(['outer-depth','inner-depth','glassiness','surface-separation','translucency'])}</ui-stack></ui-disclosure><ui-disclosure summary="Try floating surfaces"><ui-stack>${documentationCard('ui-card','/04-expressive-surface')}${documentationCard('ui-tooltip')}${documentationCard('ui-popover')}${documentationCard('ui-dialog')}</ui-stack></ui-disclosure>`);
+  const paletteView = refinement('palette', `<ui-cluster>${renderPreset('palette', 'refinement')}<ui-button data-action="restore-palette">Reset palette</ui-button></ui-cluster><div class="refinement-layout"><div class="palette-preview"><ui-stack>${paletteDetails}</ui-stack></div><ui-stack><ui-text variant="heading" as="h3">Base colors</ui-text><ui-text variant="caption">The colors your theme’s light and dark palettes are built from.</ui-text>${themeFields.filter(field => field.type === 'colour').map(renderField).join('')}<ui-disclosure summary="Adjust color character"><ui-stack>${themeFields.filter(field => field.family === 'Colour' && field.type !== 'colour' && field.id !== 'palette-relationship').map(renderField).join('')}</ui-stack></ui-disclosure><ui-disclosure summary="Color relationships">${paletteRelationships}</ui-disclosure></ui-stack></div>`);
   const options = site.catalog.groups.map(group => `<optgroup label="${escape(group.label)}">${examples.filter(example => example.category === group.id).map(example => `<option value="${escape(example.id)}" data-description="${escape(example.category + ' · ' + example.tag)}" data-example="${escape(JSON.stringify(example))}" data-search="${escape(`${example.title} ${example.tag} ${example.description} ${example.exampleTitle}`.toLocaleLowerCase())}">${escape(example.title)} · ${escape(example.exampleTitle)}</option>`).join('')}</optgroup>`).join('');
-  const links = ['ui-stack','ui-grid','ui-cluster','ui-form-field','ui-input','ui-select','ui-color-picker','ui-button','ui-disclosure','ui-textarea','ui-number-input','ui-slider','ui-curve-editor','ui-card','ui-text','ui-light-editor','ui-combobox','ui-checkbox'].map(tag => `<link rel="component" href="@threadlabs/looma/components/${tag}/${tag}.html">`).join('\n');
+  const links = ['ui-stack','ui-grid','ui-cluster','ui-form-field','ui-input','ui-select','ui-color-picker','ui-button','ui-disclosure','ui-textarea','ui-number-input','ui-slider','ui-curve-editor','ui-card','ui-text','ui-light-editor','ui-combobox','ui-checkbox','ui-list','ui-list-item'].map(tag => `<link rel="component" href="@threadlabs/looma/components/${tag}/${tag}.html">`).join('\n');
   return `${links}\n<link rel="component" href="./card.html">\n<template component="looma-customizer" module="./customizer.js"><defs>
   <state name="previews" type="list" value="${escape(JSON.stringify(initial))}"><prop type="object">${cardFields.map(name => `<prop name="${name}" required type="${name === 'resizable' ? 'boolean' : 'string'}"></prop>`).join('')}</prop></state>
   <state name="cards" type="list" value="${escape(JSON.stringify(initial))}"><prop type="object">${cardFields.map(name => `<prop name="${name}" required type="${name === 'resizable' ? 'boolean' : 'string'}"></prop>`).join('')}</prop></state>
   </defs>
   <div data-looma-customizer data-recipe="${escape(JSON.stringify(recipe))}" data-base="${escape(site.base)}" data-mode="${site.config.local ? 'local' : 'public'}" data-revision="${escape(site.config.revision ?? '')}">
-  <ui-stack gap="l"><ui-text>Choose a starting point, refine shared decisions, and see them on real documentation examples.</ui-text>
-  <ui-text variant="caption" role="status" aria-live="polite" data-message>Changes are remembered across the documentation.</ui-text>
+  <ui-stack gap="l">
+  <ui-text variant="caption" role="status" aria-live="polite" data-message></ui-text>
   <ui-stack gap="xs"><ui-text variant="eyebrow">Theme changes</ui-text><ui-cluster><ui-button size="sm" data-action="undo" disabled>Undo</ui-button><ui-button size="sm" data-action="redo" disabled>Redo</ui-button><ui-button size="sm" data-action="reset" title="Restore this theme’s starting values">Reset</ui-button></ui-cluster></ui-stack>
-  <ui-disclosure summary="Explore nearby styles"><ui-stack><ui-text variant="caption">Preview a small change before applying it. Locks preserve your selected families.</ui-text><ui-cluster>${[['palette','Palette'],['material','Material'],['type','Type & spacing']].map(([id,label]) => `<ui-checkbox size="sm" data-family-lock="${id}">Lock ${label}</ui-checkbox>`).join('')}</ui-cluster>${choice(`id="nearby-style" data-variation-choice data-selected-value="${Object.keys(themeVariations)[0]}"`, 'Nearby style', Object.keys(themeVariations)[0], Object.entries(themeVariations).map(([id,label]) => `<option value="${id}">${label}</option>`).join(''))}<ui-button data-action="preview-variation">Preview variation</ui-button><div data-variation-confirm hidden><ui-stack><ui-text data-variation-description role="status"></ui-text><ui-cluster><ui-button preset="primary" data-action="apply-variation">Apply variation</ui-button><ui-button data-action="cancel-variation">Cancel preview</ui-button></ui-cluster></ui-stack></div></ui-stack></ui-disclosure>
-  ${materialView}${paletteView}
-  <div class="customizer-layout" data-customizer-overview>
-  <aside aria-label="Theme controls"><ui-stack>${choice('id="theme-start" data-preset', 'Starting point', startingPointFor(recipe), `<option value="custom" disabled>Your theme</option>${Object.entries(startingPointLabels).map(([id,label]) => `<option value="${id}">${label}</option>`).join('')}`)}
-  ${supplements.Colour}${supplements.Material}
-  <ui-disclosure summary="Type, size & motion"><ui-stack>${families}</ui-stack></ui-disclosure>
-  <ui-disclosure summary="Export & save"><ui-stack><ui-cluster><ui-button data-action="css" variant="solid">Download CSS</ui-button><ui-button data-action="recipe">Download recipe</ui-button><ui-button data-action="import">Import recipe</ui-button></ui-cluster>
+  ${materialView}${paletteView}${typographyView}${layoutView}${motionView}
+  ${refinement('themes', `<ui-stack>${choice('id="theme-start" data-preset', 'Starting point', startingPointFor(recipe), `<option value="custom" disabled>Your theme</option>${Object.entries(startingPointLabels).map(([id,label]) => `<option value="${id}">${label}</option>`).join('')}`)}<ui-text variant="caption">A starting theme coordinates color, typography, space, material, and motion. Refine any of them from the overview.</ui-text>${documentationCard('ui-cluster', '/99-theme-sampler', true)}</ui-stack>`)}
+  ${refinement('export', `<ui-stack><ui-cluster><ui-button data-action="css" variant="solid">Download CSS</ui-button><ui-button data-action="recipe">Download recipe</ui-button><ui-button data-action="import">Import recipe</ui-button></ui-cluster>
   <input type="file" accept="application/json,.json" hidden data-recipe-file>
   <ui-button data-action="save" variant="solid" hidden>Save to repository</ui-button>
   <ui-disclosure summary="Use your theme"><ui-text>Every export includes light and dark. Leave data-theme off the page to follow system preference, or set it to light or dark on the page or a section. <a href="${escape(site.base)}design-system/">Installation and mode guidance</a></ui-text></ui-disclosure>
-  <ui-disclosure summary="Theme CSS"><ui-textarea data-css readonly rows="12" aria-label="Generated theme CSS" value="${escape(themeCSS(recipe))}"></ui-textarea></ui-disclosure></ui-stack></ui-disclosure>
+  <ui-disclosure summary="Theme CSS"><ui-textarea data-css readonly rows="12" aria-label="Generated theme CSS" value="${escape(themeCSS(recipe))}"></ui-textarea></ui-disclosure></ui-stack>`)}
+  <div class="customizer-layout" data-customizer-overview>
+  <aside aria-label="Theme controls"><ui-stack gap="s"><ui-button variant="card" data-action="refine-themes"><ui-stack gap="xs"><ui-text variant="eyebrow">Starting theme</ui-text><ui-text variant="heading" data-theme-summary></ui-text></ui-stack></ui-button>
+  <ui-list>${[['palette','Palette','Colors for light & dark'],['material','Material & light','Surface character'],['typography','Typography','Fonts & readable type'],['layout','Size & spacing','Proportions & breathing room'],['motion','Motion','Pace & response']].map(([id,label,description]) => `<ui-list-item wrap>${id === 'palette' ? `<span slot="leading">${swatches()}</span>` : ''}<a href="#${id}" data-action="refine-${id}">${label}</a><span slot="description" data-summary="${id}">${description}</span><ui-icon slot="trailing" name="chevron-right"></ui-icon></ui-list-item>`).join('')}</ui-list>
+  <ui-cluster><ui-button data-action="refine-components">Browse components</ui-button><ui-button data-action="refine-export">Export & save</ui-button></ui-cluster>
   </ui-stack></aside>
   <section data-theme-sampler><ui-stack gap="xs"><ui-text variant="heading" as="h2">Theme sampler</ui-text>${documentationCard('ui-cluster', '/99-theme-sampler', true)}</ui-stack></section>
-  <section class="examples"><ui-stack><ui-form-field><label slot="label" for="example-query">Search components</label><ui-input id="example-query" type="search" data-example-query placeholder="Name, tag or purpose"></ui-input></ui-form-field><ui-text variant="caption" role="status" aria-live="polite" data-example-count></ui-text><ui-disclosure summary="Add an example"><ui-stack><ui-combobox id="example-choice" data-add-example label="Choose a component example" placeholder="Search buttons, fields, dialogs…" disclosure clearable>${options}</ui-combobox><ui-button data-action="add" disabled>Add to preview</ui-button></ui-stack></ui-disclosure>
-  <ui-grid columns="2" min="sm"><section $each="card of $previews" $key="$card.id"><looma-example-card ${cardFields.filter(name => name !== 'id').map(name => `from:${name.replace(/[A-Z]/g, letter => '-' + letter.toLowerCase())}="$card.${name}"`).join(' ')} from:identity="$card.id" loading="eager" removable></looma-example-card></section></ui-grid>
-  <ui-button data-action="more-examples">Show more components</ui-button>
   <noscript>Enable JavaScript to edit the theme. The component reference and example previews remain available.</noscript>
-  </ui-stack></section></div></ui-stack></div>
+  </div>${refinement('components', `  <section class="examples"><ui-stack><ui-form-field><label slot="label" for="example-query">Search components</label><ui-input id="example-query" type="search" data-example-query placeholder="Name, tag or purpose"></ui-input></ui-form-field><ui-text variant="caption" role="status" aria-live="polite" data-example-count></ui-text><ui-disclosure summary="Add an example"><ui-stack><ui-combobox id="example-choice" data-add-example label="Choose a component example" placeholder="Search buttons, fields, dialogs…" disclosure clearable>${options}</ui-combobox><ui-button data-action="add" disabled>Add to preview</ui-button></ui-stack></ui-disclosure>
+  <ui-grid columns="2" min="sm"><section $each="card of $previews" $key="$card.id"><looma-example-card ${cardFields.filter(name => name !== 'id').map(name => `from:${name.replace(/[A-Z]/g, letter => '-' + letter.toLowerCase())}="$card.${name}"`).join(' ')} from:identity="$card.id" loading="eager" removable></looma-example-card></section></ui-grid>
+  <ui-button data-action="more-examples">Show more components</ui-button></ui-stack></section>
+`)}</ui-stack></div>
   <style>
-    [data-customizer-overview][hidden], [data-refinement-view][hidden], [data-variation-confirm][hidden] { display: none !important; }
+    [data-customizer-overview][hidden], [data-refinement-view][hidden] { display: none !important; }
     .customizer-layout { display: grid !important; grid-template-columns: minmax(16rem, 20rem) minmax(0, 1fr); gap: var(--ui-space-6) !important; align-items: start !important; }
-    aside { grid-row: 1 / span 2; position: sticky; inset-block-start: 5rem; max-block-size: calc(100dvh - 6rem); overflow: auto; padding: max(var(--ui-space-2), calc(var(--ui-focus-width) * 2)) !important; scroll-padding: max(var(--ui-space-2), calc(var(--ui-focus-width) * 2)); }
+    aside { grid-row: 1 / span 2; position: sticky; inset-block-start: calc(var(--_editor-chrome-height, 4.25rem) + var(--ui-space-2)); max-block-size: calc(100dvh - var(--_editor-chrome-height, 4.25rem) - var(--ui-space-4)); overflow: auto; padding: max(var(--ui-space-2), calc(var(--ui-focus-width) * 2)) !important; scroll-padding: max(var(--ui-space-2), calc(var(--ui-focus-width) * 2)); }
     .examples { min-inline-size: 0; }
     .refinement-layout { display: grid !important; grid-template-columns: minmax(0, 1.2fr) minmax(16rem, 1fr); gap: var(--ui-space-6) !important; align-items: start !important; }
-    [data-refinement-view] { scroll-margin-block-start: 5rem; }
-    .palette-preview { position: sticky; inset-block-start: 5rem; max-block-size: calc(100dvh - 6rem); overflow: auto; padding: max(var(--ui-space-2), calc(var(--ui-focus-width) * 2)) !important; }
+    [data-refinement-view] { scroll-margin-block-start: calc(var(--_editor-chrome-height, 4.25rem) + var(--ui-space-2)); }
+    .palette-preview, .editor-preview { position: sticky; inset-block-start: calc(var(--_editor-chrome-height, 4.25rem) + var(--ui-space-2)); max-block-size: calc(100dvh - var(--_editor-chrome-height, 4.25rem) - var(--ui-space-4)); overflow: auto; padding: max(var(--ui-space-2), calc(var(--ui-focus-width) * 2)) !important; }
     .spacing-samples { display: flex !important; align-items: center !important; gap: 0 !important; padding-block: var(--ui-space-3) !important; }
     .spacing-samples > span { display: block !important; block-size: var(--ui-space-1); inline-size: var(--ui-space-1); border-radius: 50%; background: var(--ui-accent); }
     .spacing-samples > span:nth-child(2) { margin-inline-start: var(--ui-space-2) !important; }
@@ -111,6 +112,9 @@ export function customizerResource(site, input = defaultRecipe()) {
     .palette-canvas { background: var(--_palette-canvas, var(--ui-surface)); }
     .palette-content { background: var(--_palette-content, var(--ui-surface-raised)); }
     .palette-action { background: var(--_palette-action, var(--ui-accent)); }
-    @media (max-width: 64rem) { .customizer-layout, .refinement-layout { grid-template-columns: minmax(0, 1fr); } aside { grid-row: auto; order: 2; position: static; max-block-size: none; } .palette-preview { position: static; max-block-size: none; overflow: visible; padding: 0 !important; } [data-theme-sampler] { order: 1; } .examples { order: 3; } }
+    .motion-track { overflow: clip; display: flex; align-items: center; block-size: 5rem; padding: var(--ui-space-3); border-radius: var(--ui-radius-md); background: var(--ui-surface-muted); }
+    [data-motion-object] { display: block; inline-size: 2rem; block-size: 2rem; border-radius: var(--ui-radius-sm); background: var(--ui-accent-solid); box-shadow: var(--ui-action-shadow); }
+    @media (max-width: 64rem) { .customizer-layout, .refinement-layout { grid-template-columns: minmax(0, 1fr); } aside { grid-row: auto; order: 1; position: static; max-block-size: none; } .palette-preview, .editor-preview { position: sticky; inset-block-start: calc(var(--_editor-chrome-height, 4.25rem) + var(--ui-space-2)); z-index: 1; background: var(--ui-surface); max-block-size: none; overflow: visible; padding: 0 !important; } [data-theme-sampler] { order: 2; } .examples { order: 3; } }
+    @media (max-width: 64rem) { .palette-preview[data-page-flow], .editor-preview[data-page-flow] { position: static; } }
   </style></template>`;
 }

package/docs/customizer.js

@@ -1,7 +1,7 @@
 import { googleFontStack, systemFont, loadGoogleFonts } from './fonts.mjs';
 import { documentationTheme, themeEvent } from './theme-session.mjs';
 import { componentRegistry } from '@nextwebwg/html-next/runtime';
-import { startingPoints, startingPointFor, themeCSS, validateRecipe, themeFields, themePalettes, materialPresets, applyRefinement, refinementState, deriveTheme, nearbyVariation } from './theme.mjs';
+import { startingPoints, startingPointFor, startingPointLabels, themeCSS, validateRecipe, themeFields, themePalettes, materialPresets, applyRefinement, refinementState, deriveTheme } from './theme.mjs';
 
 import { valueEditor, editorValue, convertValueUnit } from './value-editors.mjs';
 
@@ -13,6 +13,7 @@ export function connect(host) {
   const message = root.querySelector('[data-message]');
   const file = root.querySelector('[data-recipe-file]');
   const theme = documentationTheme(view);
+  const motionPreference = view.matchMedia('(prefers-reduced-motion: reduce)');
   let saved = validateRecipe(JSON.parse(root.dataset.recipe));
   let recipe = theme?.recipe ?? structuredClone(saved);
   let revision = root.dataset.revision;
@@ -24,8 +25,8 @@ export function connect(host) {
   const catalogExamples = [...root.querySelectorAll('[data-add-example] option[data-example]')].map(option => JSON.parse(option.dataset.example));
   const removedExamples = new Set();
   let previewQuery = '', previewLimit = 9;
-  let refinementTrigger;
-  let previewFrame = 0, pending = false, candidate, gestureStart;
+  let refinementTrigger, overviewScroll = 0, motionAnimation, motionSignature;
+  let previewFrame = 0, pending = false, gestureStart;
   const abort = new AbortController();
   const say = (text, error = false) => { message.textContent = text; message.setAttribute('role', error ? 'alert' : 'status'); };
   const sayApplied = text => say(theme?.storageAvailable ? text : 'Theme applies to this page. Browser storage is unavailable; download CSS or a recipe to keep it.');
@@ -63,7 +64,38 @@ export function connect(host) {
       }
     }
   };
+  const header = document.querySelector('[data-component~="markupress-header"]');
+  const previews = [...root.querySelectorAll('[data-editor-preview], .palette-preview')];
+  const updatePreviewLayout = () => {
+    const chrome = header?.getBoundingClientRect().height ?? 0;
+    root.style.setProperty('--_editor-chrome-height', `${chrome}px`);
+    for (const preview of previews) preview.toggleAttribute('data-page-flow', preview.offsetHeight > (view.innerHeight - chrome) / 2);
+  };
+  const replayMotion = () => {
+    const element = root.querySelector('[data-motion-object]');
+    const duration = parseFloat(convertValueUnit(recipe.values['response-time'], 'ms', unitContext()));
+    motionAnimation?.cancel();
+    const available = Math.max(0, element.parentElement.clientWidth - element.offsetWidth - 2 * parseFloat(view.getComputedStyle(element.parentElement).paddingInlineStart));
+    const start = available * .3, end = available * .7;
+    element.style.transform = `translateX(${start}px)`;
+    if (motionPreference.matches) return;
+    motionAnimation = element.animate([{ transform: `translateX(${start}px)` }, { transform: `translateX(${end}px)` }], { duration: Math.max(0, duration) * 3, easing: recipe.values['response-curve'], iterations: 2, direction: 'alternate', fill: 'none' });
+  };
   const paint = () => {
+    const values = recipe.values;
+    root.querySelector('[data-theme-summary]').textContent = startingPointLabels[recipe.origin ?? startingPointFor(recipe)] ?? 'Your theme';
+    const summaries = {
+      palette: `${themePalettes[refinementState(recipe, 'palette').id]?.label ?? 'Custom colors'} · Light & dark`,
+      material: `${materialPresets[refinementState(recipe, 'material').id]?.label ?? 'Custom material'}`,
+      typography: `${recipe.fonts?.['body-font'] ?? values['body-font'].split(',')[0]} · ${values['text-size']}`,
+      layout: `${Number(values.rhythm) * Number(values.spacing) < .95 ? 'Compact' : Number(values.rhythm) * Number(values.spacing) > 1.2 ? 'Relaxed' : 'Comfortable'} · ${parseFloat(values['corner-roundness']) === 0 ? 'Square' : 'Rounded'} corners`,
+      motion: `${values['response-time']} · ${values['response-curve'].startsWith('cubic-bezier') ? 'Custom curve' : values['response-curve']}`,
+    };
+    for (const [family, text] of Object.entries(summaries)) root.querySelector(`[data-summary="${family}"]`).textContent = text;
+    root.querySelector('[data-motion-readout]').textContent = `${values['response-time']} feedback · ${parseFloat(convertValueUnit(values['response-time'], 'ms', unitContext())) * 3}ms travel`;
+    componentRegistry.update(root.querySelector('[data-action="replay-motion"]'), { disabled: motionPreference.matches });
+    root.querySelector('[data-motion-preference]').textContent = motionPreference.matches ? 'Reduced motion is on. The study stays still.' : 'Travel is three times the feedback duration, like a larger surface transition.';
+
     const css = theme?.css || themeCSS(recipe);
     if (boundsBase !== recipe.values['text-size']) {
       boundsBase = recipe.values['text-size'];
@@ -86,13 +118,16 @@ export function connect(host) {
       }
       componentRegistry.update(root.querySelector(`[data-action="restore-${family}"]`), { disabled: state.id === 'custom' || !state.customized });
     }
-    for (const control of root.querySelectorAll('[data-font-picker]')) componentRegistry.update(control, { value: control.dataset.fontPicker === 'display-font' && recipe.values['display-font'] === recipe.values['body-font'] ? 'inherit' : recipe.fonts?.[control.dataset.fontPicker] ?? (recipe.values[control.dataset.fontPicker] === systemFont ? 'system' : 'custom') });
+    for (const control of root.querySelectorAll('[data-font-picker]')) {
+      control.querySelector('option[value=custom]').textContent = recipe.values[control.dataset.fontPicker].split(',')[0].replaceAll('"', '').trim();
+      componentRegistry.update(control, { value: control.dataset.fontPicker === 'display-font' && recipe.values['display-font'] === recipe.values['body-font'] ? 'inherit' : recipe.fonts?.[control.dataset.fontPicker] ?? (recipe.values[control.dataset.fontPicker] === systemFont ? 'system' : 'custom') });
+    }
     componentRegistry.update(root.querySelector('[data-light-editor]'), { x: Number(recipe.values['light-x']), y: Number(recipe.values['light-y']) });
     const adjustments = ['light', 'dark'].flatMap(mode => deriveTheme(recipe, { mode }).adjustments.map(item => ({ ...item, mode })));
     const report = root.querySelector('[data-palette-adjustments]');
     report.textContent = adjustments.length ? 'Paired ranges are derived for readability. Your base colors stay editable; resolved values are shown below.' : 'Both ranges preserve your base colors with readable text and essential outlines.';
     root.querySelector('[data-palette-adjustment-details]').textContent = adjustments.length ? adjustments.map(item => `${item.mode} ${fields.get(item.id).label.toLowerCase()} ${item.requested} → ${item.resolved}`).join('; ') + '. Base colors remain editable.' : 'Both ranges preserve your base colors with readable text and essential outlines.';
-    for (const card of root.querySelectorAll('[data-example-card]')) if (card.getClientRects().length) card.dispatchEvent(new CustomEvent('looma-theme-preview', { detail: { css } }));
+    for (const card of root.querySelectorAll('[data-example-card]')) card.dispatchEvent(new CustomEvent('looma-theme-preview', { detail: { css } }));
     const cssControl = root.querySelector('[data-css]');
     if (cssControl.getClientRects().length) updateControl(cssControl, css);
     for (const action of ['undo','redo']) componentRegistry.update(root.querySelector(`[data-action="${action}"]`), { disabled: !theme?.[action === 'undo' ? 'canUndo' : 'canRedo'] });
@@ -110,6 +145,11 @@ export function connect(host) {
     const gaps = root.querySelector('[data-spacing-samples]');
     gaps.setAttribute('aria-label', `Spacing progression with curve ${recipe.values['space-curve']}`);
     updateSizes();
+    updatePreviewLayout();
+    const nextMotion = `${values['response-time']}/${values['response-curve']}`;
+    if (!root.querySelector('[data-refinement-view="motion"]').hidden && motionSignature !== nextMotion) {
+      motionSignature = nextMotion; replayMotion();
+    }
   };
   const show = (next, persist = true) => {
     recipe = validateRecipe(next);
@@ -120,15 +160,9 @@ export function connect(host) {
     changed = JSON.stringify(recipe) !== JSON.stringify(saved);
     paint();
   };
-  const clearPreview = () => {
-    if (!candidate) return;
-    candidate = undefined; theme?.compare();
-    root.querySelector('[data-variation-confirm]').hidden = true;
-  };
   const preview = next => {
     const validated = validateRecipe(next);
     if (JSON.stringify(validated.values) === JSON.stringify(recipe.values)) return;
-    clearPreview();
     if (!pending) gestureStart = structuredClone(recipe);
     recipe = validated; pending = true;
     if (!previewFrame) previewFrame = view.requestAnimationFrame(() => {
@@ -205,49 +239,42 @@ export function connect(host) {
     const link = document.createElement('a'); link.href = url; link.download = name; link.click();
     setTimeout(() => URL.revokeObjectURL(url), 0);
   };
+  const renderView = () => {
+    const family = view.location.hash.slice(1);
+    const section = [...root.querySelectorAll('[data-refinement-view]')].find(element => element.dataset.refinementView === family);
+    const overview = root.querySelector('[data-customizer-overview]');
+    if (section) refinementTrigger = root.querySelector(`[data-action="refine-${family}"]`);
+    for (const element of root.querySelectorAll('[data-refinement-view]')) element.hidden = element !== section;
+    overview.hidden = Boolean(section);
+    motionAnimation?.cancel();
+    if (family === 'motion') motionSignature = undefined;
+    paint();
+    if (section) { section.focus(); section.scrollIntoView({ block: 'start' }); }
+    else { refinementTrigger?.focus({ preventScroll: true }); view.scrollTo({ top: overviewScroll, behavior: 'instant' }); }
+  };
+  const navigate = family => {
+    flush();
+    view.history.pushState(null, '', view.location.pathname + view.location.search + (family ? '#' + family : ''));
+    renderView();
+  };
   const click = async event => {
     const button = event.target.closest?.('[data-action]');
     if (!button) { view.requestAnimationFrame(paint); return; }
     if (button.dataset.action === 'save' && saving) return;
+    if (button.matches('a')) event.preventDefault();
     flush();
-    if (!['preview-variation', 'apply-variation', 'cancel-variation'].includes(button.dataset.action)) clearPreview();
     try {
       switch (button.dataset.action) {
+        case 'replay-motion': replayMotion(); break;
         case 'undo': case 'redo':
           theme?.[button.dataset.action](); show(theme?.recipe ?? recipe, false); sayApplied('Previous theme decision restored.'); break;
-        case 'preview-variation': {
-          clearPreview();
-          const locks = [...root.querySelectorAll('[data-family-lock]')].filter(control => control.querySelector('input')?.checked).map(control => control.dataset.familyLock);
-          candidate = nearbyVariation(recipe, root.querySelector('[data-variation-choice]').dataset.selectedValue, locks);
-          theme?.compare(candidate); root.querySelector('[data-variation-confirm]').hidden = false;
-          const differences = themeFields.filter(field => recipe.values[field.id] !== candidate.values[field.id]);
-          root.querySelector('[data-variation-description]').textContent = differences.length ? differences.map(field => `${field.label}: ${recipe.values[field.id]} → ${candidate.values[field.id]}`).join('; ') : 'No changes: the relevant families are locked or already at their bounds.';
-          break;
-        }
-        case 'apply-variation': {
-          const selected = candidate; clearPreview();
-          if (selected) show(selected); sayApplied('Variation applied. Undo returns to your previous theme.'); break;
-        }
-        case 'cancel-variation': clearPreview(); paint(); say('Variation cancelled; your theme is unchanged.'); break;
-        case 'light-top': case 'light-left': case 'light-center': {
-          const positions = { 'light-top': [.5, 0], 'light-left': [.15, .15], 'light-center': [.5, .5] };
-          const [x, y] = positions[button.dataset.action];
-          show(refinedRecipe({ ...recipe.values, 'light-x': String(x), 'light-y': String(y) }));
-          sayApplied('Light direction applied throughout your theme.'); break;
-        }
-        case 'refine-material': case 'refine-palette': {
+        case 'refine-material': case 'refine-palette': case 'refine-typography': case 'refine-layout': case 'refine-motion': case 'refine-themes': case 'refine-export': case 'refine-components': {
           const family = button.dataset.action.slice(7);
-          refinementTrigger = button;
-          root.querySelector('[data-customizer-overview]').hidden = true;
-          for (const section of root.querySelectorAll('[data-refinement-view]')) section.hidden = section.dataset.refinementView !== family;
-          const section = root.querySelector(`[data-refinement-view="${family}"]`);
-          paint(); section.focus(); section.scrollIntoView({ block: 'start' });
+          refinementTrigger = button; overviewScroll = view.scrollY;
+          navigate(family);
           break;
         }
-        case 'back':
-          for (const section of root.querySelectorAll('[data-refinement-view]')) section.hidden = true;
-          root.querySelector('[data-customizer-overview]').hidden = false;
-          paint(); refinementTrigger?.focus(); break;
+        case 'back': navigate(''); break;
         case 'restore-material': case 'restore-palette': {
           const family = button.dataset.action.slice(8), state = refinementState(recipe, family);
           if (state.id !== 'custom') { show(applyRefinement(recipe, family, state.id)); sayApplied(`${family === 'material' ? 'Material' : 'Palette'} preset restored; other theme decisions are unchanged.`); }
@@ -302,7 +329,7 @@ export function connect(host) {
     if (event.target.matches('[data-light-editor]') || event.target.closest?.('[data-token]')) {
       input(event); flush(); sayApplied('Theme remembered in this browser. Undo restores the previous decision.'); return;
     }
-    flush(); clearPreview();
+    flush();
     if (event.target.matches('[data-unit-for]')) {
       const field = fields.get(event.target.dataset.unitFor);
       try {
@@ -328,14 +355,14 @@ export function connect(host) {
   const choose = event => {
     if (!event.target.matches('[data-choice]') || event.detail.kind !== 'selection') return;
     event.target.dataset.selectedValue = event.detail.value;
-    if (!event.target.matches('[data-variation-choice]')) change(event);
+    change(event);
   };
   const blur = event => { const control = event.target; if (control.closest?.('[data-token]')) queueMicrotask(() => { if (alive && control.validity?.customError) say(control.validationMessage, true); }); };
   const synchronize = () => { if (!pending && theme && JSON.stringify(recipe) !== JSON.stringify(theme.recipe)) show(theme.recipe, false); };
   const cancel = event => { if (event.target.matches('[data-light-editor], [data-editor-kind="curve"]')) { flush(false); say('Drag cancelled; the previous value is restored.'); } };
   const keyboard = event => {
     if (!(event.ctrlKey || event.metaKey) || event.key.toLowerCase() !== 'z' || event.target.closest?.('input,textarea,select,[contenteditable="true"]')) return;
-    event.preventDefault(); flush(); clearPreview(); theme?.[event.shiftKey ? 'redo' : 'undo'](); show(theme?.recipe ?? recipe, false);
+    event.preventDefault(); flush(); theme?.[event.shiftKey ? 'redo' : 'undo'](); show(theme?.recipe ?? recipe, false);
   };
   const ready = event => {
     if (event.data?.type === 'looma-preview-ready' && [...root.querySelectorAll('iframe')].some(frame => frame.contentWindow === event.source)) paint();
@@ -352,7 +379,7 @@ export function connect(host) {
   let fontRequest = 0;
   const selectFont = async event => {
     const control = event.target.closest?.('[data-font-picker]'); if (!control) return;
-    flush(); clearPreview();
+    flush();
     const id = control.dataset.fontPicker, family = event.detail.value;
     const fonts = { ...recipe.fonts };
     if (family === 'system' || family === 'inherit') delete fonts[id]; else fonts[id] = family;
@@ -377,6 +404,11 @@ export function connect(host) {
     selectedExample = event.detail.value ?? '';
     filterExamples();
   };
+  const motionPreferenceChanged = () => { motionAnimation?.cancel(); paint(); };
+  const previewObserver = new view.ResizeObserver(updatePreviewLayout);
+  for (const element of [...previews, ...(header ? [header] : [])]) previewObserver.observe(element);
+  view.addEventListener('resize', updatePreviewLayout);
+  motionPreference.addEventListener('change', motionPreferenceChanged);
   root.addEventListener('toggle', updateSizes, true);
   root.addEventListener('looma-example-remove', remove);
   root.addEventListener('input', input);
@@ -389,9 +421,12 @@ export function connect(host) {
   root.addEventListener('change', change);
   root.addEventListener('click', click);
   view.addEventListener('message', ready);
+  view.addEventListener('popstate', renderView);
+  view.addEventListener('hashchange', renderView);
   view.addEventListener('beforeunload', flush);
   view.addEventListener(themeEvent, synchronize);
   show(recipe, false); filterExamples();
+  if (view.location.hash) renderView();
   if (theme?.storageAvailable === false) sayApplied('');
   if (root.dataset.mode === 'local') {
     fetch(root.dataset.base + '_looma/session', { signal: abort.signal }).then(async response => {
@@ -403,5 +438,5 @@ export function connect(host) {
       root.querySelector('[data-action="save"]').hidden = false;
     }).catch(error => { if (alive && error.name !== 'AbortError') say(error.message, true); });
   }
-  return () => { root.removeEventListener('toggle', updateSizes, true); flush(); clearPreview(); root.removeEventListener('cancel', cancel); root.removeEventListener('keydown', keyboard); alive = false; abort.abort(); root.removeEventListener('looma-example-remove', remove); root.removeEventListener('input', input); root.removeEventListener('value-change', choose); root.removeEventListener('value-change', selectExample); root.removeEventListener('value-change', selectFont); root.removeEventListener('blur', blur, true); root.removeEventListener('change', change); root.removeEventListener('click', click); view.removeEventListener('beforeunload', flush); view.removeEventListener('message', ready); view.removeEventListener(themeEvent, synchronize); };
+  return () => { previewObserver.disconnect(); view.removeEventListener('resize', updatePreviewLayout); motionPreference.removeEventListener('change', motionPreferenceChanged); root.removeEventListener('toggle', updateSizes, true); motionAnimation?.cancel(); flush(); root.removeEventListener('cancel', cancel); root.removeEventListener('keydown', keyboard); alive = false; abort.abort(); root.removeEventListener('looma-example-remove', remove); root.removeEventListener('input', input); root.removeEventListener('value-change', choose); root.removeEventListener('value-change', selectExample); root.removeEventListener('value-change', selectFont); root.removeEventListener('blur', blur, true); root.removeEventListener('change', change); root.removeEventListener('click', click); view.removeEventListener('beforeunload', flush); view.removeEventListener('message', ready); view.removeEventListener('popstate', renderView); view.removeEventListener('hashchange', renderView); view.removeEventListener(themeEvent, synchronize); };
 }

package/docs/site.mjs

@@ -144,7 +144,7 @@ export async function prepareDocumentation({ root, config = {}, catalog }) {
   const customizer = path.join(generated, 'customizer.html');
   await write(customizer, customizerResource({ catalog: combined, config, base }, config.recipe));
   const customizerPage = path.join(content, 'customize.md');
-  await write(customizerPage, `---\ntitle: Customize\nsidebar: false\noutline: false\nprevious: false\nnext: false\n---\n\n# Weave your design system\n\n<link rel="component" href="${relativeHref(customizerPage, customizer)}">\n<looma-customizer></looma-customizer>\n`);
+  await write(customizerPage, `---\ntitle: Customize\nsidebar: false\noutline: false\nprevious: false\nnext: false\n---\n\n# Customize your theme\n\n<link rel="component" href="${relativeHref(customizerPage, customizer)}">\n<looma-customizer></looma-customizer>\n`);
   await write(path.join(generated, 'catalog.json'), JSON.stringify(combined));
   const redirects = {};
   for (const component of combined.components) {

package/docs/theme-session.mjs

@@ -7,7 +7,7 @@ export const themeEvent = 'looma-documentation-theme';
 export function createThemeSession(view, { base, baseline, systemCSS, historyLimit = 100 }) {
   const key = `looma:documentation-theme:v1:${base}`;
   let original = validateRecipe(baseline);
-  let selected, draft, comparison;
+  let selected, draft;
   const past = [], future = [];
   let portableCSS = '';
   let storageAvailable = true;
@@ -17,7 +17,7 @@ export function createThemeSession(view, { base, baseline, systemCSS, historyLim
   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 = () => {
-    const displayed = comparison ?? draft ?? selected;
+    const displayed = 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' }) : '';
@@ -42,22 +42,21 @@ export function createThemeSession(view, { base, baseline, systemCSS, historyLim
     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(); },
+    undo() { if (!past.length) return; future.push(structuredClone(selected)); selected = past.pop(); draft = undefined; persist(); },
+    redo() { if (!future.length) return; past.push(structuredClone(selected)); selected = future.pop(); draft = undefined; persist(); },
     apply(recipe) {
       const next = validateRecipe(recipe);
       if (JSON.stringify(next) !== JSON.stringify(selected)) remember();
-      selected = next; draft = comparison = undefined; persist();
+      selected = next; draft = undefined; persist();
     },
-    reset() { if (selected !== undefined) remember(); selected = draft = comparison = undefined; persist(); return structuredClone(original); },
+    reset() { if (selected !== undefined) remember(); selected = draft = 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; draft = comparison = undefined; past.length = future.length = 0; paint();
+    selected = next; draft = undefined; past.length = future.length = 0; paint();
   });
   view.addEventListener('markupress-header-notice-dismiss', () => session.reset());
   paint();