@palate/cli 0.0.0-stage → 0.0.1

package/src/shoot.mjs

@@ -0,0 +1,235 @@
+// `palate shoot <route>`: render the page, screenshot it at each width, and report what is measurably off,
+// so the agent can look at its own work and fix it. Starts the project's dev server (any common stack)
+// unless --url is given.
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { acquireBrowser, acquireServer } from "./pool.mjs";
+import { measurePrinciples, principlesReport } from "./principles.mjs";
+import { loopOfRoute, mark } from "./loop/timeline.mjs";
+import { MOTION_INIT, scrollThrough, shootFull } from "./look.mjs";
+import { activeRules, appliesTo, checkRules, measureRules, projectOf, routeTags, rulesReport, statesFactsFor } from "./loop/rules.mjs";
+
+export { freePort, kill, waitFor } from "./devserver.mjs";
+export { launch } from "./pool.mjs";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const metricsScript = fs.readFileSync(path.join(here, "page-metrics.js"), "utf8").trim().replace(/;\s*$/, "");
+const fingerprintScript = fs.readFileSync(path.join(here, "page-fingerprint.js"), "utf8").trim().replace(/;\s*$/, "");
+const axePath = createRequire(import.meta.url).resolve("axe-core/axe.min.js");
+
+// Git Bash on Windows rewrites "/team" to "C:/Program Files/Git/team" (and "/m/today" to "M:/today"). A route
+// never starts with a drive, so a value like that is refused with what to do, before it is stored anywhere
+// (research, direction and blueprint JSON keep the route). "//team" (Git Bash's escape) and "team" are accepted.
+export const ROUTE_IS_PATH = 'That route looks like a file path (Git Bash rewrites "/"): pass //, or set MSYS_NO_PATHCONV=1';
+export const looksLikePath = (raw) => /^([A-Za-z]:([\\/]|$)|\\\\)/.test(String(raw ?? "").trim());
+export function normalizeRoute(raw) {
+  const s = String(raw ?? "").trim();
+  if (looksLikePath(s)) throw new Error(`${ROUTE_IS_PATH} (got "${s}").`);
+  const r = s.replace(/\\/g, "/").replace(/\/{2,}/g, "/");
+  return r.startsWith("/") ? r : `/${r}`;
+}
+
+async function resolveReference(ref) {
+  if (fs.existsSync(ref)) return ref;
+  const { allRecords, fetchImage } = await import("./refs.mjs");
+  const record = allRecords().find((r) => r.id === ref);
+  return record ? fetchImage(record) : undefined;
+}
+
+async function sideBySide(browser, ours, theirs, out, label) {
+  const uri = (f) => `data:image/${/\.jpe?g$/i.test(f) ? "jpeg" : /\.webp$/i.test(f) ? "webp" : "png"};base64,${fs.readFileSync(f).toString("base64")}`;
+  const page = await browser.newPage({ viewport: { width: 1600, height: 600 } });
+  await page.setContent(`<!doctype html><body style="margin:0;background:#eee;font:14px system-ui">
+    <div id="w" style="display:inline-flex;gap:16px;padding:16px">
+      <figure style="margin:0;width:760px"><figcaption style="margin-bottom:6px">Ours</figcaption><img src="${uri(ours)}" style="width:100%;border:1px solid #ccc"></figure>
+      <figure style="margin:0;width:760px"><figcaption style="margin-bottom:6px">Reference: ${label.replace(/[<>&"]/g, "")}</figcaption><img src="${uri(theirs)}" style="width:100%;border:1px solid #ccc"></figure>
+    </div></body>`);
+  await page.locator("#w").screenshot({ path: out });
+  await page.close();
+}
+
+// fold: a quick look while building: the first screen only (no full-page screenshot) and no principles pass,
+// which runs on the winner.
+// like: projects the user asked to match; the similarity gate lets their look through.
+// tablet: also 1024 and 768 (tablet is where a hero photo gets blown up behind its text); palate gate always
+// renders those, so a shoot adds them only when asked.
+export const TABLET_WIDTHS = [1440, 1024, 768, 390];
+export async function shoot(dir, rawRoute, { widths: given, tablet = false, url, compare, fold: foldOnly = false, principles: withPrinciples = !foldOnly, like = [] } = {}) {
+  const widths = given ?? (tablet ? TABLET_WIDTHS : [1440, 390]);
+  const route = normalizeRoute(rawRoute);
+  const server = await acquireServer(dir, { url });
+  const base = server.base;
+
+  const slug = route.replace(/[^a-z0-9]+/gi, "-").replace(/^-|-$/g, "") || "home";
+  const outDir = path.join(dir, ".palate", "shots", slug);
+  fs.mkdirSync(outDir, { recursive: true });
+  fs.writeFileSync(path.join(dir, ".palate", ".gitignore"), "*\n");
+  const round = fs.readdirSync(outDir).filter((f) => f.endsWith("-fold.png")).reduce((n, f) => Math.max(n, Number(f.match(/^r(\d+)/)?.[1] ?? 0)), 0) + 1;
+
+  const { browser, release } = await acquireBrowser();
+  const report = [`# palate shoot ${route} (round ${round})${foldOnly ? ", first screen only" : ""}`, ""];
+  const files = [];
+  let fingerprint;
+  // The look fingerprint (loop/lookvec.mjs), measured on full shoots at the first desktop width.
+  let look = null;
+  let gate = null;
+  // The user's rules, checked once at the first desktop width.
+  let rules = null;
+  const allRules = activeRules();
+  try {
+    for (const width of widths) {
+      const height = width < 600 ? 844 : 900;
+      const ctx = await browser.newContext({ viewport: { width, height } });
+      const page = await ctx.newPage();
+      // Counts what moves (for the motion rule); patches nothing the page relies on.
+      if (allRules.length) await page.addInitScript(MOTION_INIT);
+      const errors = [];
+      page.on("pageerror", (e) => errors.push(e.message));
+      page.on("console", (m) => m.type() === "error" && errors.push(m.text()));
+      // Vite may reload the page once while it optimises newly found dependencies; measure again if so.
+      let m, contrastNodes, fold, full, principles;
+      for (let attempt = 0; ; attempt++) {
+        try {
+          await page.goto(base + route, { waitUntil: "networkidle", timeout: 30_000 }).catch((e) => errors.push(e.message));
+          await page.waitForTimeout(700);
+          // A build error renders as the dev server's overlay, not as the page.
+          const overlay = await page.evaluate(() => document.querySelector("vite-error-overlay")?.shadowRoot?.querySelector(".message")?.textContent ?? null).catch(() => null);
+          if (overlay) errors.unshift(`The page did not build: ${overlay.trim().slice(0, 300)}`);
+          fold = path.join(outDir, `r${round}-w${width}-fold.png`);
+          full = path.join(outDir, `r${round}-w${width}-full.png`);
+          await page.screenshot({ path: fold });
+          // Scroll through first so lazy images load and scroll reveals fire, then shoot the whole page.
+          if (!foldOnly) {
+            await scrollThrough(page, { pause: 80 });
+            await shootFull(page, full);
+          }
+          if (!attempt) files.push(fold, ...(foldOnly ? [] : [full]));
+          m = await page.evaluate(`(${metricsScript})()`);
+          await page.addScriptTag({ path: axePath });
+          contrastNodes = await page.evaluate(`axe.run(document, { runOnly: ["color-contrast"] }).then(r => r.violations.flatMap(v => v.nodes.map(n => (n.target.join(' ') + ' "' + (n.html.replace(/<[^>]+>/g, '').trim().slice(0, 30)) + '" ' + ((n.any[0] && n.any[0].data && n.any[0].data.contrastRatio) || '') + ':1'))))`);
+          // Alignment, hierarchy, spacing, type and consistency (scrolls to the top, so after the screenshots).
+          principles = withPrinciples ? await measurePrinciples(page).catch(() => null) : null;
+          if (!fingerprint && !overlay && width >= 1000) fingerprint = await page.evaluate(`(${fingerprintScript})()`).catch(() => undefined);
+          if (!foldOnly && !look && !overlay && width >= 1000) look = await import("./loop/lookvec.mjs").then((L) => L.measureLook(page)).then((m) => m.look).catch(() => null);
+          break;
+        } catch (e) {
+          if (attempt || !/context was destroyed|navigat/i.test(e.message)) throw e;
+          await page.waitForLoadState("networkidle").catch(() => {});
+        }
+      }
+      const contrast = contrastNodes.length;
+      // The rules: scroll through once (lazy parts load, reveals fire), measure, check those for this kind of screen.
+      if (allRules.length && !rules && width >= 1000 && !errors.some((e) => e.startsWith("The page did not build"))) {
+        try {
+          // A dev server can reload the page mid-scroll (another agent saved a file): then wait and scroll again.
+          let navs = 0;
+          page.on("framenavigated", (f) => f === page.mainFrame() && navs++);
+          await scrollThrough(page, { pause: 90 });
+          const broken = () => page.evaluate(() => document.body.innerText.length < 200).catch(() => true);
+          if (navs || (await broken())) {
+            await page.waitForLoadState("networkidle", { timeout: 30_000 }).catch(() => {});
+            await page.waitForTimeout(900);
+            await scrollThrough(page, { pause: 90 });
+          }
+          // The page itself broke while scrolling (a runtime error): measure it as loaded, unscrolled, and say so.
+          let note = null;
+          if (await broken()) {
+            note = `the page broke while scrolling${errors.length ? ` (${errors.at(-1).slice(0, 140)})` : ""}, so the rules were checked on the page as loaded, without scrolling`;
+            await page.reload({ waitUntil: "networkidle", timeout: 30_000 }).catch(() => {});
+            await page.waitForTimeout(900);
+          }
+          const { facts, sections } = await measureRules(page, allRules);
+          // Empty, loading, error … can't be seen in the page as it loads: they come from the latest palate states run.
+          Object.assign(facts, statesFactsFor(dir, route) ?? {});
+          if (note) facts.note = note;
+          const tags = routeTags(dir, route, { title: await page.title().catch(() => ""), sections });
+          rules = { tags, facts, results: checkRules(allRules.filter((r) => appliesTo(r, tags, { route, project: projectOf(dir) })), facts) };
+          fs.writeFileSync(path.join(outDir, `r${round}-rules.json`), JSON.stringify({ route, ...rules }, null, 1));
+        } catch (e) {
+          rules = { error: String(e.message).slice(0, 160), results: [] };
+        }
+      }
+      // The page's system across its sections (H2 sizes, section padding, buttons, cards; a photo used twice): the
+      // gate's page-level checks, so the one shoot of a direct fix sees a drift too.
+      let system = [];
+      if (width >= 1200 && !errors.some((e) => e.startsWith("The page did not build"))) {
+        try {
+          const { floorOnPage } = await import("./loop/floor.mjs");
+          const { findSections } = await import("./look.mjs");
+          const sections = await findSections(page);
+          system = (await floorOnPage(page, { width, sections, pageLevel: true })).filter((c) => c.id === "SYSTEM_DRIFT" || c.id === "PHOTO_REPEAT");
+        } catch {}
+      }
+      await ctx.close();
+
+      const warn = [];
+      if (errors.length) warn.push(`Console errors: ${errors.slice(0, 3).join(" | ")}`);
+      for (const c of system) warn.push(`${c.id}${c.severity === "fail" ? " (palate gate fails this)" : ""}: ${c.what}${c.fix ? `. ${c.fix}` : ""}`);
+      if (m.overflowX > 1) warn.push(`Page scrolls sideways by ${m.overflowX}px. Find the element wider than the screen.`);
+      if (m.tnumProseCount) warn.push(`Tabular figures are on ${m.tnumProseCount} text block(s) with words, e.g. "${m.tnumProse[0]}". In many fonts this spaces out commas and full stops. Apply tabular-nums only to numbers.`);
+      if (contrast) warn.push(`${contrast} element(s) fail colour contrast (WCAG AA): ${contrastNodes.slice(0, 3).join(" · ")}`);
+      if (m.tinyText) warn.push(`${m.tinyText} text element(s) under 12px.`);
+      if (m.fontSizes.length > 7) warn.push(`${m.fontSizes.length} different font sizes on one screen; a tight screen uses 4 to 6.`);
+      if (m.fontFamilies.length > 2) warn.push(`${m.fontFamilies.length} font families: ${m.fontFamilies.join(", ")}.`);
+      if (width >= 1200 && m.contentSpan < 55) warn.push(`Content spans only ${m.contentSpan}% of the width at ${width}px. Check whether the layout uses the screen or just floats in the middle.`);
+      if (width < 600 && m.smallTargets) warn.push(`${m.smallTargets} tap target(s) smaller than 24px: ${m.smallTargetList.join(", ")}.`);
+
+      report.push(`## ${width}px`);
+      report.push(foldOnly ? `- Screenshot: ${fold} (first screen; the page is ${m.pageHeight}px tall)` : `- Screenshots: ${fold} (first screen) and ${full} (full page, ${m.pageHeight}px tall)`);
+      if (!errors.some((e) => e.startsWith("The page did not build"))) {
+        const loop = loopOfRoute(dir, route);
+        if (loop) {
+          mark(dir, loop, "first_render", { route });
+          mark(dir, loop, "shot", { route });
+        }
+      }
+      report.push(`- Biggest text on the first screen: ${m.focal.size}px "${m.focal.text}"`);
+      report.push(`- Font sizes in use: ${m.fontSizes.join(", ")}`);
+      report.push(`- Font families: ${m.fontFamilies.join(", ")} · ${m.textColors} text colours · content spans ${m.contentSpan}% of the width`);
+      report.push(warn.length ? warn.map((w) => `- ⚠ ${w}`).join("\n") : "- No measurable problems. Judge the screenshot itself.");
+      if (principles) report.push(...principlesReport(principles, { max: 8 }));
+      report.push("");
+    }
+    if (rules?.results?.length) report.push(...rulesReport(rules.results).map((l, i) => (i === 0 ? `## Your rules (${rules.tags.join(", ")}; checked at ${widths.find((w) => w >= 1000)}px)` : l)), ...(rules.facts?.note ? [`- ⚠ Note: ${rules.facts.note}.`] : []), "");
+    else if (rules?.error) report.push(`## Your rules`, `- Could not check them: ${rules.error}`, "");
+    // A route built from the user's own design is theirs, not palate's: its look isn't compared or remembered.
+    const { matchedRoute } = await import("./loop/matched.mjs");
+    if (look && matchedRoute(dir, route)) report.push("## Look", "- Not compared: this route is built from the user's own design (palate match).", "");
+    else if (look) {
+      // The page's visual language in one line, and the closest look palate made recently in another project.
+      try {
+        const L = await import("./loop/lookvec.mjs");
+        const { projectId } = await import("./loop/layouts.mjs");
+        const { likeOf } = await import("./loop/similar.mjs");
+        const best = L.closestLook(look, { excludePid: projectId(dir), exclude: [...like, ...likeOf(dir, route)] });
+        await L.recordLook(dir, route, look);
+        const buttons = L.buttonRepeatFinding(look, { excludePid: projectId(dir), like: [...like, ...likeOf(dir, route)] });
+        report.push("## Look", L.lookLine(look, best, { buttons }), "");
+      } catch {}
+    }
+    if (fingerprint?.skeleton.length) {
+      const { noveltyReport } = await import("./novelty.mjs");
+      const novelty = noveltyReport(dir, route, fingerprint, { like });
+      gate = novelty.gate ?? null;
+      report.push(...novelty, "");
+    }
+    if (compare) {
+      const refImage = await resolveReference(compare);
+      const ours = files.find((f) => f.endsWith("-fold.png"));
+      if (refImage && ours) {
+        const file = path.join(outDir, `r${round}-compare.png`);
+        await sideBySide(browser, ours, refImage, file, compare);
+        report.push(`## Compared with ${compare}`, `- Side by side: ${file}`, "- Ask: where does ours fall short of the reference in hierarchy, type, spacing, density and finish? What is the single change that closes most of the gap?", "");
+      } else report.push(`- ⚠ Could not load reference "${compare}" for comparison.`, "");
+    }
+  } finally {
+    await release();
+    server.stop();
+  }
+  if (foldOnly) report.push("First screen only: the 390 check, the principles pass, details and animate run on the winner, after the pick.");
+  report.push("Now open the first-screen screenshots with your image-reading tool and review them with the Look checklist in the palate skill. Measurements catch bugs; they don't tell you whether the design is good.");
+  if (gate && !gate.pass) report.push(`palate shoot ${route}: FAILED the similarity gate. Change what it names (yourself; this isn't a question for the user), then shoot again.`);
+  return { report: report.join("\n"), files, rules, gate };
+}

package/src/systems/apply.mjs

@@ -0,0 +1,355 @@
+// `palate system apply <id>`: transfer a design system's craft into the project's own tokens.
+// Colour roles, a named type scale (text-display … text-caption), radii, depth and section spacing go
+// into the project's CSS; the project's brand accent is kept unless --no-keep-brand. Also writes
+// .palate/system.md: the rules an agent follows to extend the system to anything it never showed.
+import fs from "node:fs";
+import path from "node:path";
+import { hueSat, luminance, parseColor } from "../catalog/classify.mjs";
+import { fontClass } from "../catalog/classify.mjs";
+import { loadSystems } from "./load.mjs";
+
+const OPEN_FONTS = [
+  "Inter Tight", "Inter", "Geist Mono", "Geist", "Manrope", "DM Sans", "IBM Plex Sans", "IBM Plex Mono", "Plus Jakarta Sans", "Instrument Serif", "Instrument Sans",
+  "Fraunces", "Newsreader", "Source Serif 4", "EB Garamond", "Space Grotesk", "JetBrains Mono", "Figtree", "Outfit", "Sora", "Work Sans", "Public Sans",
+  "Roboto", "Open Sans", "Lora", "Playfair Display", "Cormorant Garamond", "Bricolage Grotesque", "Hanken Grotesk", "Onest", "Schibsted Grotesk", "Archivo",
+];
+const FONTSOURCE = (f) => `@fontsource-variable/${f.toLowerCase().replace(/\s+/g, "-").replace("source-serif-4", "source-serif-4")}`;
+const BY_CLASS = { "geometric-sans": "Geist", grotesk: "Inter", "humanist-sans": "Figtree", serif: "Newsreader", display: "Bricolage Grotesque", mono: "JetBrains Mono" };
+
+const toHex = ([r, g, b]) => "#" + [r, g, b].map((v) => Math.round(Math.max(0, Math.min(255, v))).toString(16).padStart(2, "0")).join("");
+const mix = (a, b, t) => {
+  const A = parseColor(a);
+  const B = parseColor(b);
+  if (!A || !B) return a;
+  return toHex(A.map((v, i) => v + (B[i] - v) * t));
+};
+const readable = (bg) => {
+  const rgb = parseColor(bg);
+  return rgb && luminance(rgb) > 0.45 ? "#0a0a0a" : "#ffffff";
+};
+// oklch() strings carry chroma directly; parseColor flattens them to grey.
+const chromatic = (value) => {
+  const ok = /oklch\(\s*[\d.]+%?\s+([\d.]+)/i.exec(value ?? "");
+  if (ok) return Number(ok[1]) > 0.04;
+  const rgb = parseColor(value);
+  return rgb ? hueSat(rgb).s > 0.15 : false;
+};
+
+// A family an agent can actually load: the system's own if it's open, the substitute it names, or one by class.
+function openFamily(family, sys) {
+  if (!family) return undefined;
+  const direct = OPEN_FONTS.find((f) => family.toLowerCase() === f.toLowerCase() || family.toLowerCase().startsWith(f.toLowerCase() + " "));
+  if (direct) return direct;
+  const cls = fontClass(family) ?? "grotesk";
+  const isMono = (f) => /mono/i.test(f);
+  // A substitute must be the same kind of face: a mono role gets a mono font, a serif role a serif.
+  const candidates = OPEN_FONTS.filter((f) => (cls === "mono" ? isMono(f) : !isMono(f)) && (cls === "serif" ? fontClass(f) === "serif" : fontClass(f) !== "serif"));
+  const note = Object.entries(sys.sections)
+    .filter(([k]) => /substitut|font famil|typograph/.test(k))
+    .map(([, v]) => v)
+    .join("\n");
+  const named = candidates.find((f) => new RegExp(`\\b${f}\\b`, "i").test(note));
+  return named ?? BY_CLASS[cls];
+}
+
+function typeRoles(sys) {
+  const t = [...sys.type].sort((a, b) => b.size - a.size);
+  const by = (re) => sys.type.filter((r) => re.test(r.role)).sort((a, b) => b.size - a.size);
+  const displays = by(/display|hero|heading-1|headline|h1|title-xl/);
+  const pick = (...lists) => lists.flat().find(Boolean);
+  const roles = {
+    display: pick(displays[0], t[0]),
+    h1: pick(displays[1], by(/heading-lg|heading-1|h1|title-lg/)[0], t[1]),
+    h2: pick(displays[2], by(/heading-md|heading-2|h2|headline|section/)[0], t[2]),
+    h3: pick(by(/card-title|heading-sm|title-md|h3|subhead|title/)[0], t[3]),
+    "body-lg": pick(by(/body-lg|lead|subhead/)[0]),
+    body: pick(by(/^body(-md)?$/)[0], by(/body/)[0]),
+    "body-sm": pick(by(/body-sm|small/)[0]),
+    caption: pick(by(/caption|micro|label|eyebrow/).reverse()[0]),
+    button: pick(by(/button/)[0]),
+  };
+  return completeScale(Object.fromEntries(Object.entries(roles).filter(([, v]) => v)));
+}
+
+// Every project gets the same role names, even when a DESIGN.md documents only some of them: the
+// missing steps are derived from the body size, and nothing goes below 12px (the shoot floor).
+function completeScale(roles) {
+  const body = roles.body ?? { size: 16, weight: 400, lineHeight: 1.5 };
+  const like = (size, extra) => ({ family: body.family, weight: body.weight ?? 400, lineHeight: body.lineHeight ?? 1.5, ...extra, size });
+  const out = { ...roles, body };
+  out["body-lg"] ??= like(Math.round(body.size * 1.125), { lineHeight: 1.55 });
+  out["body-sm"] ??= like(Math.max(13, body.size - 2));
+  out.label = like(out["body-sm"].size, { weight: 500, lineHeight: 1.4 });
+  out.caption = out.caption ? { ...out.caption, size: Math.max(12, out.caption.size) } : like(12, { lineHeight: 1.4 });
+  out.button ??= like(out["body-sm"].size, { weight: 500, lineHeight: 1 });
+  const order = ["display", "h1", "h2", "h3", "body-lg", "body", "body-sm", "label", "caption", "button"];
+  return Object.fromEntries(order.filter((k) => out[k]).map((k) => [k, out[k]]));
+}
+
+// WCAG contrast, and a colour nudged toward black or white until it reaches the ratio.
+const wcag = (a, b) => {
+  const A = parseColor(a);
+  const B = parseColor(b);
+  if (!A || !B) return 21;
+  const [l1, l2] = [luminance(A), luminance(B)].sort((x, y) => y - x);
+  return (l1 + 0.05) / (l2 + 0.05);
+};
+function reach(color, against, ratio, toward) {
+  let c = color;
+  for (let i = 1; i <= 20 && wcag(c, against) < ratio; i++) c = mix(color, toward, i * 0.05);
+  return c;
+}
+
+// shadcn's cn() runs tailwind-merge, which reads unknown text-* classes as colours and drops a
+// type role whenever a colour class follows it. Teach it the roles.
+function patchCn(dir, roleNames) {
+  const file = ["src/lib/utils.ts", "lib/utils.ts", "src/lib/utils.js"].map((f) => path.join(dir, f)).find((f) => fs.existsSync(f));
+  if (!file) return undefined;
+  let src = fs.readFileSync(file, "utf8");
+  const list = roleNames.map((r) => `"${r}"`).join(", ");
+  const block = `// palate: the design system's type roles are font sizes; without this, tailwind-merge reads them as
+// text colours and drops them when a colour class follows.
+const twMerge = extendTailwindMerge({
+  extend: { classGroups: { "font-size": [{ text: [${list}] }] } },
+});`;
+  if (/extendTailwindMerge/.test(src)) {
+    src = src.replace(/"font-size":\s*\[\{\s*text:\s*\[[^\]]*\]/, `"font-size": [{ text: [${list}]`);
+  } else if (/import\s*\{\s*twMerge\s*\}\s*from\s*["']tailwind-merge["'];?/.test(src)) {
+    src = src.replace(/import\s*\{\s*twMerge\s*\}\s*from\s*["']tailwind-merge["'];?/, 'import { extendTailwindMerge } from "tailwind-merge";');
+    src = src.replace(/(\n)(export function cn)/, `\n${block}\n$1$2`);
+  } else return undefined;
+  fs.writeFileSync(file, src);
+  return path.relative(dir, file);
+}
+
+// In a hairline system, shared primitives lose their resting drop shadows (overlays keep theirs).
+function stripRestingShadows(dir) {
+  const uiDir = ["src/components/ui", "components/ui"].map((d) => path.join(dir, d)).find((d) => fs.existsSync(d));
+  if (!uiDir) return 0;
+  let n = 0;
+  for (const f of fs.readdirSync(uiDir).filter((f) => /^(button|input|select|textarea|card|checkbox|switch|tabs|badge|toggle)\.tsx$/.test(f))) {
+    const file = path.join(uiDir, f);
+    const src = fs.readFileSync(file, "utf8");
+    const out = src.replace(/(?<![\w:-])shadow-(xs|sm)(?![\w-])\s?/g, () => (n++, ""));
+    if (out !== src) fs.writeFileSync(file, out);
+  }
+  return n;
+}
+
+function firstShadow(sys) {
+  const text = Object.entries(sys.sections)
+    .filter(([k]) => /elevation|depth|shadow|card/.test(k))
+    .map(([, v]) => v)
+    .join("\n");
+  const m = /((?:rgba?\([^)]*\)|#[0-9a-f]{3,8})\s+-?\d+px\s+-?\d+px\s+-?\d+px(?:\s+-?\d+px)?(?:\s*,\s*(?:rgba?\([^)]*\)|#[0-9a-f]{3,8})\s+-?\d+px\s+-?\d+px\s+-?\d+px(?:\s+-?\d+px)?)*)/i.exec(text) ?? /(-?\d+px\s+-?\d+px\s+-?\d+px(?:\s+-?\d+px)?\s+(?:rgba?\([^)]*\)|#[0-9a-f]{3,8}))/i.exec(text);
+  return m?.[1];
+}
+
+function findTokenCss(dir) {
+  const candidates = ["src/index.css", "src/globals.css", "app/globals.css", "src/app/globals.css", "src/styles/globals.css", "src/tokens.css", "styles/globals.css"];
+  return candidates.map((c) => path.join(dir, c)).find((f) => fs.existsSync(f) && /:root\s*\{[^}]*--background\s*:/s.test(fs.readFileSync(f, "utf8")));
+}
+
+export function systemTokens(sys, { brandPrimary } = {}) {
+  const r = sys.roles;
+  const light = sys.facets.theme !== "dark";
+  const canvas = r.canvas;
+  const ink = r.ink;
+  const soft = r.surfaceSoft ?? mix(canvas, ink, light ? 0.035 : 0.06);
+  const primary = brandPrimary ?? r.primary ?? ink;
+  const vars = {
+    background: canvas,
+    foreground: ink,
+    card: r.surface && r.surface !== canvas ? r.surface : light ? mix(canvas, "#ffffff", 0.6) : mix(canvas, "#ffffff", 0.04),
+    "card-foreground": ink,
+    popover: r.surface ?? canvas,
+    "popover-foreground": ink,
+    primary,
+    "primary-foreground": brandPrimary ? undefined : r.onPrimary ?? readable(primary),
+    secondary: soft,
+    "secondary-foreground": ink,
+    muted: soft,
+    "muted-foreground": r.muted ?? r.body ?? mix(ink, canvas, 0.45),
+    accent: mix(soft, ink, light ? 0.02 : 0.04),
+    "accent-foreground": ink,
+    border: r.hairline ?? mix(canvas, ink, light ? 0.1 : 0.14),
+    input: r.hairlineStrong ?? r.hairline ?? mix(canvas, ink, light ? 0.16 : 0.2),
+    ring: primary,
+    destructive: r.error,
+    success: r.success,
+    warning: r.warning,
+  };
+  // Text must stay readable: muted text on every surface, and the label on the primary button.
+  // A kept brand colour isn't changed here; apply reports it instead.
+  vars["muted-foreground"] = reach(vars["muted-foreground"], [vars.muted, vars.background, vars.card].sort((a, b) => wcag(vars["muted-foreground"], a) - wcag(vars["muted-foreground"], b))[0], 4.5, light ? "#000000" : "#ffffff");
+  if (!brandPrimary && vars["primary-foreground"] && wcag(vars.primary, vars["primary-foreground"]) < 4.5) {
+    vars.primary = reach(vars.primary, vars["primary-foreground"], 4.5, luminance(parseColor(vars["primary-foreground"]) ?? [255, 255, 255]) > 0.5 ? "#000000" : "#ffffff");
+    vars.ring = vars.primary;
+  }
+  return Object.fromEntries(Object.entries(vars).filter(([, v]) => v));
+}
+
+function themeBlock(sys, fonts, roles = typeRoles(sys)) {
+  // @fontsource-variable registers each face as "<Name> Variable"; the plain name covers a local install.
+  const face = (f) => `"${f} Variable", "${f}"`;
+  const lines = ["@theme {", `  --font-sans: ${face(fonts.body)}, ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;`, `  --font-display: ${face(fonts.display)}, var(--font-sans);`];
+  if (fonts.mono) lines.push(`  --font-mono: ${face(fonts.mono)}, ui-monospace, "SF Mono", Menlo, monospace;`);
+  for (const [role, t] of Object.entries(roles)) {
+    lines.push(`  --text-${role}: ${t.size / 16}rem;`);
+    if (t.lineHeight) lines.push(`  --text-${role}--line-height: ${t.lineHeight};`);
+    if (t.tracking) lines.push(`  --text-${role}--letter-spacing: ${t.tracking}em;`);
+    if (t.weight) lines.push(`  --text-${role}--font-weight: ${t.weight};`);
+  }
+  const rad = sys.radii;
+  const radius = (k, fallback) => (rad[k] ?? fallback) !== undefined ? `${Math.min(rad[k] ?? fallback, 9999)}px` : undefined;
+  for (const [k, v] of [["sm", radius("sm", rad.xs)], ["md", radius("md")], ["lg", radius("lg")], ["xl", radius("xl")], ["2xl", radius("xxl", rad.xl)]]) if (v) lines.push(`  --radius-${k}: ${v};`);
+  const shadow = firstShadow(sys);
+  if (shadow) lines.push(`  --shadow-raised: ${shadow};`);
+  if (sys.spacing.section) lines.push(`  --spacing-section: ${sys.spacing.section / 16}rem;`);
+  lines.push("}");
+  return { css: lines.join("\n"), roles };
+}
+
+function grammar(sys, roles, keptBrand) {
+  const f = sys.facets;
+  const rules = [];
+  rules.push(
+    f.elevation === "hairline"
+      ? "Depth comes from 1px hairlines (`border`) and stepped surfaces (`bg-background` → `bg-muted` → `bg-card`). No drop shadows on things at rest; only overlays (menus, dialogs) may float."
+      : f.elevation === "shadow"
+        ? "Raised surfaces use `shadow-raised` (the system's own shadow); borders stay faint or absent."
+        : "Use hairlines for structure and `shadow-raised` only for genuinely floating things.",
+  );
+  rules.push(`Radii: buttons and inputs \`rounded-md\` (${sys.radii.md ?? "?"}px), cards \`rounded-lg\` (${sys.radii.lg ?? "?"}px)${f.radius === "pill" ? "; primary buttons are pills (`rounded-full`)" : ""}. Never mix in other radii.`);
+  rules.push(
+    f.palette === "restrained"
+      ? "Colour is rare: the accent appears only on the primary action, links, focus and selection. Everything else is neutral. Status uses small dots or text, not filled badges."
+      : "The accent leads; supporting colours stay inside their own areas (one per category or status), never decorative.",
+  );
+  rules.push(`Type: use the named roles only (${Object.keys(roles).map((k) => `\`text-${k}\``).join(", ")}); \`text-label\` is for table headers, form labels and names in lists. Don't add weights or tracking on top of a role. Display type is ${roles.display?.weight ?? "?"} weight with ${roles.display?.tracking ?? 0}em tracking; never bold it further.`);
+  rules.push(`Density: body is ${roles.body?.size ?? "?"}px. ${f.density === "dense" ? "Keep rows 36–44px and gaps tight." : f.density === "airy" ? "Give content generous gaps (24–48px) and large section spacing." : "Rows 44–52px, section spacing as `py-(--spacing-section)` where it exists."}`);
+  if (keptBrand) rules.push("The primary colour is the project's own brand, kept on purpose. Use it the way this system uses its accent.");
+  rules.push("Extending the system: a component this system never showed must still look native. Build it from the same surfaces, hairlines, radii, type roles and accent rules above, then check it next to an existing component.");
+  return rules;
+}
+
+const trim = (s, n) => (s && s.length > n ? s.slice(0, n).replace(/\s+\S*$/, "") + " …" : s ?? "");
+
+export function applySystem(id, dir, { keepBrand = true, typeFrom } = {}) {
+  const all = loadSystems();
+  const find = (x) => all.find((s) => s.id === x || s.name.toLowerCase() === String(x).toLowerCase());
+  const sys = find(id);
+  if (!sys) throw new Error(`No design system "${id}". Run: palate system list`);
+  // Blending: display, h1 and h2 (and the display face) from a second system; everything else from the first.
+  const donor = typeFrom ? find(typeFrom) : undefined;
+  if (typeFrom && !donor) throw new Error(`No design system "${typeFrom}" to take type from.`);
+  const typeSet = { ...typeRoles(sys), ...(donor ? Object.fromEntries(["display", "h1", "h2"].map((k) => [k, typeRoles(donor)[k]]).filter(([, v]) => v)) : {}) };
+  const cssFile = findTokenCss(dir);
+  const display = typeSet.display;
+  const body = typeSet.body;
+  const monoRole = sys.type.find((t) => /mono|code/.test(t.role));
+  const fonts = { display: openFamily(display?.family, donor ?? sys) ?? "Inter", body: openFamily(body?.family, sys) ?? "Inter", mono: monoRole ? openFamily(monoRole.family, sys) : undefined };
+
+  let brandPrimary;
+  let changes = [];
+  const notes = [];
+  if (cssFile) {
+    let css = fs.readFileSync(cssFile, "utf8");
+    fs.mkdirSync(path.join(dir, ".palate", "backup"), { recursive: true });
+    fs.writeFileSync(path.join(dir, ".palate", "backup", `${path.basename(cssFile)}.${Date.now()}`), css);
+    const root = /:root\s*\{([^}]*)\}/s.exec(css);
+    const currentPrimary = /--primary\s*:\s*([^;]+);/.exec(root?.[1] ?? "")?.[1]?.trim();
+    if (keepBrand && currentPrimary && chromatic(currentPrimary)) brandPrimary = currentPrimary;
+    const vars = systemTokens(sys, { brandPrimary });
+    let block = root[1];
+    for (const [k, v] of Object.entries(vars)) {
+      const re = new RegExp(`(--${k}\\s*:\\s*)([^;]+);`);
+      if (re.test(block)) {
+        const old = re.exec(block)[2].trim();
+        if (old !== v) changes.push(`--${k}: ${old} → ${v}`);
+        block = block.replace(re, `$1${v};`);
+      } else {
+        block = block.replace(/\s*$/, `\n  --${k}: ${v};\n`);
+        changes.push(`--${k}: (new) ${v}`);
+      }
+    }
+    const radius = sys.radii.md ?? sys.radii.sm;
+    if (radius !== undefined) block = block.replace(/(--radius\s*:\s*)([^;]+);/, `$1${Math.min(radius, 9999) / 16}rem;`);
+    css = css.replace(root[0], `:root {${block}}`);
+    // Status colours need Tailwind names (bg-success, text-warning) to be usable at all.
+    const inline = /@theme inline\s*\{([^}]*)\}/s.exec(css);
+    if (inline) {
+      const add = ["success", "warning", "destructive"].filter((k) => vars[k] && !new RegExp(`--color-${k}\\s*:`).test(inline[1])).map((k) => `  --color-${k}: var(--${k});`);
+      if (add.length) css = css.replace(inline[0], inline[0].replace(/\}$/, `${add.join("\n")}\n}`));
+    }
+    if (brandPrimary) {
+      const fg = /--primary-foreground\s*:\s*([^;]+);/.exec(block)?.[1]?.trim();
+      if (fg && wcag(brandPrimary, fg) < 4.5) notes.push(`Your brand primary (${brandPrimary}) behind its button text (${fg}) is ${wcag(brandPrimary, fg).toFixed(2)}:1, under WCAG AA 4.5:1. Darken the brand for buttons or change the button text colour.`);
+    }
+    if (/\.dark\s*\{/.test(css)) notes.push("Dark-mode tokens (.dark) were left as they were; they don't follow this system yet.");
+    const { css: theme } = themeBlock(sys, fonts, typeSet);
+    const marked = `/* palate:system ${sys.id}${donor ? ` + type from ${donor.id}` : ""} — craft from ${sys.name}${donor ? ` and ${donor.name}` : ""} (DESIGN.md via VoltAgent/awesome-design-md, MIT) */\n${theme}\n/* /palate:system */`;
+    css = /\/\* palate:system[\s\S]*?\/\* \/palate:system \*\//.test(css) ? css.replace(/\/\* palate:system[\s\S]*?\/\* \/palate:system \*\//, marked) : `${css.trimEnd()}\n\n${marked}\n`;
+    for (const f of new Set([fonts.display, fonts.body, fonts.mono].filter(Boolean))) {
+      const imp = `@import "${FONTSOURCE(f)}";`;
+      if (!css.includes(imp)) css = css.replace(/(@import\s+["']tailwindcss["'];?)/, `$1\n${imp}`);
+    }
+    fs.writeFileSync(cssFile, css);
+  }
+
+  const { roles } = themeBlock(sys, fonts, typeSet);
+  const cnFile = patchCn(dir, Object.keys(roles));
+  const shadowsRemoved = sys.facets.elevation === "hairline" ? stripRestingShadows(dir) : 0;
+  if (keepBrand && !brandPrimary) notes.push(`The project had no brand colour, so the primary is ${sys.name}'s own accent. Set your own --primary in the token file, or the product will wear ${sys.name}'s colour.`);
+  const rules = grammar(sys, roles, Boolean(brandPrimary));
+  const sec = (re) => Object.entries(sys.sections).find(([k]) => re.test(k))?.[1];
+  const brief = [
+    `# Design system: ${sys.name}${donor ? ` with display type from ${donor.name}` : ""}`,
+    "",
+    `Craft transferred from ${sys.name}'s public design (DESIGN.md from VoltAgent/awesome-design-md, MIT). ${brandPrimary ? `The project's own brand colour (${brandPrimary}) is kept as the primary.` : ""} Don't reproduce ${sys.name}'s logo, wording or imagery.`,
+    "",
+    `${trim(sys.description, 600)}`,
+    "",
+    "## Type roles (use these classes, nothing else)",
+    "| Class | Size | Weight | Line height | Tracking |",
+    "|---|---|---|---|---|",
+    ...Object.entries(roles).map(([k, t]) => `| \`text-${k}\` | ${t.size}px | ${t.weight ?? ""} | ${t.lineHeight ?? ""} | ${t.tracking ? `${t.tracking}em` : "0"} |`),
+    "",
+    `Fonts: display \`${fonts.display}\`, body \`${fonts.body}\`${fonts.mono ? `, mono \`${fonts.mono}\`` : ""} (open substitutes where the original is proprietary). Install with: pnpm add ${[...new Set([fonts.display, fonts.body, fonts.mono].filter(Boolean))].map(FONTSOURCE).join(" ")}`,
+    "",
+    "## Rules for building anything in this system",
+    ...rules.map((r) => `- ${r}`),
+    "",
+    "## The system's own guidance",
+    sec(/do'?s and don'?ts|^do$/) ? `### Do and don't\n${trim(sec(/do'?s and don'?ts|^do$/), 1800)}` : "",
+    sec(/^don'?t$/) ? `### Don't\n${trim(sec(/^don'?t$/), 1200)}` : "",
+    sec(/elevation|depth/) ? `### Elevation\n${trim(sec(/elevation|depth/), 1200)}` : "",
+    sec(/whitespace|spacing system|layout/) ? `### Layout\n${trim(sec(/whitespace|spacing system|layout/), 1200)}` : "",
+    sec(/^buttons?$/) ? `### Buttons\n${trim(sec(/^buttons?$/), 1200)}` : "",
+    sec(/cards|containers/) ? `### Cards and containers\n${trim(sec(/cards|containers/), 1200)}` : "",
+    sec(/inputs|forms/) ? `### Inputs\n${trim(sec(/inputs|forms/), 800)}` : "",
+  ]
+    .filter((l) => l !== "")
+    .join("\n");
+  fs.mkdirSync(path.join(dir, ".palate"), { recursive: true });
+  fs.writeFileSync(path.join(dir, ".palate", ".gitignore"), "*\n");
+  fs.writeFileSync(path.join(dir, ".palate", "system.md"), brief);
+  const histFile = path.join(dir, ".palate", "systems.json");
+  const hist = fs.existsSync(histFile) ? JSON.parse(fs.readFileSync(histFile, "utf8")) : [];
+  hist.push({ id: sys.id, ...(donor ? { typeFrom: donor.id } : {}), at: new Date().toISOString() });
+  fs.writeFileSync(histFile, JSON.stringify(hist, null, 2));
+
+  return [
+    `Applied ${sys.name} craft to ${cssFile ? path.relative(dir, cssFile) : "(no shadcn token file found: see .palate/system.md and map the tokens by hand)"}.`,
+    brandPrimary ? `Kept the project's brand primary (${brandPrimary}).` : "Primary taken from the system.",
+    changes.length ? `Changed ${changes.length} tokens:\n${changes.map((c) => `  ${c}`).join("\n")}` : "",
+    `Type roles: ${Object.entries(roles).map(([k, t]) => `text-${k} ${t.size}px/${t.weight ?? ""}`).join(" · ")}`,
+    `Fonts: install ${[...new Set([fonts.display, fonts.body, fonts.mono].filter(Boolean))].map(FONTSOURCE).join(" ")} (imports added).`,
+    cnFile ? `Taught tailwind-merge the type roles in ${cnFile}, so cn() keeps them.` : "",
+    shadowsRemoved ? `Removed ${shadowsRemoved} resting drop shadow(s) from components/ui (this system uses hairlines).` : "",
+    ...notes.map((n) => `Note: ${n}`),
+    `Rules for extending the system: .palate/system.md (read it before building).`,
+  ]
+    .filter(Boolean)
+    .join("\n");
+}