@palate/cli 0.0.0-stage → 0.0.2

package/src/loop/buttons.mjs

@@ -0,0 +1,413 @@
+// The button language: how a page's actions look, chosen per product from its research, as part of the look.
+// Why: on the Nov 6 benchmark five very different products (a tracing tool, a bakery, a tool library, a pottery
+// studio app, a wedding photographer) got their own ground, type, hero and header, and the same button: a filled
+// box about 48px tall, a 15–16px semi-bold sans label in sentence case, a small radius, a darker ring and a soft
+// contact shadow, beside a bold underlined link. Only the colour and the radius changed, and the look check
+// compared only fill and shape, so it never counted as a repeat. A button is a small thing that carries a lot of
+// a brand's voice (a stamped ticket at a bakery, a keycap in a terminal, a line of display type at a studio).
+//
+// Six axes, a library of named languages as starting points (kb/sections/_buttons.md says when each fits),
+// similarity between two languages (planned or measured), words for both, and the CSS palate generates for the
+// chosen one. The craft (hover, pressed, focus, disabled, contrast, tap area, reduced motion) never changes.
+
+export const BUTTON_AXES = {
+  shape: ["square", "soft", "pill", "none"],
+  fill: ["solid", "outline", "tinted", "underline", "ghost"],
+  size: ["compact", "standard", "large"],
+  label: ["sentence", "upper-tracked", "display", "mono"],
+  adornment: ["none", "arrow", "icon", "detail", "keycap"],
+  secondary: ["text-link", "ghost", "solid", "none", "inline"],
+};
+export const AXIS_NAMES = Object.keys(BUTTON_AXES);
+const BOXLESS = new Set(["underline", "ghost"]);
+
+// The library: starting points, each with the products it fits. A plan names one (and may change an axis or
+// two), or says "custom" and sets all six.
+export const BUTTON_LANGUAGES = {
+  "plain-solid": {
+    shape: "soft", fill: "solid", size: "standard", label: "sentence", adornment: "none", secondary: "text-link",
+    words: "a filled box with a sentence-case label and a text link beside it",
+    fits: "software where the action is routine and nothing in the product's world suggests another; palate's recent pages all used it, so only when the research shows the category's best sites do",
+    tags: ["saas", "software", "b2b"],
+  },
+  "editorial-arrow": {
+    shape: "none", fill: "underline", size: "large", label: "display", adornment: "arrow", secondary: "inline",
+    words: "no box: the action is a line in the display face, underlined, with a trailing arrow; the second action sits inside the copy",
+    fits: "publications, studios, architects, writers, editorial and wedding photography, culture: pages where type is the material",
+    tags: ["editorial", "studio", "portfolio", "photography", "writing", "culture", "architecture", "agency", "museum"],
+  },
+  "stamped-tag": {
+    shape: "square", fill: "outline", size: "standard", label: "upper-tracked", adornment: "detail", secondary: "text-link",
+    words: "a square ticket in ink with a hard offset edge, a small uppercase tracked label and a detail inside (the day, the price, a number)",
+    fits: "bakeries, cafés, markets, local shops, libraries of things, small events: anything sold over a counter or printed on a tag",
+    tags: ["food", "bakery", "cafe", "restaurant", "local", "market", "shop", "library", "community", "events", "print"],
+  },
+  "tracked-outline": {
+    shape: "square", fill: "outline", size: "large", label: "upper-tracked", adornment: "none", secondary: "none",
+    words: "a thin square outline, wide and quiet, with an uppercase tracked label and no second action",
+    fits: "fashion, photography, hotels, galleries, jewellery: the work is loud, the button steps back",
+    tags: ["fashion", "photography", "hotel", "hospitality", "gallery", "luxury", "wedding", "jewellery", "interior"],
+  },
+  "keycap-command": {
+    shape: "soft", fill: "solid", size: "compact", label: "mono", adornment: "keycap", secondary: "ghost",
+    words: "a compact key with a monospace label and a keycap hint (↵, ⌘K) or the command itself; the second action a ghost button",
+    fits: "developer tools, CLIs, tracing and observability, terminals, APIs: the audience lives on the keyboard",
+    tags: ["developer", "dev", "devtools", "cli", "api", "tracing", "observability", "infrastructure", "code", "terminal"],
+  },
+  "oversized-pill": {
+    shape: "pill", fill: "solid", size: "large", label: "display", adornment: "arrow", secondary: "text-link",
+    words: "a big pill in the display face with a trailing arrow",
+    fits: "consumer apps, launches, fitness, playful brands, festivals: one confident action and nothing else",
+    tags: ["consumer", "app", "launch", "playful", "fitness", "music", "festival", "kids", "game"],
+  },
+  "tinted-soft": {
+    shape: "soft", fill: "tinted", size: "standard", label: "sentence", adornment: "icon", secondary: "ghost",
+    words: "a soft tinted button (the accent at low strength, the label in its dark shade) with a leading icon",
+    fits: "community tools, health, education, non-profits, friendly dashboards: inviting, never shouting",
+    tags: ["community", "health", "education", "nonprofit", "charity", "care", "wellbeing", "friendly", "tool"],
+  },
+  "price-in-button": {
+    shape: "soft", fill: "solid", size: "large", label: "sentence", adornment: "detail", secondary: "none",
+    words: "a large solid button that carries the price or the time after a divider (\"Pre-order the box · £18\")",
+    fits: "commerce, booking, pre-orders, tickets, services with a set price: the visitor sees what they agree to",
+    tags: ["commerce", "shop", "booking", "ticket", "preorder", "service", "store", "subscription"],
+  },
+  "poster-block": {
+    shape: "square", fill: "solid", size: "large", label: "upper-tracked", adornment: "none", secondary: "solid",
+    words: "a square block of colour with a bold uppercase label, a second block in ink beside it",
+    fits: "civic campaigns, sport, charities with one urgent ask, festivals, bold posters",
+    tags: ["civic", "sport", "campaign", "charity", "protest", "festival", "poster", "union", "politics"],
+  },
+};
+export const LANGUAGE_NAMES = Object.keys(BUTTON_LANGUAGES);
+
+// The anatomy of a language name plus the plan's own changes: { language, shape, fill, size, label, adornment,
+// secondary } (unknown axes left out). null when nothing is said.
+export function resolveButtons(b) {
+  if (!b) return null;
+  if (typeof b === "string") b = { language: b };
+  if (typeof b !== "object") return null;
+  const base = BUTTON_LANGUAGES[b.language] ?? {};
+  const out = { language: b.language ?? null };
+  for (const a of AXIS_NAMES) {
+    const v = b[a] ?? base[a];
+    if (v != null) out[a] = v;
+  }
+  if (BOXLESS.has(out.fill)) out.shape = "none";
+  return out;
+}
+
+// The blueprint's checks on look.buttons: { problems, warnings }.
+export function buttonProblems(b) {
+  const problems = [];
+  const warnings = [];
+  if (!b || typeof b !== "object") {
+    problems.push(`look.buttons: the page's button language, chosen from the research: { "language": one of ${LANGUAGE_NAMES.join(", ")} or "custom", plus any axis you change (${AXIS_NAMES.join(", ")}), "why" }`);
+    return { problems, warnings };
+  }
+  if (b.language != null && b.language !== "custom" && !BUTTON_LANGUAGES[b.language]) problems.push(`look.buttons.language "${b.language}" isn't in the library: one of ${LANGUAGE_NAMES.join(", ")}, or "custom" with all six axes`);
+  if ((b.language == null || b.language === "custom") && AXIS_NAMES.some((a) => b[a] == null)) problems.push(`look.buttons: a custom language sets all six axes (${AXIS_NAMES.filter((a) => b[a] == null).join(", ")} missing)`);
+  for (const a of AXIS_NAMES) if (b[a] != null && !BUTTON_AXES[a].includes(b[a])) problems.push(`look.buttons.${a} "${b[a]}": one of ${BUTTON_AXES[a].join(", ")}`);
+  const r = resolveButtons(b);
+  if (b.shape === "none" && r.fill && !BOXLESS.has(r.fill)) problems.push(`look.buttons: shape none has no box, so the fill can't be ${r.fill} (use underline or ghost, or give it a shape)`);
+  if (b.shape && b.shape !== "none" && BOXLESS.has(r.fill)) warnings.push(`look.buttons: a ${r.fill} button has no box, so shape ${b.shape} is ignored`);
+  if (!b.why) warnings.push("look.buttons.why: which research reference or product truth the buttons come from");
+  return { problems, warnings };
+}
+
+// The coarse call-to-action class (lookvec's cta axis) of a language, and a partial language from a cta.
+export function ctaOf(b) {
+  const r = resolveButtons(b);
+  if (!r?.fill) return null;
+  if (BOXLESS.has(r.fill)) return "text-link";
+  if (r.fill === "outline") return "outline";
+  return r.shape === "pill" ? "solid-pill" : r.shape === "square" ? "solid-square" : "solid-rounded";
+}
+export function buttonsFromCta(cta, secondary) {
+  const style = cta?.style ?? cta;
+  const sec = { "underlined-link": "text-link", "text-link": "text-link", ghost: "ghost", solid: "solid", none: "none" }[cta?.secondary ?? secondary];
+  const base =
+    {
+      "solid-rounded": { shape: "soft", fill: "solid" },
+      "solid-pill": { shape: "pill", fill: "solid" },
+      "solid-square": { shape: "square", fill: "solid" },
+      gradient: { fill: "solid" },
+      outline: { fill: "outline" },
+      "outline-pill": { shape: "pill", fill: "outline" },
+      "text-link": { shape: "none", fill: "underline" },
+    }[style] ?? null;
+  if (!base) return null;
+  return { ...base, ...(sec ? { secondary: sec } : {}), derived: true };
+}
+
+// ---- similarity: weighted axes, near values half, the choices nearly every button makes half (two buttons with
+// sentence-case labels and no adornment say less), and for two measured buttons, how close their finish is
+// (height, radius as a share of height, label size, weight and tracking).
+// Shape weighs least: the five benchmark pages changed their radius and kept the same button (soft and square
+// are close; a pill is further).
+export const BUTTON_WEIGHTS = { shape: 0.75, fill: 1.5, size: 1, label: 1.5, adornment: 0.75, secondary: 0.75 };
+const BUTTON_NEAR = new Set(
+  [
+    ["shape", "soft", "pill"],
+    ["fill", "solid", "tinted"],
+    ["fill", "outline", "ghost"],
+    ["fill", "underline", "ghost"],
+    ["size", "compact", "standard"],
+    ["size", "standard", "large"],
+    ["adornment", "arrow", "icon"],
+    ["adornment", "arrow", "none"],
+    ["secondary", "text-link", "inline"],
+    ["secondary", "ghost", "none"],
+  ].flatMap(([a, x, y]) => [`${a}:${x}:${y}`, `${a}:${y}:${x}`]),
+);
+export const BUTTON_COMMON = { label: ["sentence"], adornment: ["none"] };
+export const COMMON_BUTTON_CREDIT = 0.75;
+// Pairs that are nearly the same: three quarters.
+const BUTTON_CLOSE = new Set(["shape:soft:square", "shape:square:soft"]);
+const ok = (x) => x != null && x !== "unknown";
+// Axes both languages state.
+export const comparableButtonAxes = (a, b) => AXIS_NAMES.filter((k) => ok(a?.[k]) && ok(b?.[k]));
+const finishScore = (a, b) => {
+  const fa = a?.finish, fb = b?.finish;
+  if (!fa || !fb) return null;
+  const close = (x, y, span) => (x == null || y == null ? null : Math.max(0, 1 - Math.abs(x - y) / span));
+  // The edge (a ring, a contact shadow, both, none): the benchmark button's darker ring and soft shadow are half of
+  // what makes it one button; a shared part counts half.
+  const edges = (e) => new Set(String(e).split("+").filter((x) => x && x !== "none"));
+  const edge = fa.edge == null || fb.edge == null ? null : (() => {
+    const [x, y] = [edges(fa.edge), edges(fb.edge)];
+    if (!x.size && !y.size) return 1;
+    const shared = [...x].filter((k) => y.has(k)).length;
+    return shared / Math.max(x.size, y.size);
+  })();
+  const parts = [close(fa.h, fb.h, 12), close(fa.radiusShare, fb.radiusShare, 0.25), close(fa.px, fb.px, 4), close(fa.weight, fb.weight, 200), close(fa.tracking, fb.tracking, 0.08), edge].filter((x) => x != null);
+  return parts.length ? parts.reduce((x, y) => x + y, 0) / parts.length : null;
+};
+export const FINISH_SHARE = 0.4;
+
+// { score 0–1, same: axes equal, near: axes close, axes: comparable count, parts }.
+export function buttonSimilarity(a, b) {
+  const [x, y] = [a?.language && !a.shape ? resolveButtons(a) : a, b?.language && !b.shape ? resolveButtons(b) : b];
+  let sum = 0, weight = 0;
+  const same = [], near = [], parts = {};
+  for (const k of comparableButtonAxes(x, y)) {
+    const w = BUTTON_WEIGHTS[k];
+    let s = 0;
+    if (x[k] === y[k]) s = BUTTON_COMMON[k]?.includes(x[k]) ? COMMON_BUTTON_CREDIT : 1;
+    else if (BUTTON_CLOSE.has(`${k}:${x[k]}:${y[k]}`)) s = 0.75;
+    else if (BUTTON_NEAR.has(`${k}:${x[k]}:${y[k]}`)) s = 0.5;
+    if (x[k] === y[k]) same.push(k);
+    else if (s > 0) near.push(k);
+    parts[k] = s;
+    sum += w * s;
+    weight += w;
+  }
+  if (!weight) return { score: 0, same, near, axes: 0, parts };
+  let score = sum / weight;
+  const f = finishScore(x, y);
+  if (f != null) {
+    parts.finish = +f.toFixed(2);
+    score = (1 - FINISH_SHARE) * score + FINISH_SHARE * f;
+  }
+  return { score: +score.toFixed(3), same, near, axes: comparableButtonAxes(x, y).length, parts };
+}
+
+// ---- words
+const SHAPE_W = { square: "square", soft: "soft-cornered", pill: "pill", none: "boxless" };
+const FILL_W = { solid: "solid", outline: "outline", tinted: "tinted", underline: "underlined text", ghost: "ghost" };
+const SIZE_W = { compact: "compact", standard: "standard", large: "large" };
+const LABEL_W = { sentence: "sentence case", "upper-tracked": "uppercase tracked", display: "in the display face", mono: "monospace" };
+const ADORN_W = { none: "", arrow: ", trailing arrow", icon: ", leading icon", detail: ", a detail inside", keycap: ", a keycap" };
+const SEC_W = { "text-link": ", with a text link", ghost: ", with a ghost button", solid: ", with a second solid", none: ", no second action", inline: ", with a link in the copy", underlined: ", with an underlined link" };
+const WEIGHT_W = (w) => (w == null ? "" : w >= 700 ? "bold" : w >= 600 ? "semi-bold" : w >= 500 ? "medium" : w <= 350 ? "light" : "regular");
+
+// A planned language in words: "stamped-tag: square outline, standard, uppercase tracked, a detail inside, with a text link".
+export function describeButtons(b) {
+  if (!b) return "";
+  if (b.finish) return describeMeasuredButtons(b);
+  const r = b.language && !b.shape ? resolveButtons(b) : b;
+  const box = r.fill && BOXLESS.has(r.fill) ? FILL_W[r.fill] : [SHAPE_W[r.shape], FILL_W[r.fill]].filter(Boolean).join(" ");
+  const body = [box, SIZE_W[r.size], LABEL_W[r.label]].filter(Boolean).join(", ") + (ADORN_W[r.adornment] ?? "") + (SEC_W[r.secondary] ?? "");
+  return `${r.language && r.language !== "custom" && !r.derived ? `${r.language}: ` : ""}${body}`;
+}
+// A measured button in words: "48px solid, 16px semi-bold sentence case, small radius, with an underlined link".
+export function describeMeasuredButtons(b) {
+  const f = b.finish ?? {};
+  const radius = b.shape === "none" ? null : b.shape === "pill" ? "pill" : b.shape === "square" ? "square corners" : (f.radiusShare ?? 0) < 0.2 ? "small radius" : "rounded";
+  const box = BOXLESS.has(b.fill) ? `${FILL_W[b.fill]} (no box)` : `${f.h ? `${f.h}px ` : ""}${FILL_W[b.fill] ?? b.fill}`;
+  const label = `${f.px ? `${f.px}px ` : ""}${[WEIGHT_W(f.weight), LABEL_W[b.label] ?? b.label].filter(Boolean).join(" ")}`;
+  const sec = b.secondary === "text-link" && f.secondaryUnderlined ? SEC_W.underlined : SEC_W[b.secondary] ?? "";
+  return [box, label, radius].filter(Boolean).join(", ") + (ADORN_W[b.adornment] ?? "") + sec;
+}
+
+// Library languages that differ from b on most axes, best fit first for the product's tags.
+export function otherLanguages(b, { tags = [], limit = 2 } = {}) {
+  const t = new Set(tags.map((x) => String(x).toLowerCase()));
+  return LANGUAGE_NAMES.filter((n) => n !== b?.language)
+    .map((n) => ({ n, sim: buttonSimilarity(resolveButtons(n), b ?? {}).score, fit: BUTTON_LANGUAGES[n].tags.filter((x) => t.has(x)).length }))
+    .filter((x) => x.sim < 0.55)
+    .sort((x, y) => y.fit - x.fit || x.sim - y.sim)
+    .slice(0, limit)
+    .map((x) => x.n);
+}
+// The library ranked for a product's tags (for the blueprint brief).
+export function rankLanguages(tags = []) {
+  const t = new Set(tags.map((x) => String(x).toLowerCase()));
+  // plain-solid last: it is the habit this library exists to break.
+  return LANGUAGE_NAMES.map((n) => ({ n, fit: n === "plain-solid" ? -1 : BUTTON_LANGUAGES[n].tags.filter((x) => t.has(x)).length })).sort((a, b) => b.fit - a.fit).map((x) => x.n);
+}
+
+// ---- the CSS for a language. c: the blueprint's colours. Craft stays constant: hover, pressed, focus-visible,
+// disabled, a label at 4.5:1 or more on its fill, a tap target of at least 44px, motion off when reduced.
+const hexRgb = (h) => (h && /^#[0-9a-f]{6}$/i.test(h) ? [1, 3, 5].map((i) => parseInt(h.slice(i, i + 2), 16)) : null);
+const rgbHex = (rgb) => "#" + rgb.map((v) => Math.max(0, Math.min(255, Math.round(v))).toString(16).padStart(2, "0")).join("");
+const mix = (a, b, t) => {
+  const [x, y] = [hexRgb(a), hexRgb(b)];
+  return x && y ? rgbHex(x.map((v, i) => v + (y[i] - v) * t)) : a;
+};
+const relLum = (rgb) => {
+  const [r, g, b] = rgb.map((v) => {
+    const c = v / 255;
+    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  });
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+};
+export function contrastOf(a, b) {
+  const [x, y] = [hexRgb(a), hexRgb(b)];
+  if (!x || !y) return null;
+  const [l1, l2] = [relLum(x), relLum(y)].sort((p, q) => q - p);
+  return +((l1 + 0.05) / (l2 + 0.05)).toFixed(2);
+}
+// The first colour that reads at min:1 on the ground, else the better of black and white.
+export function readable(candidates, ground, min = 4.5) {
+  for (const c of candidates.filter((x) => hexRgb(x))) if (contrastOf(c, ground) >= min) return c;
+  return contrastOf("#000000", ground) >= contrastOf("#ffffff", ground) ? "#000000" : "#ffffff";
+}
+export const SIZES = { compact: { h: 36, px: 14, pad: 14 }, standard: { h: 44, px: 15, pad: 20 }, large: { h: 56, px: 17, pad: 28 } };
+export const TAP = 44;
+
+// opts.rules: the user's rule texts; they win over the language (no pills, no uppercase, no gradients…).
+export function buttonCss(buttons, c = {}, { rules = [] } = {}) {
+  const r = resolveButtons(buttons) ?? resolveButtons("plain-solid");
+  const notes = [];
+  const said = (re) => rules.some((x) => re.test(x) && /button|cta|action/i.test(x) && /\b(no|never|avoid|don'?t|without)\b/i.test(x));
+  if (r.shape === "pill" && said(/pill/i)) (r.shape = "soft"), notes.push("pill → soft (your rule)");
+  if (r.label === "upper-tracked" && said(/upper ?case|all caps|caps/i)) (r.label = "sentence"), notes.push("uppercase → sentence case (your rule)");
+  if (r.fill === "outline" && said(/outline|ghost/i)) (r.fill = "solid"), notes.push("outline → solid (your rule)");
+  if (r.adornment === "arrow" && said(/arrow/i)) (r.adornment = "none"), notes.push("no arrow (your rule)");
+  const size = SIZES[r.size] ?? SIZES.standard;
+  const bg = c.bg ?? "#ffffff";
+  const ink = c.ink ?? "#111111";
+  const accent = c.accent ?? ink;
+  const onAccent = readable([c["on-accent"], "#ffffff", ink], accent);
+  // Text actions and outlines: the accent when it reads on the ground, else a darker (or lighter) accent, else ink.
+  const dark = (contrastOf(ink, "#ffffff") ?? 21) > (contrastOf(ink, "#000000") ?? 1);
+  const toward = dark ? "#000000" : "#ffffff";
+  const lineInk = readable([accent, mix(accent, toward, 0.25), mix(accent, toward, 0.45), ink], bg);
+  const tint = mix(accent, bg, 0.86);
+  const tintInk = readable([mix(accent, toward, 0.35), mix(accent, toward, 0.55), ink], tint);
+  const boxless = BOXLESS.has(r.fill);
+  const radius = r.shape === "pill" ? "999px" : r.shape === "square" ? "2px" : r.shape === "soft" ? `${Math.round(size.h * 0.2)}px` : "0";
+  const font =
+    r.label === "upper-tracked" ? `600 ${size.px - 2}px/1 var(--font-body)` : r.label === "display" ? `${r.size === "large" ? 500 : 500} ${size.px + (boxless ? 5 : 2)}px/1.1 var(--font-display)` : r.label === "mono" ? `500 ${size.px - 1}px/1 var(--font-mono, ui-monospace, SFMono-Regular, Menlo, monospace)` : `500 ${size.px}px/1 var(--font-body)`;
+  const tracking = r.label === "upper-tracked" ? "0.09em" : r.label === "display" ? "-0.01em" : "0";
+  const lbl = r.fill === "solid" ? onAccent : r.fill === "tinted" ? tintInk : lineInk;
+  const ground = r.fill === "solid" ? accent : r.fill === "tinted" ? tint : bg;
+  const ratio = contrastOf(lbl, ground);
+  const L = [];
+  L.push(`/* The page's button language: ${describeButtons(r)}${notes.length ? ` (${notes.join("; ")})` : ""}.`);
+  L.push(`   Label ${lbl} on ${ground}: ${ratio}:1. Generated from blueprint.json's look.buttons; change the plan, not this block. */`);
+  L.push(":root {");
+  L.push(`  --btn-h: ${size.h}px;`);
+  L.push(`  --btn-pad: ${boxless ? 0 : size.pad}px;`);
+  L.push(`  --btn-radius: ${radius};`);
+  L.push(`  --btn-font: ${font};`);
+  L.push(`  --btn-tracking: ${tracking};`);
+  L.push(`  --btn-label: ${lbl};`);
+  L.push("}");
+  L.push(":is(.btn, .btn-primary, .btn-secondary) {");
+  L.push("  position: relative; display: inline-flex; align-items: center; justify-content: center; gap: 0.5em;");
+  L.push(`  min-height: ${boxless ? `${TAP}px` : "var(--btn-h)"}; padding-inline: var(--btn-pad); border: 0; border-radius: var(--btn-radius);`);
+  L.push(`  font: var(--btn-font); letter-spacing: var(--btn-tracking);${r.label === "upper-tracked" ? " text-transform: uppercase;" : ""}`);
+  L.push("  text-decoration: none; white-space: nowrap; cursor: pointer; -webkit-tap-highlight-color: transparent;");
+  L.push("  transition: transform 160ms cubic-bezier(.23,1,.32,1), background-color 160ms ease, box-shadow 160ms ease, color 160ms ease, text-decoration-color 160ms ease;");
+  L.push("}");
+  // A compact box is under 44px: its hit area grows with a pseudo-element, not its look.
+  if (!boxless && size.h < TAP) L.push(`:is(.btn, .btn-primary, .btn-secondary)::after { content: ""; position: absolute; inset: ${-(TAP - size.h) / 2}px -4px; }  /* tap target ${TAP}px */`);
+  // Primary, by fill.
+  if (r.fill === "solid") {
+    L.push(`.btn-primary { background: var(--color-accent, ${accent}); color: ${onAccent === c["on-accent"] ? `var(--color-on-accent, ${onAccent})` : onAccent}; }`);
+    // Hover moves the fill away from its label, so the label never loses contrast.
+    const lift = (contrastOf(onAccent, "#ffffff") ?? 1) < (contrastOf(onAccent, "#000000") ?? 1) ? "#000000" : "#ffffff";
+    L.push(`.btn-primary:hover { background: ${mix(accent, lift, 0.08)}; }`);
+    L.push(`.btn-primary:active { transform: translateY(1px); background: ${mix(accent, lift, 0.14)}; }`);
+  } else if (r.fill === "tinted") {
+    L.push(`.btn-primary { background: ${tint}; color: ${tintInk}; }`);
+    L.push(`.btn-primary:hover { background: ${mix(accent, bg, 0.78)}; }`);
+    L.push(`.btn-primary:active { transform: translateY(1px); background: ${mix(accent, bg, 0.7)}; }`);
+  } else if (r.fill === "outline") {
+    L.push(`.btn-primary { background: transparent; color: ${lineInk}; box-shadow: inset 0 0 0 ${r.adornment === "detail" || r.label === "upper-tracked" ? "1.5px" : "1px"} currentColor; }`);
+    L.push(`.btn-primary:hover { background: ${mix(lineInk, bg, 0.92)}; }`);
+    L.push(`.btn-primary:active { transform: translateY(1px); background: ${mix(lineInk, bg, 0.86)}; }`);
+  } else if (r.fill === "underline") {
+    L.push(`.btn-primary { color: ${lineInk}; text-decoration: underline; text-decoration-thickness: 1px; text-underline-offset: 0.22em; }`);
+    L.push(".btn-primary:hover { text-decoration-thickness: 2px; }");
+    L.push(".btn-primary:active { transform: translateY(1px); }");
+  } else {
+    L.push(`.btn-primary { color: ${lineInk}; padding-inline: 12px; }`);
+    L.push(`.btn-primary:hover { background: ${mix(ink, bg, 0.93)}; }`);
+    L.push(".btn-primary:active { transform: translateY(1px); }");
+  }
+  // The stamped ticket: a hard offset edge that the press closes.
+  if (r.shape === "square" && r.fill === "outline" && r.adornment === "detail") {
+    L.push(`.btn-primary { box-shadow: inset 0 0 0 1.5px currentColor, 3px 3px 0 0 currentColor; }`);
+    L.push(".btn-primary:active { transform: translate(3px, 3px); box-shadow: inset 0 0 0 1.5px currentColor, 0 0 0 0 currentColor; }");
+  }
+  // A key: a darker bottom edge that the press flattens.
+  if (r.adornment === "keycap" && r.fill === "solid") {
+    L.push(`.btn-primary { box-shadow: inset 0 -2px 0 ${mix(accent, "#000000", 0.3)}; }`);
+    L.push(`.btn-primary:active { box-shadow: inset 0 0 0 ${mix(accent, "#000000", 0.3)}; transform: translateY(1px); }`);
+  }
+  // Secondary, by the language's second action.
+  const sec = r.secondary ?? "text-link";
+  const secInk = readable([ink], bg);
+  if (sec === "solid") {
+    L.push(`.btn-secondary { background: ${ink}; color: ${readable([bg, "#ffffff", "#000000"], ink)}; }`);
+    L.push(`.btn-secondary:hover { background: ${mix(ink, bg, 0.12)}; }`);
+    L.push(".btn-secondary:active { transform: translateY(1px); }");
+  } else if (sec === "ghost") {
+    L.push(`.btn-secondary { background: transparent; color: ${secInk}; box-shadow: inset 0 0 0 1px ${mix(ink, bg, 0.75)}; }`);
+    L.push(`.btn-secondary:hover { background: ${mix(ink, bg, 0.94)}; }`);
+    L.push(".btn-secondary:active { transform: translateY(1px); }");
+  } else {
+    // A text link (or the language has none and a section still needs one): no box, a hit area of 44px.
+    L.push(`.btn-secondary { min-height: ${TAP}px; padding-inline: 0; background: none; color: ${secInk}; font: 500 ${size.px}px/1.2 var(--font-body); letter-spacing: 0; text-transform: none; text-decoration: underline; text-decoration-thickness: 1px; text-underline-offset: 0.22em; text-decoration-color: ${mix(ink, bg, 0.5)}; }`);
+    L.push(".btn-secondary:hover { text-decoration-color: currentColor; }");
+    if (sec === "inline") L.push(".btn-secondary.is-inline, p .btn-secondary { display: inline; min-height: 0; font: inherit; }  /* inside the copy: the sentence carries it */");
+  }
+  // Adornment hooks: markup the builder adds when the language asks.
+  L.push(".btn-arrow { display: inline-block; transition: transform 160ms cubic-bezier(.23,1,.32,1); }");
+  L.push(":is(.btn, .btn-primary, .btn-secondary):hover .btn-arrow { transform: translateX(3px); }");
+  L.push(".btn-icon { width: 1.1em; height: 1.1em; flex: none; }");
+  L.push(".btn-detail { font-variant-numeric: tabular-nums; padding-left: 0.75em; margin-left: 0.25em; border-left: 1px solid color-mix(in oklab, currentColor 35%, transparent); }");
+  L.push(".btn-key, :is(.btn, .btn-primary) kbd { font: 500 0.8em/1 var(--font-mono, ui-monospace, monospace); padding: 0.25em 0.45em; border-radius: 4px; background: color-mix(in oklab, currentColor 14%, transparent); }");
+  // Craft that never changes.
+  L.push(`:is(.btn, .btn-primary, .btn-secondary):focus-visible { outline: 2px solid ${readable([accent, ink], bg, 3)}; outline-offset: ${boxless ? 4 : 2}px; }`);
+  L.push(':is(.btn, .btn-primary, .btn-secondary):is([disabled], [aria-disabled="true"]) { opacity: 0.5; cursor: not-allowed; transform: none; }');
+  L.push("@media (prefers-reduced-motion: reduce) { :is(.btn, .btn-primary, .btn-secondary, .btn-arrow) { transition: none; } :is(.btn, .btn-primary, .btn-secondary):active, :is(.btn, .btn-primary, .btn-secondary):hover .btn-arrow { transform: none; } }");
+  return { css: L.join("\n"), language: r, label: lbl, ground, ratio, notes };
+}
+
+// How to write the markup for a language's adornment (for the build briefs).
+export function markupHint(b) {
+  const r = resolveButtons(b);
+  if (!r) return "";
+  const hint = {
+    arrow: '<a class="btn-primary" href="…">See the spring menu <span class="btn-arrow" aria-hidden="true">→</span></a>',
+    icon: '<a class="btn-primary" href="…"><svg class="btn-icon" aria-hidden="true">…</svg>Join the Thursday session</a>',
+    detail: '<a class="btn-primary" href="…">Pre-order the box <span class="btn-detail">Sat · £18</span></a>',
+    keycap: '<a class="btn-primary" href="…">Start tracing <kbd aria-hidden="true">↵</kbd></a>',
+    none: '<a class="btn-primary" href="…">Book the walkthrough</a>',
+  }[r.adornment ?? "none"];
+  return `${hint}${r.secondary && r.secondary !== "none" ? ` · second action: \`.btn-secondary\` (${{ "text-link": "a text link", ghost: "a ghost button", solid: "a second solid in ink", inline: "a link inside the sentence" }[r.secondary]})` : " · no second action beside it"}`;
+}

package/src/loop/common.mjs

@@ -0,0 +1,206 @@
+// Shared pieces of the design loop (variants → judge → pick → polish): where a loop's files live, which
+// routes are its variants, rendering them all with one dev server, and the user's taste log.
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { PALATE_HOME } from "../catalog/store.mjs";
+import { HIDE_DEV, routeFile } from "../look.mjs";
+import { acquireBrowser, acquireServer } from "../pool.mjs";
+import { normalizeRoute } from "../shoot.mjs";
+import { loopOfRoute, loopTimeline, mark } from "./timeline.mjs";
+import { activeRules, measureRules } from "./rules.mjs";
+
+export const TASTE_DIR = path.join(PALATE_HOME, "taste");
+const fingerprintScript = fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "page-fingerprint.js"), "utf8").trim().replace(/;\s*$/, "");
+
+export function sessionDir(dir, name) {
+  const d = path.join(dir, ".palate", "variants", name);
+  fs.mkdirSync(d, { recursive: true });
+  fs.writeFileSync(path.join(dir, ".palate", ".gitignore"), "*\n");
+  return d;
+}
+
+export const readJson = (f, fallback) => {
+  try {
+    return JSON.parse(fs.readFileSync(f, "utf8"));
+  } catch {
+    return fallback;
+  }
+};
+
+// Variants of a loop are routes named <name>-<direction letter><number>, e.g. pricing-a1, pricing-b2: either a
+// route file (src/routes/pricing-a1.tsx, pages/pricing-a1.vue …) or a route folder (app/pricing-a1/page.tsx,
+// src/routes/pricing-a1/+page.svelte …).
+export function variantRoutes(dir, name) {
+  const roots = ["src/routes", "src/pages", "src/app", "app", "pages", "app/routes"].map((r) => path.join(dir, r)).filter((r) => fs.existsSync(r));
+  const esc = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const fileRe = new RegExp(`^${esc}-([a-z]\\d+)\\.(tsx|jsx|ts|js|vue|svelte|astro)$`);
+  const dirRe = new RegExp(`^${esc}-([a-z]\\d+)$`);
+  const pageRe = /^(\+?page|index|route)\.(tsx|jsx|ts|js|vue|svelte|astro)$/;
+  const found = new Set();
+  for (const r of roots)
+    for (const e of fs.readdirSync(r, { withFileTypes: true })) {
+      if (e.isFile() && fileRe.test(e.name)) found.add(`/${e.name.replace(/\.[a-z]+$/, "")}`);
+      if (e.isDirectory() && dirRe.test(e.name) && fs.readdirSync(path.join(r, e.name)).some((f) => pageRe.test(f))) found.add(`/${e.name}`);
+    }
+  return [...found].sort();
+}
+
+// Marketing sections are judged as a whole section; app screens and heroes on the first screen.
+export function screenKind(name, job = "") {
+  const t = `${name} ${job}`.toLowerCase();
+  if (/\bhero\b/.test(t)) return { kind: "hero", full: false };
+  if (/pricing|features?|section|testimonial|faq|footer|cta|landing/.test(t)) return { kind: "marketing", full: true };
+  return { kind: "app", full: false };
+}
+
+// The newest modification time of the files that make up a route (its file, or every file in its folder).
+export function routeMtime(dir, route) {
+  const found = routeFile(dir, route);
+  if (!found) return null;
+  const folder = path.dirname(found.file);
+  const own = folder !== found.root && path.basename(folder) === route.replace(/^\//, "").split("/").pop();
+  const files = own ? walkFiles(folder) : [found.file];
+  return Math.max(...files.map((f) => fs.statSync(f).mtimeMs));
+}
+const walkFiles = (d) => fs.readdirSync(d, { withFileTypes: true }).flatMap((e) => (e.isDirectory() ? walkFiles(path.join(d, e.name)) : [path.join(d, e.name)]));
+const slugFile = (outDir, route) => path.join(outDir, `${route.replace(/^\//, "").replace(/[^a-z0-9-]+/gi, "-")}.png`);
+
+// A render made earlier (by judge, for pick) that is still current: same settings, route files unchanged since.
+function cached(dir, route, dirs, full) {
+  const mtime = routeMtime(dir, route);
+  if (mtime == null) return null;
+  for (const d of dirs) {
+    const file = slugFile(d, route);
+    const info = readJson(file.replace(/\.png$/, ".render.json"), null);
+    if (!info || info.full !== full || !fs.existsSync(file) || mtime > info.mtime) continue;
+    const fp = readJson(file.replace(/\.png$/, ".fp.json"), null)?.fp ?? null;
+    return { route, file, fp, cached: true };
+  }
+  return null;
+}
+
+// Loads a route like a reader would see it. A dev server may reload once while it optimises dependencies;
+// then it waits for the reload instead of loading twice every time.
+async function load(page, url) {
+  let navs = 0;
+  page.on("framenavigated", (f) => f === page.mainFrame() && navs++);
+  const res = await page.goto(url, { waitUntil: "networkidle", timeout: 60_000 }).catch(() => null);
+  await page.waitForTimeout(600);
+  if (navs > 1) {
+    await page.waitForLoadState("networkidle", { timeout: 30_000 }).catch(() => {});
+    await page.waitForTimeout(600);
+  }
+  return res;
+}
+
+// Renders every route the same way (1440 wide) into outDir/<slug>.png, three at a time in one browser.
+// Reports routes that fail to build. Each page's fingerprint (skeleton, first-screen shape, type and
+// colour) is kept in outDir/<slug>.fp.json for the layout memory. reuse: folders whose renders may stand
+// in when the route's files haven't changed since (pick reuses judge's).
+// rules: also measure the facts the user's rules read (outDir/<slug>.facts.json), for the judge.
+export async function render(dir, routes, outDir, { full = false, url, reuse = [], concurrency = 3, rules = false } = {}) {
+  const ruleList = rules ? activeRules() : [];
+  fs.mkdirSync(outDir, { recursive: true });
+  const out = new Array(routes.length);
+  const todo = [];
+  routes.forEach((raw, i) => {
+    const route = normalizeRoute(raw);
+    const hit = reuse.length ? cached(dir, route, reuse, full) : null;
+    if (hit) out[i] = hit;
+    else todo.push([i, route]);
+  });
+  if (!todo.length) return out;
+  const server = await acquireServer(dir, { url });
+  const { browser, release } = await acquireBrowser();
+  const one = async ([i, route]) => {
+    const mtime = routeMtime(dir, route);
+    // Reduced motion, so judge and picker see each page's finished state rather than an animation caught mid-play.
+    const page = await browser.newPage({ viewport: { width: 1440, height: 900 }, reducedMotion: "reduce" });
+    try {
+      await page.addInitScript(HIDE_DEV);
+      const res = await load(page, server.base + route);
+      const broken =
+        (await page.evaluate(() => document.querySelector("vite-error-overlay")?.shadowRoot?.querySelector(".message")?.textContent ?? null).catch(() => null)) ??
+        (res && res.status() >= 500 ? `the page returned ${res.status()} (a build or runtime error)` : null);
+      const file = slugFile(outDir, route);
+      if (broken) return (out[i] = { route, error: broken.trim().slice(0, 200) });
+      const fp = await page.evaluate(`(${fingerprintScript})()`).catch(() => null);
+      if (fp) fs.writeFileSync(file.replace(/\.png$/, ".fp.json"), JSON.stringify({ route, fp }));
+      if (ruleList.length) {
+        const m = await measureRules(page, ruleList).catch(() => null);
+        if (m) fs.writeFileSync(file.replace(/\.png$/, ".facts.json"), JSON.stringify({ route, facts: m.facts }));
+      }
+      if (full) {
+        const h = await page.evaluate(() => Math.min(document.documentElement.scrollHeight, 2400));
+        await page.setViewportSize({ width: 1440, height: Math.max(900, h) });
+        await page.waitForTimeout(300);
+      }
+      await page.screenshot({ path: file });
+      fs.writeFileSync(file.replace(/\.png$/, ".render.json"), JSON.stringify({ route, full, mtime, at: new Date().toISOString() }));
+      const loop = loopOfRoute(dir, route);
+      if (loop) mark(dir, loop, "first_render", { route });
+      out[i] = { route, file, fp };
+    } finally {
+      await page.close().catch(() => {});
+    }
+  };
+  try {
+    const queue = [...todo];
+    await Promise.all(Array.from({ length: Math.min(concurrency, queue.length) }, async () => {
+      while (queue.length) {
+        const item = queue.shift();
+        await one(item).catch((e) => (out[item[0]] = { route: item[1], error: String(e.message).slice(0, 200) }));
+      }
+    }));
+  } finally {
+    await release();
+    server.stop();
+  }
+  return out.filter(Boolean);
+}
+
+// Waits until `n` of the loop's variants are built: the route exists, its files have settled (unchanged
+// for 15s after its builder's shoot, or 60s if it never shot), and it answers without an error. Returns
+// the ready routes in the order they became ready; with fewer than n after `timeout`, whatever is ready
+// (at least two). Every route seen ready is logged to the loop's timeline.
+export async function waitReady(dir, name, n, { url, timeout = 30 * 60_000, poll = 4000, log = (s) => console.error(s) } = {}) {
+  const server = await acquireServer(dir, { url });
+  const ready = [];
+  const until = Date.now() + timeout;
+  const isVary = Boolean(readJson(path.join(sessionDir(dir, name), "loop.json"), {})?.vary);
+  let said = "";
+  try {
+    for (;;) {
+      const shotRoutes = new Set(Object.keys(loopTimeline(dir, name)?.shot ?? {}));
+      const routes = variantRoutes(dir, name).filter((r) => !ready.includes(r));
+      for (const r of routes) {
+        const m = routeMtime(dir, r);
+        if (m == null || Date.now() - m < (shotRoutes.has(r) ? 15_000 : 60_000)) continue;
+        // vary starts each route as an exact copy of the page; it is built only once its builder marks the new section.
+        const rf = isVary ? routeFile(dir, r)?.file : null;
+        // The attribute on a JSX/HTML tag, not the copy's header comment that mentions it.
+        if (isVary && !(rf && /<[a-z][\w.-]*\b[^<>]*\sdata-palate-vary\b/i.test(fs.readFileSync(rf, "utf8")))) continue;
+        const res = await fetch(server.base + r, { signal: AbortSignal.timeout(90_000) }).catch(() => null);
+        if (!res || res.status >= 400) continue;
+        ready.push(r);
+        mark(dir, name, "ready", { route: r });
+      }
+      const status = `${ready.length} of ${n} variants ready${ready.length ? `: ${ready.join(", ")}` : ""}`;
+      if (status !== said) log((said = status));
+      if (ready.length >= n) return ready;
+      if (Date.now() > until) {
+        if (ready.length >= 2) return ready;
+        throw new Error(`Only ${ready.length} variant(s) of "${name}" were ready after ${Math.round(timeout / 60000)} min.`);
+      }
+      await new Promise((r) => setTimeout(r, poll));
+    }
+  } finally {
+    server.stop();
+  }
+}
+
+export function appendTaste(record) {
+  fs.mkdirSync(TASTE_DIR, { recursive: true });
+  fs.appendFileSync(path.join(TASTE_DIR, "picks.jsonl"), JSON.stringify({ ...record, at: new Date().toISOString() }) + "\n");
+}