@scattered-light/loomiere 0.0.0-stage → 0.1.0

package/tools/brand-builder/builder.js

@@ -0,0 +1,1119 @@
+/*
+ * Brand builder. Edits a brand file and previews what the generator makes from it.
+ *
+ * Served by `loomiere studio`, which supplies GET/POST
+ * /api/brand. `loomiere studio --export` bundles this file into one page with the brand
+ * inlined as window.BRAND_DATA; that copy can't save, only copy the JSON.
+ */
+import { formatHex, oklch, wcagContrast } from 'culori';
+
+import { buildPrimitives } from '../../generator/brand.mjs';
+import { checkDataColors, DATA_CONTRAST, nudgeDataColor, VISIONS } from '../../generator/data-colors.mjs';
+import { VISION_THEMES, visionColors } from '../../generator/vision.mjs';
+import { formatBrand } from '../../generator/format-brand.mjs';
+import { CONCEPTS, conceptModes, defaultPick, LEVELS, pickRef, SLOTS, stepRef, STYLES, withDefaults } from '../../generator/roles.mjs';
+
+const BRAND_ROLES = ['neutral', 'primary', 'secondary', 'tertiary', 'quaternary'];
+const ALERT_ROLES = ['success', 'warning', 'error', 'info'];
+const RATIOS = [
+  ['Minor second', 1.067], ['Major second', 1.125], ['Minor third', 1.2], ['Major third', 1.25],
+  ['Perfect fourth', 1.333], ['Augmented fourth', 1.414], ['Perfect fifth', 1.5], ['Golden', 1.618],
+];
+const SAMPLE = 'Dusk over the dunes';
+/**
+ * The builder follows the order a brand gets made in: set the brand, then find the pairs it
+ * allows, then decide which colors play which part in the UI. Each step only consumes the ones
+ * before it, so going back to adjust a brand color and returning never loses anything.
+ */
+const STEPS = [
+  { id: 'brand', label: 'Brand', intro: 'Colors, type, space and shape: the raw material everything else uses.',
+    groups: [['Brand', [['identity', 'Name']]],
+      ['Color', [['ends', 'Paper & ink'], ['tables', 'Contrast steps'], ['palettes', 'Brand colors'], ['alerts', 'Alerts'], ['data', 'Data colors'], ['vision', 'Color vision']]],
+      ['Shape', [['type', 'Type'], ['space', 'Space'], ['shape', 'Radius & lines'], ['elevation', 'Shadows'], ['motion', 'Motion']]]] },
+  { id: 'pairs', label: 'Pairs', intro: 'Background and text combinations the brand colors allow.', groups: [['Pairs', [['pairs', 'Pairs']]]] },
+  { id: 'roles', label: 'Roles & themes', intro: 'Which colors play which part, and what the light and dark themes look like.', groups: [['Roles', [['roles', 'Roles & themes'], ['concepts', 'Concepts']]]] },
+];
+const stepOf = (section) => STEPS.find((st) => st.groups.some(([, items]) => items.some(([id]) => id === section)))?.id;
+const ROOT_PX = 16;
+
+const $ = (id) => document.getElementById(id);
+const esc = (s) => String(s ?? '').replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
+const clone = (v) => JSON.parse(JSON.stringify(v));
+const round = (n, p = 2) => Number(Number(n).toFixed(p));
+const ratio = (a, b) => wcagContrast(a, b);
+const textOn = (hex) => (ratio(hex, '#ffffff') >= ratio(hex, '#000000') ? '#ffffff' : '#000000');
+
+const state = {
+  static: Boolean(window.BRAND_DATA),
+  name: '',
+  brand: null,
+  overrides: {},
+  savedText: '',
+  brands: [],
+  built: false,
+  usePins: true,
+  dataGoal: DATA_CONTRAST,
+  // Color vision: which theme's colors are open for tuning, and whether cards show colors
+  // as designed or as seen with each vision.
+  visionOpen: null,
+  step: (() => { try { return localStorage.getItem('brand-builder-step') || 'brand'; } catch { return 'brand'; } })(),
+  visionSeen: false,
+  // Suggested data color fixes, kept until the data or the goal changes.
+  dataFixes: null,
+  width: 1280,
+  result: null,
+  error: null,
+  pinError: null,
+  // Semantic tokens that read each role concept, from the server ("chrome.fg" → ["text.primary", …]).
+  uses: {},
+};
+
+/* ---------- paths ---------- */
+
+const pathOf = (p) => (Array.isArray(p) ? p : p.split('.'));
+function get(p, obj = state.brand) {
+  return pathOf(p).reduce((o, k) => o?.[k], obj);
+}
+function set(p, value, obj = state.brand) {
+  const keys = pathOf(p);
+  let o = obj;
+  for (const k of keys.slice(0, -1)) o = o[k] ??= {};
+  if (value === undefined) delete o[keys.at(-1)];
+  else o[keys.at(-1)] = value;
+}
+
+/* ---------- compute ---------- */
+
+function compute() {
+  state.pinError = null;
+  try {
+    try {
+      state.result = buildPrimitives(state.brand, state.usePins ? state.overrides : {});
+    } catch (err) {
+      // A pin that no longer matches (a step was renamed or removed) shouldn't block the preview.
+      if (!state.usePins || !/Override/.test(err.message)) throw err;
+      state.pinError = err.message;
+      state.result = buildPrimitives(state.brand, {});
+    }
+    state.error = null;
+  } catch (err) {
+    state.error = err.message;
+  }
+}
+
+const colors = () => state.result.files.color.color;
+/** A color token's hex, following one level of {color.x.y} reference. */
+function hexAt(tokenPath) {
+  const t = tokenPath.split('.').slice(1).reduce((o, k) => o?.[k], colors());
+  const v = t?.$value;
+  if (typeof v !== 'string') return null;
+  const ref = v.match(/^\{(.+)\}$/);
+  return ref ? hexAt(ref[1]) : v;
+}
+const pairRef = (r) => `color.${{ paper: 'white', ink: 'black' }[r] ?? r}`;
+
+/** px for a CSS length at a viewport width: "1rem", "12px", or clamp(min, a + b, max). */
+function pxAt(value, width) {
+  const term = (t) => {
+    const m = t.trim().match(/^(-?[\d.]+)(rem|px|vw)?$/);
+    if (!m) return 0;
+    const n = Number(m[1]);
+    return m[2] === 'rem' ? n * ROOT_PX : m[2] === 'vw' ? (n * width) / 100 : n;
+  };
+  const sum = (expr) => expr.split('+').reduce((a, t) => a + term(t), 0);
+  const c = String(value).match(/^clamp\((.+),(.+),(.+)\)$/);
+  if (!c) return sum(String(value));
+  return Math.min(sum(c[3]), Math.max(sum(c[1]), sum(c[2])));
+}
+
+/* ---------- small builders ---------- */
+
+const colorIn = (bind, value, label) => `<span class="color-in">
+  <input type="color" data-bind="${bind}" data-kind="color" value="${esc(toHex6(value))}" aria-label="${esc(label)}">
+  <input type="text" class="hex" data-bind="${bind}" data-kind="hex" value="${esc(value)}" aria-label="${esc(label)} hex" spellcheck="false">
+</span>`;
+function toHex6(v) {
+  try { return formatHex(v) ?? '#000000'; } catch { return '#000000'; }
+}
+const numIn = (bind, value, label, attrs = '') => `<label class="field"><span>${label}</span><input type="number" data-bind="${bind}" data-kind="number" value="${esc(value)}" ${attrs}></label>`;
+const textIn = (bind, value, label, attrs = '') => `<label class="field"><span>${label}</span><input type="text" data-bind="${bind}" data-kind="text" value="${esc(value)}" ${attrs}></label>`;
+const listIn = (bind, value, label, kind, hint) => `<label class="field"><span>${label}</span><input type="text" data-bind="${bind}" data-kind="${kind}" value="${esc(value.join(', '))}" spellcheck="false">${hint ? `<small>${hint}</small>` : ''}</label>`;
+const check = (bind, value, label) => `<label class="toggle"><input type="checkbox" data-bind="${bind}" data-kind="bool"${value ? ' checked' : ''}> ${label}</label>`;
+const selectIn = (bind, value, options, label) => `<label class="field"><span>${label}</span><select data-bind="${bind}" data-kind="select">${options.map(([v, l]) => `<option value="${esc(v)}"${String(v) === String(value) ? ' selected' : ''}>${esc(l)}</option>`).join('')}</select></label>`;
+
+/** Rows of name → number for an object like radius.steps; names can be renamed. */
+function mapEditor(bind, obj, { valueLabel = 'Value', step = 'any', locks } = {}) {
+  const rows = Object.entries(obj).map(([k, v]) => `<div class="map-row${locks ? ' locks' : ''}">
+      <input type="text" data-rename="${bind}" data-key="${esc(k)}" value="${esc(k)}" aria-label="Name" spellcheck="false">
+      <input type="number" data-bind="${bind}.${k}" data-kind="number" value="${esc(v)}" step="${step}" aria-label="${esc(k)} ${valueLabel}">
+      ${locks ? `<label class="toggle" title="Locked steps keep their target even when a brand color lands near them"><input type="checkbox" data-lock="${locks}" data-key="${esc(k)}"${get(locks)?.includes(Number(k)) ? ' checked' : ''}> lock</label>` : ''}
+      <button class="icon-btn" type="button" data-act="map-remove" data-bind="${bind}" data-key="${esc(k)}" aria-label="Remove ${esc(k)}">×</button>
+    </div>`);
+  return `<div class="list">${rows.join('')}<div><button class="btn small" type="button" data-act="map-add" data-bind="${bind}">Add</button></div></div>`;
+}
+
+const band = (id, title, intro, edit, preview) => `<section class="band" id="${id}">
+  <div class="band-head"><h2>${title}</h2>${intro ? `<p class="muted">${intro}</p>` : ''}</div>
+  ${edit === null ? preview : `<div class="band-body"><div class="edit">${edit}</div><div class="preview" id="pv-${id}">${preview}</div></div>`}
+</section>`;
+
+/* ---------- sections: editors ---------- */
+
+function paletteEditor(role) {
+  const p = get(['color', 'palettes', role]);
+  const keys = p.keys ?? [];
+  const tables = Object.keys(state.brand.color.contrast);
+  return `<div class="panel">
+    <div class="pal-head"><h3>${esc(p.label ?? role)}</h3>${p.label && p.label !== role ? `<span class="role">${role}</span>` : ''}</div>
+    <div class="row">
+      ${ALERT_ROLES.includes(role) ? '' : textIn(`color.palettes.${role}.label`, p.label ?? '', 'Label', 'spellcheck="false"')}
+      ${selectIn(`color.palettes.${role}.contrast`, p.contrast ?? 'spot', tables.map((t) => [t, t]), 'Contrast steps')}
+    </div>
+    <div class="field"><span>Keys</span>
+      <div class="list">${keys.map((k, i) => `<div class="row">${colorIn(`color.palettes.${role}.keys.${i}`, k, `${role} key ${i + 1}`)}
+        <button class="icon-btn" type="button" data-act="key-remove" data-role="${role}" data-i="${i}" aria-label="Remove key ${i + 1}">×</button></div>`).join('')}
+        <div><button class="btn small" type="button" data-act="key-add" data-role="${role}">Add key</button></div>
+      </div>
+      <small>The ramp bends through every key. Order doesn't matter.</small>
+    </div>
+    <details class="more"${p.exact || p.darkest || p.tone ? ' open' : ''}><summary>More options</summary><div class="edit">
+    ${check(`color.palettes.${role}.exact`, p.exact, 'Keys land exactly on their nearest step')}
+    <div class="row">
+      ${check(`color.palettes.${role}.darkest@toggle`, p.darkest !== undefined, 'Ends at its own darkest color')}
+      ${p.darkest !== undefined ? colorIn(`color.palettes.${role}.darkest`, p.darkest, `${role} darkest`) : ''}
+    </div>
+    ${p.tone ? `<div class="field"><span>Tone</span>
+        <div class="row">${colorIn(`color.palettes.${role}.tone.color`, p.tone.color, `${role} tone`)}
+          <button class="btn small" type="button" data-act="tone-remove" data-role="${role}">Remove tone</button></div>
+        ${rangeIn(`color.palettes.${role}.tone.intensity.0`, toneAt(p, 0), 'Tone in the lights')}
+        ${rangeIn(`color.palettes.${role}.tone.intensity.1`, toneAt(p, 1), 'Tone in the darks')}
+        <small>A tone tints the ramp like a transparent color over gray, easing from the lights to the darks.</small>
+      </div>` : `<div><button class="btn small" type="button" data-act="tone-add" data-role="${role}">Add a tone</button></div>`}
+    </div></details>
+  </div>`;
+}
+const toneAt = (p, i) => (Array.isArray(p.tone.intensity) ? p.tone.intensity[i] : p.tone.intensity);
+const rangeIn = (bind, value, label) => `<label class="field"><span>${label} · <output data-out="${bind}">${Math.round(value * 100)}%</output></span>
+  <input type="range" min="0" max="1" step="0.01" data-bind="${bind}" data-kind="number" value="${esc(value)}"></label>`;
+
+function editorsHtml() {
+  const b = state.brand;
+  const c = b.color;
+  const out = [];
+
+  out.push(band('identity', 'Name', 'What the brand is called and a line about it. The name becomes the file name.',
+    `${textIn('name', state.name, 'File name', 'data-special="name" spellcheck="false"')}
+     <label class="field"><span>Description</span><textarea rows="2" data-bind="description" data-kind="text">${esc(b.description ?? '')}</textarea></label>`,
+    `<div class="panel"><p class="muted">Every other value on this page lives in <code>${esc(state.dir)}/${esc(state.name)}.json</code>. The generator turns it into the primitive tokens; semantic and component tokens point at those, so they follow.</p></div>`));
+
+  out.push(band('ends', 'Paper and ink', 'The lightest and darkest colors in the system. Every step is measured against paper, and every ramp runs from paper to ink.',
+    `<div class="row"><label class="field"><span>Paper</span>${colorIn('color.paper', c.paper, 'Paper')}</label>
+       <label class="field"><span>Ink</span>${colorIn('color.ink', c.ink, 'Ink')}</label></div>`,
+    ''));
+
+  out.push(band('tables', 'Contrast steps', 'Each step sits where its contrast against paper hits a target. Palettes on the same table match step for step, so 500 means AA everywhere.',
+    Object.entries(c.contrast).map(([name, t]) => `<details class="panel"><summary><h3>${esc(name)}</h3><span class="muted">${Object.keys(t.targets).length} steps · edit</span></summary>
+      ${mapEditor(`color.contrast.${name}.targets`, t.targets, { valueLabel: 'contrast', step: '0.01', locks: `color.contrast.${name}.locked` })}</details>`).join(''),
+    ''));
+
+  out.push(`<section class="band" id="palettes"><div class="band-head"><h2>Brand colors</h2>
+    <p class="muted">Pick the brand's colors as keys. The neutral uses a tone plus exact keys, so its grays bend through your own light and dark neutrals. Text on each step is that step's on-color, and the curve under each ramp is its path: how colorful each step is, from paper on the left to ink on the right.</p></div>
+    <div class="palettes">${BRAND_ROLES.map((r) => `<div class="pal">${paletteEditor(r)}<div class="preview" id="pv-pal-${r}"></div></div>`).join('')}</div></section>`);
+
+  out.push(`<section class="band" id="alerts"><div class="band-head"><h2>Alerts</h2>
+    <p class="muted">Status colors for success, warning, error and info messages. One key each is usually enough; the contrast table does the rest.</p></div>
+    <div class="palettes">${ALERT_ROLES.map((r) => `<div class="pal">${paletteEditor(r)}<div class="preview" id="pv-pal-${r}"></div></div>`).join('')}</div>
+    <div class="preview" id="pv-alert-sample"></div></section>`);
+
+  out.push(band('data', 'Data colors', 'Categorical colors for charts, used in this order. Neighbors should be easy to tell apart.',
+    `<div class="list">${c.data.map(([name, hex], i) => `<div class="row">
+        <input type="text" data-bind="color.data.${i}.0" data-kind="text" value="${esc(name)}" aria-label="Series ${i + 1} name" style="flex:1 1 90px" spellcheck="false">
+        ${colorIn(`color.data.${i}.1`, hex, `Series ${i + 1}`)}
+        <button class="icon-btn" type="button" data-act="data-up" data-i="${i}" aria-label="Move ${esc(name)} earlier"${i === 0 ? ' disabled' : ''}>↑</button>
+        <button class="icon-btn" type="button" data-act="data-remove" data-i="${i}" aria-label="Remove ${esc(name)}">×</button></div>`).join('')}
+      <div><button class="btn small" type="button" data-act="data-add">Add a color</button></div></div>
+    <label class="field"><span>Contrast on paper</span>
+      <select id="data-goal">${[[0, 'No minimum'], [1.5, '1.5:1, faint marks show'], [3, '3:1, WCAG for graphics']].map(([v, t]) => `<option value="${v}"${v === state.dataGoal ? ' selected' : ''}>${t}</option>`).join('')}</select></label>
+    <p class="muted">Every color is also checked against its neighbor as seen with each kind of color blindness. Under 3:1 is fine when bars get an outline or a label.</p>`,
+    ''));
+
+  out.push(`<section class="band" id="vision"><div class="band-head"><h2>Color vision</h2>
+    <p class="muted">Each theme redesigns this brand's colors for one kind of color blindness, moving each color only as far as it needs to so colors that look different to most people don't blur together. Contrast steps stay the same. Open a theme to tune any color. A page turns one on with <code>data-vision="deuteranopia"</code> on its root element.</p></div>
+    <div class="row"><label class="toggle"><input type="checkbox" id="vision-seen"${state.visionSeen ? ' checked' : ''}> Show each theme as people with that vision see it</label></div>
+    <div class="preview" id="pv-vision"></div>
+    ${visionDetailHtml()}</section>`);
+
+  const r = withDefaults(b.roles);
+  const pals = Object.entries(c.palettes);
+  const chromeOpts = pals.filter(([, p]) => p.contrast === 'neutral').map(([n]) => [n, n]);
+  const accentOpts = pals.filter(([, p]) => p.contrast !== 'neutral').map(([n]) => [n, n]);
+  const colorOpts = [['accent', `accent (${r.accent})`], ['chrome', `chrome (${r.chrome})`], ...pals.map(([n]) => [n, n])];
+  const styleOpts = Object.keys(STYLES).map((v) => [v, v]);
+  out.push(band('pairs', 'Pairs', 'Named background and text combinations. Pick them in the pair lab (<code>loomiere lab</code>); here you can see whether palette changes still keep them at AA.', null,
+    '<div class="preview" id="pv-pairs"></div>'));
+
+  const t = b.type;
+  const stepOpts = t.steps.map((s) => [s, s]);
+  out.push(band('type', 'Type', 'A modular scale: each step is the one below times the ratio. The ratio can differ on small and large screens, and sizes ease between them.',
+    `<div class="panel"><h3>Families</h3>
+       ${['display', 'body', 'mono'].map((r) => listIn(`type.families.${r}`, t.families[r] ?? [], r, 'list-str')).join('')}
+       <small class="muted">Google Fonts families load automatically for the preview.</small></div>
+     <div class="panel"><h3>Scale</h3>
+       <div class="row">${numIn('type.base.min', t.base.min, 'Base, small screen (px)', 'step="0.5"')}${numIn('type.base.max', t.base.max, 'Base, large screen (px)', 'step="0.5"')}</div>
+       <div class="row">${numIn('type.ratio.min', t.ratio.min, 'Ratio, small screen', 'step="0.001"')}${numIn('type.ratio.max', t.ratio.max, 'Ratio, large screen', 'step="0.001"')}</div>
+       <div class="row">${numIn('type.viewport.min', t.viewport.min, 'Small screen (px)')}${numIn('type.viewport.max', t.viewport.max, 'Large screen (px)')}</div>
+       ${listIn('type.steps', t.steps, 'Steps, smallest first', 'list-str')}
+       <div class="row">${selectIn('type.baseStep', t.baseStep, stepOpts, 'Base step')}${numIn('type.small.floor', t.small?.floor ?? 0, 'Smallest size (px)')}</div>
+       ${check('type.small.fixed', t.small?.fixed !== false, 'Sizes below the base stay fixed')}
+       ${check('type.stepDown', Boolean(t.stepDown), 'Headings drop one step on small screens')}
+       <small class="muted">On a small screen each size above the base starts where the step below ends on a large screen, instead of shrinking by the base's ratio.</small>
+       ${selectIn('type.displayFrom', t.displayFrom ?? '', [['', 'Never'], ...stepOpts], 'Display family from')}</div>
+     <div class="panel"><h3>Line height</h3>
+       <small class="muted">Each line is the font's own height plus leading. Leading eases from text to headings, so small text gets air and big headings sit tight.</small>
+       <div class="row">${numIn('type.lineHeight.text', t.lineHeight.text, 'Text leading (em)', 'step="0.001"')}${selectIn('type.lineHeight.textStep', t.lineHeight.textStep, stepOpts, 'Up to step')}</div>
+       <div class="row">${numIn('type.lineHeight.heading', t.lineHeight.heading, 'Heading leading (em)', 'step="0.001"')}${selectIn('type.lineHeight.headingStep', t.lineHeight.headingStep, stepOpts, 'From step')}</div>
+       ${selectIn('type.lineHeight.solidFrom', t.lineHeight.solidFrom ?? '', [['', 'Never'], ...stepOpts], 'Set solid (line height 1) from')}
+       <h3>Font measurements</h3>
+       <div class="table-wrap"><table class="metrics"><thead><tr><th>Font</th><th>Own height</th><th>Cap</th><th>x</th></tr></thead><tbody>
+         ${['display', 'body', 'mono'].map((r) => {
+           const m = t.metrics?.[r];
+           return `<tr><td>${r}</td>${m ? `<td>${round(m.ascent + m.descent, 3)}</td><td>${m.capHeight ?? '–'}</td><td>${m.xHeight ?? '–'}</td>` : '<td colspan="3" class="muted">not measured (1.2 assumed)</td>'}</tr>`;
+         }).join('')}</tbody></table></div>
+       <div class="row"><button class="btn small" type="button" data-act="measure-fonts">Measure fonts</button>
+         <small class="muted">Reads ascent, descent, cap and x-height from the loaded fonts. Do it after changing a family.</small></div></div>`,
+    `<div class="panel"><label class="field"><span>Preview width · <output id="width-out">${state.width}px</output></span>
+       <input type="range" id="width" min="320" max="1600" step="10" value="${state.width}"></label></div>
+     <div class="preview" id="pv-type-out"></div>`));
+
+  out.push(band('space', 'Space', 'Every space token is the unit times a step, so the whole layout keeps one rhythm.',
+    `${numIn('space.unit', b.space.unit, 'Unit (px)', 'step="0.5" min="1"')}
+     ${listIn('space.steps', b.space.steps, 'Steps (multiples of the unit)', 'list-num')}`,
+    ''));
+
+  out.push(band('shape', 'Radius and lines', 'Corner radii and border widths, each a multiple of its base.',
+    `<div class="panel"><h3>Radius</h3>${numIn('radius.base', b.radius.base, 'Base (px)', 'step="0.5"')}${mapEditor('radius.steps', b.radius.steps, { valueLabel: '× base', step: '0.25' })}</div>
+     <div class="panel"><h3>Lines</h3>${numIn('stroke.base', b.stroke.base, 'Base (px)', 'step="0.5"')}${mapEditor('stroke.steps', b.stroke.steps, { valueLabel: '× base', step: '0.5' })}</div>`,
+    ''));
+
+  out.push(band('elevation', 'Shadows', 'The shadow shapes are fixed; the brand sets their color and how strong they are.',
+    `<label class="field"><span>Shadow color</span>${colorIn('elevation.shadowColor', b.elevation.shadowColor, 'Shadow color')}</label>
+     <label class="field"><span>Strength · <output data-out="elevation.strength">${b.elevation.strength}×</output></span>
+       <input type="range" min="0" max="3" step="0.05" data-bind="elevation.strength" data-kind="number" value="${b.elevation.strength}"></label>`,
+    ''));
+
+  out.push(band('motion', 'Motion', 'Durations for transitions. Speed scales all of them at once.',
+    `<label class="field"><span>Speed · <output data-out="motion.speed">${b.motion.speed}×</output></span>
+       <input type="range" min="0.25" max="3" step="0.05" data-bind="motion.speed" data-kind="number" value="${b.motion.speed}"></label>
+     ${mapEditor('motion.durations', b.motion.durations, { valueLabel: 'ms', step: '10' })}`,
+    ''));
+
+  out.push(band('roles', 'Roles & themes', 'Which colors play the main parts, shown on a sample screen in light and dark. Chrome is the surfaces, text and borders; the accent is links, focus and the loudest actions. The ladder sets four levels of emphasis that components share, loudest first. Any part can still be painted in another palette with <code>data-color</code>.',
+    `<div class="panel"><div class="row">${selectIn('roles.chrome', r.chrome, chromeOpts, 'Chrome')}${selectIn('roles.accent', r.accent, accentOpts, 'Accent')}</div>
+       <small class="muted">The accent doesn't have to be primary. A red brand might keep red for errors and pick a calmer accent.</small></div>
+     <div class="panel"><h3>Emphasis ladder</h3>
+       ${LEVELS.map((level) => `<div class="row"><b class="level">${level}</b>${selectIn(`roles.emphasis.${level}.style`, r.emphasis[level].style, styleOpts, 'Style')}${selectIn(`roles.emphasis.${level}.color`, r.emphasis[level].color, colorOpts, 'Color')}</div>`).join('')}
+       <small class="muted">In code: <code>&lt;Button emphasis="subtle"&gt;</code>, or <code>data-emphasis="subtle"</code> on any element. Add <code>palette="error"</code> (<code>data-color</code>) to repaint a level.</small></div>
+     <div class="panel"><h3>What uses what</h3><p class="muted">Each part of the sample screen reads one role. Change a setting and the parts that use it light up.</p>
+       <div class="palette-strip" id="pv-strip"></div>
+       <div class="row"><button class="btn small" type="button" data-act="step" data-step="brand">Adjust brand colors</button></div></div>`,
+    '<div id="pv-theme-out"></div>'));
+
+  out.push(band('concepts', 'Concepts', 'The colors the theme reuses most, each in light and dark. Every row starts on a step of the chrome or accent palette; pick another step, paper, ink, any palette or a hex to change it, and Reset to go back. Picks are saved under <code>roles.concepts</code> and keep their color when chrome or accent changes.',
+    null, '<div class="preview" id="pv-concepts"></div>'));
+
+  out.push(band('file', 'Brand file', 'What Save writes. Pins come from the overrides file and are never changed here.', null,
+    `<div class="preview" id="pv-file"></div>`));
+  return out.join('');
+}
+
+/* ---------- sections: previews ---------- */
+
+function rampHtml(role) {
+  const pal = colors()[role];
+  const p = state.brand.color.palettes[role];
+  const table = state.brand.color.contrast[p.contrast ?? 'spot'];
+  const steps = Object.keys(pal).filter((s) => s !== 'on');
+  const keys = (p.keys ?? []).map((k) => toHex6(k));
+  const paper = state.brand.color.paper;
+  const cells = steps.map((s) => {
+    const hex = pal[s].$value;
+    const on = hexAt(`color.${role}.on.${s}`) ?? textOn(hex);
+    const r = ratio(hex, paper);
+    const isKey = keys.includes(hex.toLowerCase());
+    const locked = table.locked?.includes(Number(s));
+    const pinned = pal[s].$extensions?.['sl.override'];
+    return `<div class="sw" style="background:${hex};color:${on}" title="${s} ${hex} · ${round(r)}:1 on paper${isKey ? ' · brand key' : ''}${pinned ? ' · pinned' : ''}">
+      ${isKey ? '<span class="tag">KEY</span>' : locked ? '<span class="tag">AA</span>' : pinned ? '<span class="tag">PIN</span>' : ''}
+      <b>${s}</b><span class="r">${round(r)}:1</span><span class="h">${hex}</span></div>`;
+  });
+  return `<div class="ramp-wrap"><div class="ramp" role="img" aria-label="${role} ramp">${cells.join('')}</div></div>
+    ${curveHtml(role, steps.map((st) => pal[st].$value), keys)}
+    ${p.darkest ? `<div class="ends"><span><i style="background:${p.darkest}"></i>ends at ${esc(p.darkest)}</span></div>` : ''}`;
+}
+
+/** Chroma against lightness: the path the ramp takes from paper to ink, with the keys on it. */
+function curveHtml(role, hexes, keys) {
+  const w = 560, h = 110, pad = 18;
+  const pts = hexes.map((hex) => ({ hex, ...oklch(hex) }));
+  const ks = keys.map((hex) => ({ hex, ...oklch(hex) }));
+  const maxC = Math.max(0.12, ...pts.map((q) => q.c ?? 0), ...ks.map((q) => q.c ?? 0));
+  const x = (l) => pad + (1 - l) * (w - pad * 2);
+  const y = (c) => h - pad - ((c ?? 0) / maxC) * (h - pad * 2);
+  const line = pts.map((q, i) => `${i ? 'L' : 'M'}${x(q.l).toFixed(1)} ${y(q.c).toFixed(1)}`).join(' ');
+  return `<svg class="curve" viewBox="0 0 ${w} ${h}" role="img" aria-label="${role} chroma by lightness">
+    <line x1="${pad}" x2="${w - pad}" y1="${h - pad}" y2="${h - pad}" class="tick"/>
+    <text x="${pad}" y="${h - 4}">lighter</text><text x="${w - pad}" y="${h - 4}" text-anchor="end">darker</text>
+    <text x="${pad}" y="11">chroma ${round(maxC, 2)}</text>
+    <path d="${line}" fill="none" stroke="var(--strong)" stroke-width="1.5"/>
+    ${pts.map((q) => `<circle cx="${x(q.l)}" cy="${y(q.c)}" r="5" fill="${q.hex}" stroke="var(--line)"/>`).join('')}
+    ${ks.map((q) => `<rect x="${x(q.l) - 5}" y="${y(q.c) - 5}" width="10" height="10" transform="rotate(45 ${x(q.l)} ${y(q.c)})" fill="${q.hex}" stroke="var(--fg)" stroke-width="1.5"><title>key ${q.hex}</title></rect>`).join('')}
+  </svg>`;
+}
+
+function tablesHtml() {
+  // Each table's targets on a log scale of contrast, with the WCAG lines.
+  const max = 21;
+  const x = (r) => 30 + (Math.log(r) / Math.log(max)) * 560;
+  return Object.entries(state.brand.color.contrast).map(([name, t]) => {
+    const marks = Object.entries(t.targets).map(([s, r], i) => {
+      const y = [16, 31, 46][i % 3];
+      return `<line x1="${x(r)}" x2="${x(r)}" y1="54" y2="${y + 4}" class="tick"/><circle cx="${x(r)}" cy="58" r="4" fill="${t.locked?.includes(Number(s)) ? 'var(--accent)' : 'var(--fg)'}"/><text x="${x(r)}" y="${y}" text-anchor="middle">${s}</text>`;
+    });
+    const lvls = [[3, 'AA large'], [4.5, 'AA'], [7, 'AAA']].map(([r, l]) => `<line x1="${x(r)}" x2="${x(r)}" y1="10" y2="72" class="lvl"/><text x="${x(r) + 3}" y="84">${l} ${r}</text>`);
+    const axis = [1, 2, 5, 10, 21].map((r) => `<text x="${x(r)}" y="100" text-anchor="middle">${r}:1</text>`);
+    return `<div class="panel"><h3>${esc(name)}</h3><svg class="scale-svg" viewBox="0 0 620 106" role="img" aria-label="${esc(name)} contrast targets">
+      <line x1="30" x2="590" y1="58" y2="58" stroke="var(--line)"/>${lvls.join('')}${marks.join('')}${axis.join('')}</svg>
+      <p class="muted">${Object.keys(t.targets).length} steps. Filled accent dots are locked.</p></div>`;
+  }).join('');
+}
+
+function endsHtml() {
+  const { paper, ink } = state.brand.color;
+  return `<div class="panel" style="background:${paper};color:${ink};border-color:${ink}22">
+    <h3 style="font-size:1.6rem">Ink on paper</h3><p>${round(ratio(paper, ink))}:1. This is the most contrast any pair in the system can have.</p></div>`;
+}
+
+function alertsHtml() {
+  const c = colors();
+  return `<div class="alerts">${ALERT_ROLES.map((r) => {
+    const bg = c[r]['75']?.$value ?? c[r]['50'].$value;
+    const edge = c[r]['500'].$value;
+    const fg = c[r]['900']?.$value ?? c[r]['800'].$value;
+    const copy = { success: ['Saved', 'Your changes are live.'], warning: ['Check this', 'Two fields need a second look.'], error: ['Couldn’t save', 'The server didn’t answer. Try again.'], info: ['Heads up', 'Trails close at sundown.'] }[r];
+    return `<div class="alert" style="background:${bg};border-color:${edge};color:${fg}"><b>${copy[0]}</b><span>${copy[1]}</span>
+      <span class="mono">${r} 900 on 75 · ${round(ratio(fg, bg))}:1</span></div>`;
+  }).join('')}</div>`;
+}
+
+const dataKey = () => JSON.stringify([state.brand.color.data, state.brand.color.paper, state.dataGoal]);
+const visionName = (v) => ({ typical: 'typical vision', protan: 'red-blind vision', deutan: 'green-blind vision', tritan: 'blue-blind vision' })[v];
+
+/** One note per color that has problems, in series order. */
+function dataNotes() {
+  const data = state.brand.color.data;
+  const byColor = new Map();
+  for (const p of checkDataColors(data, state.brand.color.paper, state.dataGoal)) {
+    const note = byColor.get(p.i) ?? { contrast: null, alike: [] };
+    if (p.kind === 'contrast') note.contrast = p.value;
+    else note.alike.push(p.vision);
+    byColor.set(p.i, note);
+  }
+  return [...byColor].map(([i, { contrast, alike }]) => {
+    const [name] = data[i];
+    const parts = [];
+    if (contrast !== null) parts.push(`is ${round(contrast)}:1 on paper, so bars and lines need an outline to be seen`);
+    if (alike.length) parts.push(`looks like ${data[i - 1][0]} next to it with ${alike.map(visionName).join(', ')}`);
+    return { i, text: `${name} ${parts.join(', and ')}.` };
+  });
+}
+
+function dataHtml() {
+  const data = state.brand.color.data;
+  const paper = state.brand.color.paper;
+  const notes = dataNotes();
+  const flagged = new Set(notes.map((n) => n.i));
+  const fixes = state.dataFixes?.key === dataKey() ? state.dataFixes.hex : null;
+  const chips = data.map(([name, hex], i) => `<span class="chip${flagged.has(i) ? ' flag' : ''}"><i style="background:${hex}"></i>${i + 1} ${esc(name)}<br>${round(ratio(hex, paper))}:1</span>`);
+  const values = [62, 48, 75, 33, 57, 41, 69, 52, 28, 64, 45, 71, 37, 59, 50, 66, 30, 55, 43, 68];
+  const n = Math.min(data.length, 12);
+  const w = 560, h = 180, left = 34, bw = (w - left - 10) / n;
+  const y = (v) => h - 20 - (v / 100) * (h - 40);
+  const grid = [0, 25, 50, 75, 100].map((v) => `<line class="grid" x1="${left}" x2="${w - 6}" y1="${y(v)}" y2="${y(v)}"/><text x="${left - 6}" y="${y(v) + 3}" text-anchor="end">${v}</text>`);
+  const bars = data.slice(0, n).map(([name, hex], i) => `<rect x="${left + i * bw + 3}" y="${y(values[i])}" width="${bw - 6}" height="${y(0) - y(values[i])}" rx="2" fill="${hex}"><title>${esc(name)}: ${values[i]}</title></rect>`);
+  const fixFor = (i) => {
+    if (!fixes) return '';
+    const hex = fixes[i];
+    if (!hex) return '<span class="muted">No nearby color clears this; try another hue or move it in the order.</span>';
+    return `<button class="fix" type="button" data-act="data-fix" data-i="${i}" data-hex="${hex}" title="Use ${hex} for ${esc(data[i][0])}">
+      <i style="background:${data[i][1]}"></i>→<i style="background:${hex}"></i> Use ${hex}</button>`;
+  };
+  const actions = !notes.length ? ''
+    : fixes ? `<div class="row"><button class="btn small" type="button" data-act="data-fix-all">Use every fix</button></div>`
+    : `<div class="row"><button class="btn small" type="button" data-act="data-suggest">Suggest fixes</button>
+        <span class="muted">Finds the nearest color that clears each check, for every kind of color vision.</span></div>`;
+  return `<div class="chips">${chips.join('')}</div>
+    <div class="panel"><span class="lbl">The first ${n} series in a column chart (sample values)</span>
+      <svg class="chart" viewBox="0 0 ${w} ${h}" role="img" aria-label="Sample chart with the data colors">${grid.join('')}${bars.join('')}</svg></div>
+    ${notes.length ? `<ul class="warn-list">${notes.map((note) => `<li><span>${esc(note.text)}</span>${fixFor(note.i)}</li>`).join('')}</ul>${actions}`
+      : '<p class="muted">Every color shows on paper and every neighbor is easy to tell apart, for every kind of color vision.</p>'}`;
+}
+
+function suggestDataFixes() {
+  const { data, paper } = state.brand.color;
+  const hex = {};
+  for (const { i } of dataNotes()) hex[i] = nudgeDataColor(data, i, paper, state.dataGoal);
+  state.dataFixes = { key: dataKey(), hex };
+}
+
+/** Applies fixes in series order, re-checking each against the colors already fixed. */
+function fixAllData() {
+  const { data, paper } = state.brand.color;
+  for (const { i } of dataNotes()) {
+    const still = checkDataColors(data, paper, state.dataGoal).some((p) => p.i === i);
+    const hex = still && nudgeDataColor(data, i, paper, state.dataGoal);
+    if (hex) data[i][1] = hex;
+  }
+}
+
+const PREVALENCE = {
+  deuteranopia: 'About 6 in 100 men, including milder forms',
+  protanopia: 'About 2 in 100 men, including milder forms',
+  tritanopia: 'About 1 in 10,000 people',
+  achromatopsia: 'About 1 in 30,000 people, plus grayscale screens and print',
+};
+const seeHex = (vision, hex) => formatHex(VISIONS[vision].see(hex));
+
+/** Five cards: the brand, then each theme. A theme card opens its colors for tuning. */
+function visionHtml() {
+  const c = state.brand.color;
+  const generated = visionColors(c);
+  const roles = Object.keys(Object.values(generated)[0]?.keys ?? {});
+  const card = ({ id, title, sub, note, keys, data, sees, open }) => {
+    const show = (hex) => (sees && state.visionSeen ? seeHex(sees, hex) : hex);
+    return `<article class="vcard${open ? ' open' : ''}">
+      <header><b>${title}</b><span class="muted">${sub}</span></header>
+      <div class="vcard-keys">${keys.map(([r, hex]) => `<i style="background:${show(hex)}" title="${esc(r)} ${hex}"></i>`).join('')}</div>
+      <div class="vision-data">${data.map(([name, hex]) => `<i style="background:${show(hex)}" title="${esc(name)} ${hex}"></i>`).join('')}</div>
+      <small class="muted">${note}</small>
+      ${id ? `<button class="btn small" type="button" data-act="vision-open" data-theme="${id}" aria-expanded="${open}">${open ? 'Close' : 'Tune colors'}</button>` : ''}</article>`;
+  };
+  const brandCard = card({
+    title: 'Brand', sub: 'Typical color vision', note: `${roles.length} palettes and ${c.data.length} data colors, as designed above.`,
+    keys: roles.map((r) => [r, generated[Object.keys(generated)[0]].brandKeys[r]]), data: c.data,
+  });
+  const themeCards = Object.entries(generated).map(([theme, g]) => {
+    const { name, label, sees } = VISION_THEMES[theme];
+    const pins = Object.keys(c.vision?.[theme]?.keys ?? {}).length + Object.keys(c.vision?.[theme]?.data ?? {}).length;
+    const blur = g.blurred.before === g.blurred.after ? `${g.blurred.after} pairs blur together` : `Blurred pairs: ${g.blurred.before} → ${g.blurred.after}`;
+    return card({
+      id: theme, title: name, sub: label, sees, open: state.visionOpen === theme,
+      note: `${PREVALENCE[theme]}. ${blur}${pins ? `. ${pins} pinned` : ''}.`,
+      keys: Object.entries(g.keys), data: g.data,
+    });
+  });
+  return `<div class="vcards">${brandCard}${themeCards.join('')}</div>`;
+}
+
+/** Every color of the open theme: brand and theme, each as designed and as seen, with a pin. */
+function visionDetailHtml() {
+  const theme = state.visionOpen;
+  if (!theme) return '';
+  const c = state.brand.color;
+  const g = visionColors(c)[theme];
+  const { name, sees } = VISION_THEMES[theme];
+  const pins = c.vision?.[theme] ?? {};
+  const sw = (hex, title) => `<i class="sw-s" style="background:${hex}" title="${esc(title)} ${hex}"></i>`;
+  const row = (label, kind, key, brandHex, themeHex) => {
+    const pinned = pins[kind]?.[key];
+    return `<tr><th scope="row">${esc(label)}</th>
+      <td>${sw(brandHex, 'brand')}${sw(seeHex(sees, brandHex), 'brand, as seen')}</td>
+      <td>${sw(themeHex, name)}${sw(seeHex(sees, themeHex), `${name}, as seen`)}</td>
+      <td>${colorIn(`color.vision.${theme}.${kind}.${key}`, pinned ?? themeHex, `${name} ${label}`)}</td>
+      <td>${pinned ? `<button class="btn small" type="button" data-act="vision-unpin" data-theme="${theme}" data-kind="${kind}" data-key="${esc(key)}">Use generated</button>` : `<span class="muted">${themeHex.toLowerCase() === brandHex.toLowerCase() ? 'same as brand' : 'generated'}</span>`}</td></tr>`;
+  };
+  const head = '<thead><tr><th></th><th>Brand · as seen</th><th>Theme · as seen</th><th>Color</th><th></th></tr></thead>';
+  const paletteRows = Object.entries(g.keys).map(([r, hex]) => row(c.palettes[r].label ? `${c.palettes[r].label} (${r})` : r, 'keys', r, g.brandKeys[r], hex));
+  const dataRows = g.data.map(([n, hex], i) => row(n, 'data', n, c.data[i][1], hex));
+  return `<div class="panel vision-detail"><div class="row"><h3>${name} colors</h3>
+      <button class="btn small" type="button" data-act="vision-open" data-theme="${theme}">Close</button></div>
+    <small class="muted">Each pair of swatches is the color, then how it looks with ${name.toLowerCase()}. Change a color to pin it; the others move to make room. A palette's color is its most colorful key, and the whole ramp follows it.</small>
+    <div class="table-wrap"><table class="vtable">${head}<tbody><tr><td colspan="5" class="vgroup">Palettes</td></tr>${paletteRows.join('')}
+      <tr><td colspan="5" class="vgroup">Data colors</td></tr>${dataRows.join('')}</tbody></table></div></div>`;
+}
+
+function pairsHtml() {
+  const pairs = state.brand.color.pairs ?? {};
+  const problems = state.result.problems;
+  if (!Object.keys(pairs).length) return '<p class="muted">No pairs yet. Run <code>loomiere lab</code> to pick some.</p>';
+  const cards = Object.entries(pairs).map(([name, spec]) => {
+    const bg = hexAt(pairRef(spec.bg)), fg = hexAt(pairRef(spec.fg)), accent = spec.accent && hexAt(pairRef(spec.accent));
+    if (!bg || !fg) return `<div class="pair"><b>${esc(name)}</b><span>Uses a color that no longer exists.</span></div>`;
+    return `<div class="pair" style="background:${bg};color:${fg}"><b>${esc(name)}</b>
+      <span>${esc(spec.fg)} on ${esc(spec.bg)} · ${round(ratio(fg, bg))}:1</span>
+      ${accent ? `<span style="color:${accent}">accent ${esc(spec.accent)} · ${round(ratio(accent, bg))}:1</span>` : ''}</div>`;
+  });
+  return `${problems.length ? `<div class="notice bad"><p>These pairs would stop the build:<br>${problems.map(esc).join('<br>')}</p></div>` : ''}<div class="pairs">${cards.join('')}</div>`;
+}
+
+/* Roles: the ladder and a few Base UI parts, drawn from the scope slots in light and dark. */
+const tableOf = (palette) => (state.brand.color.palettes[palette]?.contrast === 'neutral' ? 'neutral' : 'spot');
+const slotHex = (palette, slot, dark) => hexAt(stepRef(palette, SLOTS[tableOf(palette)][slot][dark ? 1 : 0]).slice(1, -1));
+
+/** A pick or token value ("{color.x.y}" or a hex) as a hex. */
+const refHex = (ref) => (ref?.startsWith('{') ? hexAt(ref.slice(1, -1)) : ref ?? null);
+/** A role concept's hex with the brand's picks applied, the way the build makes it. */
+const conceptHex = (role, slot, dark) => refHex(conceptModes(state.brand, withDefaults(state.brand.roles), role, slot)[dark ? 'dark' : 'light']);
+/** A slot's hex in a role (with picks) or a named palette (as generated). */
+const scopeHex = (color, slot, dark) => (color === 'accent' || color === 'chrome' ? conceptHex(color, slot, dark) : slotHex(color, slot, dark));
+
+function paint(level, dark, palette) {
+  const r = withDefaults(state.brand.roles);
+  const { style, color } = r.emphasis[level];
+  return Object.fromEntries(Object.entries(STYLES[style]).map(([part, slot]) => [part, slot === 'transparent' ? 'transparent' : scopeHex(palette ?? color, slot, dark)]));
+}
+
+function rolesScene(dark) {
+  const r = withDefaults(state.brand.roles);
+  const ch = r.chrome, ac = r.accent;
+  const c = (sl) => conceptHex('chrome', sl, dark);
+  const page = c('canvas');
+  const text = c('fg');
+  const muted = c('fg-secondary');
+  const raised = c('raised');
+  const line = c('border-subtle');
+  const field = c('border');
+  const slot = (p, sl) => (p === ac ? conceptHex('accent', sl, dark) : p === ch ? c(sl) : slotHex(p, sl, dark));
+  const warn = dark ? '#ff8a80' : '#b42318';
+  // A level's color: accent levels read the accent, chrome levels the chrome, so both flash.
+  const uses = (level) => `${level} ${r.emphasis[level].color}`;
+  const btn = (level, label, { palette, on = page, rate = false } = {}) => {
+    const e = paint(level, dark, palette);
+    const cr = ratio(e.fg, e.bg === 'transparent' ? on : e.bg);
+    const button = `<span class="rb" data-uses="${palette ? 'palette' : uses(level)}" title="${level}${palette ? ` in ${palette}` : ''}: ${r.emphasis[level].style}, ${round(cr, 1)}:1" style="background:${e.bg};color:${e.fg};border-color:${e.border}">${esc(label)}</span>`;
+    return rate ? `<span class="rb-wrap">${button}<small style="color:${cr < 4.5 ? warn : muted}">${round(cr, 1)}:1${cr < 4.5 ? ' low' : ''}</small></span>` : button;
+  };
+  const tag = (t) => `<em class="uses" style="color:${muted}">${t}</em>`;
+  const spots = Object.keys(state.brand.color.palettes).filter((n) => tableOf(n) === 'spot');
+  const hl = paint('subtle', dark);
+  return `<div class="scene" style="background:${page};color:${text}">
+    <b class="scene-label" style="color:${muted}">${dark ? 'Dark' : 'Light'}</b>
+    <div class="rapp-bar" data-uses="chrome" style="background:${raised};border-color:${line}">
+      <b>Dunes</b>
+      <nav>${['Surveys', 'Maps', 'Team'].map((t, i) => `<span data-uses="${i === 0 ? 'accent' : 'chrome'}" style="color:${i === 0 ? slot(ac, 'fg') : muted}">${t}</span>`).join('')}</nav>
+      ${btn('bold', 'New survey', { on: raised })}
+    </div>
+    <div class="rgrid">
+      <div class="rcard" data-uses="chrome" style="background:${raised};border-color:${line}">
+        <b>Dune survey</b><span style="color:${muted}">Three sites logged at dusk.</span>
+        <div class="rb-row">${btn('bold', 'Open', { on: raised })}${btn('standard', 'Edit', { on: raised })}${btn('subtle', 'Copy', { on: raised })}${btn('quiet', 'Archive', { on: raised })}</div></div>
+      <div class="rform">
+        <span class="ri" data-uses="chrome" style="border-color:${field};color:${muted}">Search surveys</span>
+        <span class="ri" data-uses="accent" style="border-color:${field};outline:2px solid ${slot(ac, 'focus')};outline-offset:2px;color:${text}">Focused field</span>
+        <span class="rb-row">
+          <span class="rcheck-row" data-uses="accent"><i class="rcheck" style="background:${slot(ac, 'solid')};color:${slot(ac, 'on-solid')}">✓</i>Checked</span>
+          <span class="rcheck-row" data-uses="accent"><i class="rswitch" style="background:${slot(ac, 'solid')}"><i style="background:${slot(ac, 'on-solid')}"></i></i>On</span>
+          <span class="rcheck-row" data-uses="chrome"><i class="rswitch off" style="background:${slot(ch, 'soft-active')}"><i style="background:${page}"></i></i>Off</span>
+        </span>
+      </div>
+      <div class="rmenu" data-uses="chrome" style="background:${raised};border-color:${line}">
+        <span>Rename</span><span data-uses="${uses('subtle')}" style="background:${hl.bg};color:${hl.fg}" title="Highlighted item: the subtle level">Duplicate</span><span>Move to…</span>
+        <span data-uses="palette" style="color:${slot('error', 'fg') ?? text}">Delete</span></div>
+    </div>
+    <div class="rtabs" data-uses="accent" style="border-color:${line}">${['Overview', 'Activity', 'Settings'].map((t, i) => `<span style="${i === 0 ? `color:${slot(ac, 'fg')};border-color:${slot(ac, 'solid')}` : `color:${muted};border-color:transparent`}">${t}</span>`).join('')}</div>
+    ${['error', 'success'].filter((p) => state.brand.color.palettes[p]).map((p) => `<div class="ralert" data-uses="palette" style="background:${slot(p, 'soft')};color:${slot(p, 'on-soft')};border-color:${slot(p, 'border-subtle')}">
+      <b>${p === 'error' ? 'Upload failed' : 'Saved'}</b> ${p === 'error' ? 'The file is over 20 MB.' : 'Your changes are live.'}</div>`).join('')}
+    <div class="rladder">${tag('Emphasis ladder')}<div class="rb-row">${LEVELS.map((l) => btn(l, l, { rate: true })).join('')}</div></div>
+    <div class="rladder">${tag('Bold in every palette (data-color)')}<div class="rb-row">${spots.map((p) => btn('bold', p, { palette: p, rate: true })).join('')}</div></div>
+  </div>`;
+}
+
+/** Briefly marks the preview parts that read a role setting, so a change shows where it lands. */
+function flashUses(bind) {
+  const [, what, level] = bind.split('.');
+  const key = what === 'emphasis' ? level : what;
+  for (const el of document.querySelectorAll(`#pv-theme-out [data-uses~="${key}"]`)) {
+    el.classList.remove('flash');
+    void el.offsetWidth;
+    el.classList.add('flash');
+  }
+}
+
+const rolesHtml = () => `<div class="scenes">${rolesScene(false)}${rolesScene(true)}</div>`;
+
+/* Concepts: one row per reused color, light and dark, with the step it uses and a reset. */
+function conceptPicker(key, mode, role, current, fallback) {
+  const palettes = state.brand.color.palettes;
+  const steps = (name) => Object.keys(colors()[name] ?? {}).filter((k) => k !== 'on');
+  const own = withDefaults(state.brand.roles)[role];
+  const opt = (value, label) => `<option value="${esc(value)}"${value === current ? ' selected' : ''}>${esc(label)}${value === fallback ? ' (default)' : ''}</option>`;
+  const group = (name) => `<optgroup label="${esc(name)}">${steps(name).map((st) => opt(`${name}.${st}`, `${name} ${st}`)).join('')}</optgroup>`;
+  const hex = /^#/.test(current);
+  // On-colors and other steps the lists leave out still show as the selected option.
+  const listed = hex || current === 'white' || current === 'black' || Object.keys(palettes).some((n) => steps(n).some((st) => `${n}.${st}` === current));
+  return `<span class="cpick"><select data-concept="${key}" data-mode="${mode}" aria-label="${key} ${mode}">
+      ${listed ? '' : opt(current, current.replace('.', ' '))}${group(own)}<optgroup label="Ends">${opt('white', 'Paper')}${opt('black', 'Ink')}</optgroup>
+      ${Object.keys(palettes).filter((n) => n !== own).map(group).join('')}
+      <optgroup label="Other">${opt(hex ? current : '#', hex ? `Hex ${current}` : 'Hex…')}</optgroup></select>
+    ${hex ? `<input type="text" class="chex" data-concept-hex="${key}" data-mode="${mode}" value="${esc(current)}" spellcheck="false" aria-label="${key} ${mode} hex">` : ''}</span>`;
+}
+
+function conceptsHtml() {
+  const r = withDefaults(state.brand.roles);
+  const palettes = state.brand.color.palettes;
+  const warn = '#b42318';
+  // Emphasis levels read concepts too: a level in a role reads that role's slots.
+  const levelUses = (role, slot) => LEVELS.filter((l) => r.emphasis[l].color === role && Object.values(STYLES[r.emphasis[l].style]).includes(slot)).map((l) => `emphasis ${l}`);
+  let lastGroup = '';
+  const rows = CONCEPTS.filter(({ role, slot }) => SLOTS[tableOf(r[role])]?.[slot]).map(({ role, group, slot, label, against, min }) => {
+    const key = `${role}.${slot}`;
+    const [l, d] = SLOTS[tableOf(r[role])][slot];
+    const pick = r.concepts?.[key] ?? {};
+    const other = against && (SLOTS[tableOf(r[role])][against] ? [role, against] : ['chrome', against]);
+    const cell = (mode) => {
+      const dark = mode === 'dark';
+      const hex = conceptHex(role, slot, dark);
+      const fallback = defaultPick(r[role], dark ? d : l);
+      const cr = other ? ratio(hex, conceptHex(other[0], other[1], dark)) : null;
+      const low = min && cr < min;
+      return `<td class="cswatch${dark ? ' dark' : ''}" style="--cbg:${conceptHex('chrome', 'canvas', dark)}"><i style="background:${hex}"></i>
+        <span>${conceptPicker(key, mode, role, pick[mode] ?? fallback, fallback)}
+        ${cr ? `<small class="${low ? 'bad' : 'muted'}" style="${low ? `color:${warn}` : ''}">${round(cr, 1)}:1 on ${other[1]}${low ? ` · below ${min}` : ''}</small>` : ''}</span></td>`;
+    };
+    const used = [...(state.uses[key] ?? []), ...levelUses(role, slot)];
+    const head = group !== lastGroup ? `<tr class="cgroup"><th colspan="4">${esc(group)} <small class="muted">${esc(r[role])}</small></th></tr>` : '';
+    lastGroup = group;
+    const changed = Object.keys(pick).length > 0;
+    return `${head}<tr data-uses="${role}">
+      <th><b>${esc(label)}</b><code>${key}</code>${changed ? `<button class="btn small" type="button" data-act="concept-reset" data-key="${key}">Reset</button>` : ''}</th>
+      ${cell('light')}${cell('dark')}
+      <td class="cused">${used.length ? used.map((u) => `<code>${esc(u)}</code>`).join(' ') : '<span class="muted">Only through data-color</span>'}</td></tr>`;
+  });
+  const bad = Object.keys(r.concepts ?? {}).filter((k) => !palettes[r[k.split('.')[0]]]);
+  return `${bad.length ? `<p class="notice bad">${bad.map(esc).join(', ')} no longer match a palette.</p>` : ''}
+    <div class="ctable-wrap"><table class="ctable"><thead><tr><th>Concept</th><th>Light</th><th>Dark</th><th>Used by</th></tr></thead><tbody>${rows.join('')}</tbody></table></div>`;
+}
+
+/** Saves a concept pick, dropping it (and the row) when it matches the default again. */
+function setConcept(key, mode, value) {
+  const r = withDefaults(state.brand.roles);
+  const [role, slot] = key.split('.');
+  const [l, d] = SLOTS[tableOf(r[role])][slot];
+  const roles = (state.brand.roles ??= {});
+  const picks = (roles.concepts ??= {});
+  const pick = (picks[key] ??= {});
+  if (value === defaultPick(r[role], mode === 'dark' ? d : l) || pickRef(value, state.brand.color.palettes) === undefined) delete pick[mode];
+  else pick[mode] = value;
+  if (!Object.keys(pick).length) delete picks[key];
+  if (!Object.keys(picks).length) delete roles.concepts;
+}
+
+const scaleAt = (t, r, step, width) => {
+  // The generator's own math, for one ratio, at one width.
+  const n = t.steps.indexOf(step) - t.steps.indexOf(t.baseStep);
+  const at = (base, rr) => base * rr ** n;
+  const small = at(t.base.min, r.min), large = at(t.base.max, r.max);
+  const k = Math.min(1, Math.max(0, (width - t.viewport.min) / (t.viewport.max - t.viewport.min)));
+  return small + (large - small) * k;
+};
+
+function typeHtml() {
+  const t = state.brand.type;
+  const files = state.result.files.type;
+  const pinnedCount = Object.values(files['font-size']).filter((v) => v.$extensions?.['sl.override']).length;
+  const fam = (r) => (t.families[r] ?? []).map((f) => (/\s/.test(f) ? `'${f}'` : f)).join(', ');
+  const w = state.width;
+  const rows = [...t.steps].reverse().map((s) => {
+    const tok = files['font-size'][s];
+    const px = pxAt(tok.$value, w);
+    const lh = files['line-height'][s].$value;
+    const pin = tok.$extensions?.['sl.override'] ? '<span class="pin">PIN</span>' : '';
+    const display = t.displayFrom && t.steps.indexOf(s) >= t.steps.indexOf(t.displayFrom);
+    const face = display ? fam('display') : fam('body');
+    return `<tr${s === t.baseStep ? ' class="base-row"' : ''}><td class="n">${s}${pin}</td><td class="n">${round(px, 1)}px</td><td class="n">${lh}<br><small>${round(px * lh, 1)}px</small></td>
+      <td class="s" style="font-family:${esc(face)};font-size:${px}px;line-height:${lh}">${SAMPLE}</td></tr>`;
+  });
+  const presets = RATIOS.map(([name, r]) => {
+    const ladder = ['xs', t.baseStep, ...t.steps.slice(t.steps.indexOf(t.baseStep) + 1, t.steps.indexOf(t.baseStep) + 5)]
+      .filter((s, i, a) => t.steps.includes(s) && a.indexOf(s) === i);
+    const onMin = Math.abs(t.ratio.min - r) < 0.0005, onMax = Math.abs(t.ratio.max - r) < 0.0005;
+    return `<div class="preset${onMin ? ' on-min' : ''}${onMax ? ' on-max' : ''}">
+      <div class="name">${name}<em>${r}</em></div>
+      <div class="ladder" style="font-family:${esc(fam('display'))}">${ladder.slice().reverse().map((s) => `<span style="font-size:${Math.min(56, scaleAt(t, { min: r, max: r }, s, t.viewport.max))}px">Aa ${s}</span>`).join('')}</div>
+      <div class="row"><button class="btn small" type="button" data-act="ratio" data-which="min" data-r="${r}" aria-pressed="${onMin}">Small screens</button>
+        <button class="btn small" type="button" data-act="ratio" data-which="max" data-r="${r}" aria-pressed="${onMax}">Large screens</button></div></div>`;
+  });
+  return `${pinnedCount && state.usePins ? `<div class="notice"><p>${pinnedCount} sizes are pinned in the overrides file, so scale changes don't move them. Turn pins off to see the math.</p>
+      <button class="btn small" type="button" data-act="pins-off">Turn pins off</button></div>` : ''}
+    <div class="panel"><span class="lbl">Compare ratios. Pick one for small screens and one for large; sizes ease between them.</span><div class="presets">${presets.join('')}</div></div>
+    <div class="panel"><span class="lbl">Every step at ${w}px wide</span>
+      <div class="table-wrap"><table class="type-table"><thead><tr><th>Step</th><th>Size</th><th>Line</th><th>Sample</th></tr></thead><tbody>${rows.join('')}</tbody></table></div>
+    </div>`;
+}
+
+function spaceHtml() {
+  const space = state.result.files.space.space;
+  // Integer-like keys sort first in a JS object, so order by size instead.
+  const rows = Object.entries(space).map(([s, t]) => [s, pxAt(t.$value, 0)]).sort((a, b) => a[1] - b[1]);
+  return `<div class="panel"><div class="bars">${rows.map(([s, px]) => `<div><span>${s}</span><span>${round(px, 1)}px</span><i style="width:${px}px"></i></div>`).join('')}</div></div>`;
+}
+
+function shapeHtml() {
+  const { radius } = state.result.files.radius;
+  const { stroke } = state.result.files.stroke;
+  return `<div class="panel"><span class="lbl">Radius</span><div class="tiles">${Object.entries(radius).map(([s, t]) => {
+    const px = pxAt(t.$value, 0);
+    return `<span class="tile"><i style="border-radius:${px}px"></i>${s} · ${round(px, 1)}px</span>`;
+  }).join('')}</div></div>
+  <div class="panel"><span class="lbl">Lines</span><div class="lines">${Object.entries(stroke).map(([s, t]) => {
+    const px = pxAt(t.$value, 0);
+    return `<div><span>${s} ${round(px, 1)}px</span><i style="height:${px}px"></i></div>`;
+  }).join('')}</div></div>`;
+}
+
+function shadowHtml() {
+  const { shadow } = state.result.files.shadow;
+  return `<div class="shadows">${Object.entries(shadow).filter(([s]) => s !== 'none').map(([s, t]) => `<div style="box-shadow:${t.$value}">${s}</div>`).join('')}</div>`;
+}
+
+function motionHtml() {
+  const { duration } = state.result.files.motion;
+  return `<div class="panel"><div class="row"><button class="btn small" type="button" data-act="play">Play</button><span class="muted">Each dot crosses in its duration.</span></div>
+    <div class="motion-rows">${Object.entries(duration).map(([s, t]) => `<div><span>${s} · ${t.$value}</span><span class="track" style="--w:100%"><i style="transition-duration:${t.$value}"></i></span></div>`).join('')}</div></div>`;
+}
+
+function fileHtml() {
+  const text = currentText();
+  const pins = Object.entries(state.overrides).filter(([k]) => !k.startsWith('$'));
+  return `<div class="band-body"><div class="edit">
+      <div class="panel"><h3>${text === state.savedText ? 'No unsaved changes' : 'Unsaved changes'}</h3>
+        <p class="muted">${state.static ? 'This copy can\'t write files. Copy the JSON into <code>brand/NAME.json</code>, or open the builder with <code>loomiere studio</code> to save directly.' : `Save writes <code>${esc(state.dir)}/${esc(state.name)}.json</code>${state.built ? ' and rebuilds the tokens' : ''}.`}</p>
+        <div class="row"><button class="btn" type="button" data-act="revert"${text === state.savedText ? ' disabled' : ''}>Undo all changes</button></div></div>
+      <div class="panel"><h3>Pins</h3><p class="muted">${pins.length ? `${pins.length} exact values sit on top of the math in <code>${esc(state.name)}.overrides.json</code>.` : 'No pins. Everything comes from the math.'}</p>
+        ${pins.length ? `<pre class="json">${esc(pins.map(([k, v]) => `${k}: ${v}`).join('\n'))}</pre>` : ''}
+        ${state.pinError ? `<div class="notice bad"><p>${esc(state.pinError)}. The preview is showing the math without pins.</p></div>` : ''}</div>
+    </div><pre class="json" id="brand-json" aria-label="Brand file">${esc(text)}</pre></div>`;
+}
+
+/* ---------- render ---------- */
+
+const currentText = () => formatBrand({ $schema: state.schema, name: state.name, ...state.brand });
+
+function stepNav() {
+  const i = STEPS.findIndex((st) => st.id === state.step);
+  const prev = STEPS[i - 1], next = STEPS[i + 1];
+  return `<div class="step-end">${prev ? `<button class="btn" type="button" data-act="step" data-step="${prev.id}">← ${prev.label}</button>` : '<span></span>'}
+    ${next ? `<button class="btn primary" type="button" data-act="step" data-step="${next.id}">Next: ${next.label} →</button>` : ''}</div>`;
+}
+
+function renderSteps() {
+  if (!STEPS.some((st) => st.id === state.step)) state.step = 'brand';
+  $('steps').innerHTML = STEPS.map((st, i) => `<button type="button" class="step${st.id === state.step ? ' on' : ''}" data-act="step" data-step="${st.id}" aria-current="${st.id === state.step ? 'step' : 'false'}"><b>${i + 1}</b> ${esc(st.label)}</button>`).join('');
+  const step = STEPS.find((st) => st.id === state.step);
+  $('rail').innerHTML = step.groups.map(([label, items]) => `<span class="rail-label">${esc(label)}</span>${items.map(([id, name]) => `<a href="#${id}">${esc(name)}</a>`).join('')}`).join('')
+    + '<span class="rail-label">Output</span><a href="#file">Brand file</a>';
+}
+
+function renderEditors() {
+  renderSteps();
+  $('main').innerHTML = editorsHtml() + stepNav();
+  // Every step keeps every input on the page (so previews stay wired); only this step's show.
+  for (const el of $('main').querySelectorAll('section.band')) el.hidden = el.id !== 'file' && stepOf(el.id) !== state.step;
+  renderPreviews();
+}
+
+function goStep(id) {
+  state.step = id;
+  try { localStorage.setItem('brand-builder-step', id); } catch { /* the step just won't be remembered */ }
+  renderEditors();
+  window.scrollTo({ top: 0 });
+}
+
+function renderPreviews() {
+  compute();
+  const error = $('status');
+  if (state.error) {
+    error.textContent = `The generator stopped: ${state.error}`;
+    error.className = 'status bad';
+    return;
+  }
+  if (error.classList.contains('bad')) { error.textContent = ''; error.className = 'status'; }
+  const put = (id, html) => { const el = $(id); if (el) el.innerHTML = html; };
+  put('pv-ends', endsHtml());
+  put('pv-tables', tablesHtml());
+  for (const r of [...BRAND_ROLES, ...ALERT_ROLES]) put(`pv-pal-${r}`, rampHtml(r));
+  put('pv-alert-sample', alertsHtml());
+  put('pv-data', dataHtml());
+  put('pv-pairs', pairsHtml());
+  put('pv-theme-out', rolesHtml());
+  put('pv-concepts', conceptsHtml());
+  put('pv-strip', Object.keys(state.brand.color.palettes).map((n) => `<span><i style="background:${hexAt(`color.${n}.600`) ?? 'transparent'}"></i>${esc(n)}</span>`).join(''));
+  put('pv-vision', visionHtml());
+  put('pv-type-out', typeHtml());
+  put('pv-space', spaceHtml());
+  put('pv-shape', shapeHtml());
+  put('pv-elevation', shadowHtml());
+  put('pv-motion', motionHtml());
+  put('pv-file', fileHtml());
+  loadFonts();
+  const dirty = currentText() !== state.savedText;
+  $('file-name').innerHTML = `${esc(state.name)}.json${dirty ? ' <span class="dirty">● unsaved</span>' : ''}`;
+  $('pins-label').textContent = `Pins (${Object.keys(state.overrides).filter((k) => !k.startsWith('$')).length})`;
+}
+
+let fontsLoaded = '';
+/** Ascent, descent, cap and x-height in em for each family, read from the loaded font files. */
+async function measureFonts() {
+  const generic = /^(serif|sans-serif|monospace|system-ui|cursive|fantasy|ui-\w+)$/;
+  const ctx = document.createElement('canvas').getContext('2d');
+  const metrics = {};
+  for (const [role, stack] of Object.entries(state.brand.type.families)) {
+    const family = stack.find((f) => !generic.test(f));
+    if (!family) continue;
+    const font = `400 1000px "${family}"`;
+    await document.fonts.load(font);
+    if (!document.fonts.check(font)) { status(`Couldn't load ${family} to measure it.`, true); continue; }
+    ctx.font = font;
+    const H = ctx.measureText('H'), x = ctx.measureText('x');
+    metrics[role] = {
+      ascent: round(H.fontBoundingBoxAscent / 1000, 3),
+      descent: round(H.fontBoundingBoxDescent / 1000, 3),
+      capHeight: round(H.actualBoundingBoxAscent / 1000, 3),
+      xHeight: round(x.actualBoundingBoxAscent / 1000, 3),
+    };
+  }
+  state.brand.type.metrics = { ...state.brand.type.metrics, ...metrics };
+  status(`Measured ${Object.keys(metrics).join(', ')}.`);
+}
+
+function loadFonts() {
+  const generic = /^(serif|sans-serif|monospace|system-ui|cursive|fantasy|ui-\w+)$/;
+  const names = [...new Set(Object.values(state.brand.type.families).flat().filter((f) => !generic.test(f)))];
+  const key = names.join('|');
+  if (!names.length || key === fontsLoaded) return;
+  fontsLoaded = key;
+  let link = document.getElementById('brand-fonts');
+  if (!link) { link = document.createElement('link'); link.rel = 'stylesheet'; link.id = 'brand-fonts'; document.head.append(link); }
+  link.href = `https://fonts.googleapis.com/css2?${names.map((n) => `family=${encodeURIComponent(n).replace(/%20/g, '+')}:wght@400;600;700`).join('&')}&display=swap`;
+}
+
+/* ---------- events ---------- */
+
+let pending = 0;
+const schedule = () => { cancelAnimationFrame(pending); pending = requestAnimationFrame(renderPreviews); };
+
+function readInput(el) {
+  const kind = el.dataset.kind;
+  if (kind === 'number') return el.value === '' ? undefined : Number(el.value);
+  if (kind === 'bool') return el.checked;
+  if (kind === 'list-num') return el.value.split(/[,\s]+/).filter(Boolean).map(Number).filter((n) => !Number.isNaN(n));
+  if (kind === 'list-str') return el.value.split(',').map((s) => s.trim()).filter(Boolean);
+  if (kind === 'hex') return /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.test(el.value.trim()) ? el.value.trim().toLowerCase() : undefined;
+  return el.value;
+}
+
+document.addEventListener('input', (e) => {
+  const el = e.target;
+  if (el.id === 'width') { state.width = Number(el.value); $('width-out').textContent = `${el.value}px`; return schedule(); }
+  if (el.dataset.special === 'name') { state.name = el.value.toLowerCase().replace(/[^a-z0-9-]+/g, '-'); return schedule(); }
+  const bind = el.dataset.bind;
+  if (!bind || el.dataset.kind === 'bool' || el.dataset.kind === 'select') return;
+  const value = readInput(el);
+  if (value === undefined) return;
+  set(bind, value);
+  // Keep a color's picker and hex box in step.
+  document.querySelectorAll(`[data-bind="${CSS.escape(bind)}"]`).forEach((other) => {
+    if (other === el) return;
+    if (other.dataset.kind === 'color') other.value = toHex6(value);
+    if (other.dataset.kind === 'hex') other.value = value;
+  });
+  const out = document.querySelector(`[data-out="${CSS.escape(bind)}"]`);
+  if (out) out.textContent = bind.includes('tone') ? `${Math.round(value * 100)}%` : `${value}×`;
+  schedule();
+});
+
+document.addEventListener('change', (e) => {
+  const el = e.target;
+  if (el.id === 'pins') { state.usePins = el.checked; return renderPreviews(); }
+  if (el.id === 'brand-pick') return loadBrand(el.value);
+  if (el.id === 'data-goal') { state.dataGoal = Number(el.value); return renderPreviews(); }
+  if (el.id === 'vision-seen') { state.visionSeen = el.checked; return renderPreviews(); }
+  if (el.id === 'vision-sim') { document.body.dataset.vision = el.value; return; }
+  if (el.dataset.rename) return renameKey(el.dataset.rename, el.dataset.key, el.value.trim());
+  if (el.dataset.concept || el.dataset.conceptHex) {
+    const key = el.dataset.concept ?? el.dataset.conceptHex;
+    // "Hex…" starts from the color the row shows now.
+    const value = el.value === '#' ? conceptHex(...key.split('.'), el.dataset.mode === 'dark') : el.value.trim().toLowerCase();
+    if (el.dataset.conceptHex && pickRef(value, {}) === undefined) return status('A hex looks like #221928.', true);
+    setConcept(key, el.dataset.mode, value);
+    return renderEditors();
+  }
+  if (el.dataset.lock) {
+    const locked = new Set(get(el.dataset.lock) ?? []);
+    if (el.checked) locked.add(Number(el.dataset.key)); else locked.delete(Number(el.dataset.key));
+    set(el.dataset.lock, locked.size ? [...locked].sort((a, b) => a - b) : undefined);
+    return renderPreviews();
+  }
+  const bind = el.dataset.bind;
+  if (!bind) return;
+  if (bind.endsWith('@toggle')) {
+    const real = bind.replace('@toggle', '');
+    set(real, el.checked ? state.brand.color.ink : undefined);
+    return renderEditors();
+  }
+  if (bind.startsWith('roles.')) {
+    set(bind, readInput(el));
+    renderEditors();
+    flashUses(bind);
+    return;
+  }
+  if (el.dataset.kind === 'bool' || el.dataset.kind === 'select') {
+    // "exact" is off unless it says otherwise, so leave it out of the file when it's off.
+    // Optional settings ("Never", "exact" off) are left out of the file rather than saved empty.
+    const off = (bind.endsWith('.exact') && !el.checked) || (el.dataset.kind === 'select' && el.value === '');
+    set(bind, off ? undefined : readInput(el));
+    // A new step list changes the step menus.
+    return renderEditors();
+  }
+  // New step names change the step menus; a pinned vision color gets its "Use generated" button.
+  if (bind === 'type.steps' || bind.startsWith('color.vision.')) renderEditors();
+});
+
+function renameKey(bind, from, to) {
+  if (!/^[\w-]+$/.test(to) || to === from) return renderEditors();
+  const obj = get(bind);
+  if (obj[to] !== undefined) return status(`There is already a step called ${to}.`, true);
+  set(bind, Object.fromEntries(Object.entries(obj).map(([k, v]) => [k === from ? to : k, v])));
+  renderEditors();
+}
+
+document.addEventListener('click', (e) => {
+  const b = e.target.closest('button[data-act]');
+  if (!b) return;
+  const { act, role, i, bind, key } = b.dataset;
+  const pal = role && state.brand.color.palettes[role];
+  const data = state.brand.color.data;
+  switch (act) {
+    case 'step': return goStep(b.dataset.step);
+    case 'concept-reset': {
+      const picks = state.brand.roles?.concepts;
+      if (picks) { delete picks[key]; if (!Object.keys(picks).length) delete state.brand.roles.concepts; }
+      break;
+    }
+    case 'key-add': (pal.keys ??= []).push(pal.keys.at(-1) ?? '#888888'); break;
+    case 'key-remove': pal.keys.splice(Number(i), 1); break;
+    case 'tone-add': pal.tone = { color: pal.keys?.[0] ?? '#888888', intensity: [0.1, 0.6] }; break;
+    case 'tone-remove': delete pal.tone; break;
+    case 'data-add': data.push([`color-${data.length + 1}`, '#888888']); break;
+    case 'data-remove': data.splice(Number(i), 1); break;
+    case 'data-up': [data[i - 1], data[i]] = [data[i], data[i - 1]]; break;
+    case 'data-fix': data[i][1] = b.dataset.hex; break;
+    case 'data-fix-all': fixAllData(); break;
+    case 'data-suggest': {
+      b.disabled = true;
+      b.textContent = 'Looking…';
+      // Let the button repaint before the search runs.
+      return setTimeout(() => { suggestDataFixes(); renderPreviews(); }, 30);
+    }
+    case 'map-add': {
+      const obj = get(bind);
+      let n = Object.keys(obj).length + 1;
+      while (obj[`step-${n}`] !== undefined) n++;
+      obj[`step-${n}`] = Object.values(obj).at(-1) ?? 1;
+      break;
+    }
+    case 'map-remove': delete get(bind)[key]; break;
+    case 'ratio': set(['type', 'ratio', b.dataset.which], Number(b.dataset.r)); break;
+    case 'vision-open': state.visionOpen = state.visionOpen === b.dataset.theme ? null : b.dataset.theme; break;
+    case 'vision-unpin': {
+      const v = state.brand.color.vision;
+      const { theme, kind } = b.dataset;
+      delete v[theme][kind][key];
+      if (!Object.keys(v[theme][kind]).length) delete v[theme][kind];
+      if (!Object.keys(v[theme]).length) delete v[theme];
+      if (!Object.keys(v).length) delete state.brand.color.vision;
+      break;
+    }
+    case 'measure-fonts': return measureFonts().then(renderEditors);
+    case 'pins-off': state.usePins = false; $('pins').checked = false; return renderPreviews();
+    case 'revert': state.brand = JSON.parse(state.savedText); delete state.brand.$schema; delete state.brand.name; break;
+    case 'play': {
+      const tracks = document.querySelectorAll('.track');
+      const going = tracks[0]?.classList.contains('go');
+      tracks.forEach((t) => t.classList.toggle('go', !going));
+      return;
+    }
+    default: return;
+  }
+  renderEditors();
+});
+
+/* ---------- load and save ---------- */
+
+function status(text, bad = false) {
+  $('status').textContent = text;
+  $('status').className = `status${bad ? ' bad' : ''}`;
+}
+
+function take(data) {
+  state.name = data.name;
+  state.dir = data.dir ?? 'brand';
+  state.schema = data.schema ?? 'https://unpkg.com/@scattered-light/loomiere/generator/brand.schema.json';
+  state.brands = data.brands;
+  state.built = data.built;
+  state.overrides = data.overrides ?? {};
+  state.uses = data.uses ?? {};
+  // The page owns $schema and name (the file name field), so the brand keeps only the rest.
+  const brand = { ...data.brand };
+  delete brand.$schema;
+  delete brand.name;
+  state.brand = brand;
+  state.savedText = currentText();
+  state.width = brand.type.viewport.max;
+  $('brand-pick').innerHTML = data.brands.map((b) => `<option${b === data.name ? ' selected' : ''}>${esc(b)}</option>`).join('');
+  $('brand-pick').hidden = state.static;
+  $('save').hidden = state.static;
+  renderEditors();
+}
+
+async function loadBrand(name) {
+  if (state.brand && currentText() !== state.savedText) {
+    status(`Switched without saving ${state.name}; its changes are gone.`);
+  }
+  const res = await fetch(`/api/brand?name=${encodeURIComponent(name)}`);
+  const data = await res.json();
+  if (!res.ok) return status(data.error, true);
+  take(data);
+}
+
+$('save').onclick = async () => {
+  if (state.error) return status('Fix the problem above before saving.', true);
+  $('save').disabled = true;
+  status('Saving…');
+  try {
+    const res = await fetch('/api/brand', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ name: state.name, brand: state.brand }) });
+    const body = await res.json();
+    if (!body.ok) throw new Error(body.error);
+    state.savedText = currentText();
+    if (!state.brands.includes(state.name)) { state.brands.push(state.name); $('brand-pick').innerHTML += `<option selected>${esc(state.name)}</option>`; }
+    status(body.output);
+    renderPreviews();
+  } catch (err) {
+    status(`Not saved: ${err.message}`, true);
+  } finally {
+    $('save').disabled = false;
+  }
+};
+
+$('copy').onclick = async () => {
+  try {
+    await navigator.clipboard.writeText(currentText());
+    status(`Copied ${state.name}.json to the clipboard.`);
+  } catch {
+    const pre = $('brand-json');
+    if (pre) { const r = document.createRange(); r.selectNodeContents(pre); getSelection().removeAllRanges(); getSelection().addRange(r); pre.scrollIntoView({ block: 'center' }); }
+    status('Selected the JSON. Press copy on your keyboard.');
+  }
+};
+
+if (state.static) take(clone(window.BRAND_DATA));
+else loadBrand(new URLSearchParams(location.search).get('brand') ?? '').catch(() => status('Start the builder with loomiere studio, then open the address it prints.', true));