@litfamily/litmuse 0.1.1 → 0.1.3

package/plugin/skills/frontend-ui-ux/scripts/interface-probe-lock.mjs

@@ -0,0 +1,196 @@
+// In-page design-lock conformance (DS-001..DS-008). interface-probe.mjs serialises this function
+// into the page, so it may not import anything or close over module scope; every threshold comes
+// from the rule table through `options.rules`, and the lock arrives as `options.lock`.
+export function measureLock(options) {
+  const { rules, limits, lock } = options;
+  const findings = [];
+  const notVerified = [];
+  const push = (rule, selector, value, threshold, severity) => {
+    if (findings.filter((f) => f.rule === rule).length >= limits.findingsPerRule) return;
+    findings.push({ rule, severity: severity ?? rules[rule].severity, tier: rules[rule].tier, selector, value, threshold });
+  };
+  const describe = (el) => {
+    if (el.id) return `#${el.id}`;
+    const cls = [...el.classList].slice(0, 2).map((c) => `.${c}`).join("");
+    return `${el.tagName.toLowerCase()}${cls}`;
+  };
+  const exempt = (el) => Boolean(el.closest("[data-lock-exempt], img, video, canvas, iframe, picture, object"));
+  const visible = (el) => {
+    if (typeof el.checkVisibility === "function" && !el.checkVisibility({ checkOpacity: false, checkVisibilityCSS: true })) return false;
+    const box = el.getBoundingClientRect();
+    return box.width >= 1 && box.height >= 1;
+  };
+
+  // DS-001: the generated tokens.css carries the lock id on :root.
+  const applied = getComputedStyle(document.documentElement).getPropertyValue(rules["DS-001"].threshold.property).trim().replace(/^["']|["']$/gu, "");
+  if (applied !== lock.style) {
+    push("DS-001", ":root", applied ? `${rules["DS-001"].threshold.property}: ${applied}` : `${rules["DS-001"].threshold.property} missing`, `"${lock.style}" from design.lock.json`);
+    return { findings, notVerified };
+  }
+
+  const parse = (value) => {
+    let match = /^rgba?\(([\d.]+),\s*([\d.]+),\s*([\d.]+)(?:,\s*([\d.]+))?\)$/u.exec(value);
+    if (match) return { rgb: [Number(match[1]), Number(match[2]), Number(match[3])], alpha: match[4] === undefined ? 1 : Number(match[4]) };
+    match = /^color\(srgb\s+([-\d.e]+)\s+([-\d.e]+)\s+([-\d.e]+)(?:\s*\/\s*([\d.]+))?\)$/u.exec(value);
+    if (match) return { rgb: [match[1], match[2], match[3]].map((n) => Math.round(Number(n) * 255)), alpha: match[4] === undefined ? 1 : Number(match[4]) };
+    return null;
+  };
+  const hex = (h) => [1, 3, 5].map((i) => parseInt(h.slice(i, i + 2), 16));
+  const palette = [...Object.values(lock.colors.light), ...Object.values(lock.colors.dark)].map(hex);
+  const tolerance = rules["DS-003"].threshold.channelTolerance;
+  const onPalette = (rgb) => palette.some((p) => Math.abs(p[0] - rgb[0]) <= tolerance && Math.abs(p[1] - rgb[1]) <= tolerance && Math.abs(p[2] - rgb[2]) <= tolerance);
+  const toHex = (rgb) => `#${rgb.map((n) => Math.max(0, Math.min(255, n)).toString(16).padStart(2, "0")).join("")}`;
+  const families = new Set(lock.fonts.map((f) => f.toLowerCase()));
+  const sizes = lock.type.scale_px;
+  const display = lock.type.display_px;
+  // Inside the declared signature moment type may run past the display range up to the lock's ceiling.
+  const momentMax = lock.type.moment_px?.max ?? display.max;
+  const momentAttr = rules["DS-008"].threshold.attribute;
+  const sizeTolerance = rules["DS-004"].threshold.tolerancePx;
+  const radii = lock.radius_px;
+  const radiusTolerance = rules["DS-005"].threshold.tolerancePx;
+
+  const offColours = new Map();
+  const offFamilies = new Map();
+  const offSizes = new Map();
+  const offRadii = new Map();
+  const offShadows = new Map();
+  let unparsed = 0;
+  // DS-007: the lock names an elevation grammar. "flat" allows only rings (no blur, no offset past a
+  // hairline); "offset" allows hard offsets but no blur; "soft" is left to CF-403. Insets never count.
+  const elevation = lock.elevation ?? "soft";
+  const hairline = rules["DS-007"].threshold.hairlinePx;
+  const shadowLengths = (value) => (value === "none" ? [] : value.split(/,(?![^()]*\))/u)).filter((part) => !/\binset\b/u.test(part))
+    .map((part) => part.replace(/\b(?:rgba?|color|hsla?|oklch|lab|lch)\([^)]*\)/gu, "").match(/-?[\d.]+px/gu)?.map(Number.parseFloat) ?? []);
+  const noteColour = (value, el, where) => {
+    const colour = parse(value);
+    if (!colour) { if (value !== "transparent" && value !== "none") unparsed += 1; return; }
+    if (colour.alpha < rules["DS-003"].threshold.minAlpha || onPalette(colour.rgb)) return;
+    const key = toHex(colour.rgb);
+    if (!offColours.has(key)) offColours.set(key, `${describe(el)} ${where}`);
+  };
+
+  const elements = [...document.body.querySelectorAll("*")].slice(0, limits.nodes);
+  for (const el of elements) {
+    if (exempt(el) || !visible(el)) continue;
+    const style = getComputedStyle(el);
+    const isSvgShape = el instanceof SVGElement && !(el instanceof SVGSVGElement);
+    if (isSvgShape) {
+      if (["rect", "path", "circle", "ellipse", "polygon", "polyline", "line"].includes(el.tagName.toLowerCase())) {
+        if (style.fill !== "none") noteColour(style.fill, el, "fill");
+        if (style.stroke !== "none") noteColour(style.stroke, el, "stroke");
+      }
+      continue;
+    }
+    const ownText = [...el.childNodes].some((node) => node.nodeType === Node.TEXT_NODE && node.textContent.trim());
+    if (ownText) {
+      noteColour(style.color, el, "text");
+      const family = style.fontFamily.split(",")[0].trim().replace(/^["']|["']$/gu, "").toLowerCase();
+      if (!families.has(family) && !offFamilies.has(family)) offFamilies.set(family, describe(el));
+      const px = Number.parseFloat(style.fontSize);
+      const ceiling = el.closest(`[${momentAttr}]`) ? momentMax : display.max;
+      const onScale = sizes.some((s) => Math.abs(s - px) <= sizeTolerance) || (px >= display.min - sizeTolerance && px <= ceiling + sizeTolerance);
+      if (!onScale && !offSizes.has(px)) offSizes.set(px, describe(el));
+    }
+    noteColour(style.backgroundColor, el, "background");
+    for (const side of ["Top", "Right", "Bottom", "Left"]) {
+      if (Number.parseFloat(style[`border${side}Width`]) > 0 && style[`border${side}Style`] !== "none") noteColour(style[`border${side}Color`], el, "border");
+    }
+    if (elevation !== "soft") {
+      for (const [x = 0, y = 0, blur = 0] of shadowLengths(style.boxShadow)) {
+        const offset = Math.abs(x) > hairline || Math.abs(y) > hairline;
+        if ((blur > 0 || (elevation === "flat" && offset)) && !offShadows.has(describe(el))) offShadows.set(describe(el), `${x}px ${y}px ${blur}px`);
+      }
+    }
+    const box = el.getBoundingClientRect();
+    for (const corner of ["TopLeft", "TopRight", "BottomRight", "BottomLeft"]) {
+      const raw = style[`border${corner}Radius`];
+      if (!raw || raw.includes(" ") || raw.includes("%")) continue;
+      const r = Number.parseFloat(raw);
+      if (!(r > 0)) continue;
+      const round = r >= Math.min(box.width, box.height) / 2 - radiusTolerance;
+      if (!round && !radii.some((v) => Math.abs(v - r) <= radiusTolerance) && !offRadii.has(r)) offRadii.set(r, describe(el));
+    }
+  }
+
+  for (const [family, where] of offFamilies) push("DS-002", where, `font-family "${family}"`, `one of ${lock.fonts.join(", ")}`);
+  if (offColours.size) {
+    const list = [...offColours.entries()];
+    const severity = list.length >= rules["DS-003"].threshold.highCount ? "HIGH" : rules["DS-003"].threshold.lowSeverity;
+    push("DS-003", list.slice(0, 4).map(([, where]) => where).join(" | "), `${list.length} off-palette colour(s): ${list.slice(0, 8).map(([c]) => c).join(", ")}`, `the ${lock.style} palette (light and dark roles)`, severity);
+  }
+  if (offSizes.size) push("DS-004", [...offSizes.values()].slice(0, 3).join(" | "), `${offSizes.size} size(s) off scale: ${[...offSizes.keys()].slice(0, 8).map((n) => `${n}px`).join(", ")}`, `${sizes.join("/")}px or display ${display.min}–${display.max}px`);
+  if (offRadii.size) push("DS-005", [...offRadii.values()].slice(0, 3).join(" | "), `${offRadii.size} radius value(s) off lock: ${[...offRadii.keys()].slice(0, 6).map((n) => `${n}px`).join(", ")}`, `${radii.join("/")}px or fully round`);
+  if (offShadows.size) push("DS-007", [...offShadows.keys()].slice(0, 3).join(" | "), `${offShadows.size} element(s) with ${[...offShadows.values()].slice(0, 3).join(", ")} shadows`, elevation === "flat" ? "flat lock: rings only, no blur or offset" : "offset lock: zero-blur offsets only");
+  if (unparsed) notVerified.push({ rule: "DS-003", reason: `${unparsed} colour value(s) in a format the probe cannot compare` });
+
+  // DS-006: a starter-layout slot such as {{Product}} left in visible text or a labelling attribute.
+  const slot = new RegExp(rules["DS-006"].threshold.pattern, "u");
+  const textHit = slot.exec(document.body.innerText.slice(0, limits.textChars * 10));
+  if (textHit) push("DS-006", "page text", textHit[0], "no {{slot}} from the kit layouts");
+  for (const el of document.querySelectorAll("[title], [aria-label], [alt], [placeholder]")) {
+    for (const attr of ["title", "aria-label", "alt", "placeholder"]) {
+      const value = el.getAttribute(attr);
+      const hit = value && slot.exec(value);
+      if (hit) push("DS-006", `${describe(el)}[${attr}]`, hit[0], "no {{slot}} from the kit layouts");
+    }
+  }
+  const title = slot.exec(document.title);
+  if (title) push("DS-006", "title", title[0], "no {{slot}} from the kit layouts");
+
+  // DS-008: the one signature moment the lock declares. It must be declared, marked, big enough to
+  // read, in the first screen on a read-once page, hold what its kind promises, and not be the
+  // generic gradient-and-centred-text hero.
+  const m = rules["DS-008"].threshold;
+  const declared = lock.moment;
+  if (!declared) {
+    push("DS-008", "design.lock.json", "the lock predates signature moments and records none", "a moment recorded with design-lock.mjs moment");
+    return { findings, notVerified };
+  }
+  if (!declared.kind) {
+    push("DS-008", "design.lock.json", "the lock declares no signature moment", `a ${declared.scale} moment recorded with design-lock.mjs moment`);
+    return { findings, notVerified };
+  }
+  const marked = [...document.querySelectorAll(`[${m.attribute}]`)].filter(visible);
+  if (!marked.length) {
+    push("DS-008", "page", `no [${m.attribute}] element for the declared ${declared.kind}`, `one element marked ${m.attribute}="${declared.kind}"`);
+    return { findings, notVerified };
+  }
+  if (marked.length > 1) push("DS-008", marked.slice(0, 3).map(describe).join(" | "), `${marked.length} elements claim the signature moment`, "one moment per page", "MEDIUM");
+  const el = marked.find((node) => node.getAttribute(m.attribute) === declared.kind) ?? marked[0];
+  const where = describe(el);
+  const kind = el.getAttribute(m.attribute);
+  if (kind !== declared.kind) push("DS-008", where, `marked "${kind}" but the lock declares "${declared.kind}"`, "the declared kind");
+  const box = el.getBoundingClientRect();
+  const area = box.width * box.height;
+  const minArea = declared.scale === "bold" ? m.boldMinAreaPx : m.smallMinAreaPx;
+  if (area < minArea) push("DS-008", where, `${Math.round(box.width)}×${Math.round(box.height)} px moment is too small to read as one`, `≥ ${minArea} px²`);
+  const base = options.pass === "base";
+  if (declared.scale === "small" && base && innerWidth >= m.foldMinViewportPx && area > m.smallMaxViewportShare * innerWidth * innerHeight) push("DS-008", where, `a work-surface moment covering ${Math.round((100 * area) / (innerWidth * innerHeight))}% of the screen`, `≤ ${m.smallMaxViewportShare * 100}%: work surfaces stay calm`, "MEDIUM");
+  if (declared.above_fold && base) {
+    const top = box.top + scrollY;
+    const wide = innerWidth >= m.foldMinViewportPx;
+    const limit = wide ? innerHeight - m.foldMinVisiblePx : innerHeight * m.phoneScreens;
+    if (top > limit) push("DS-008", where, `moment starts ${Math.round(top)} px down, below the fold`, wide ? `starts by ${Math.round(limit)} px (first screen)` : `starts within ${m.phoneScreens} screens (${Math.round(limit)} px)`);
+  }
+  const has = (selector) => el.matches(selector) || [...el.querySelectorAll(selector)].some(visible);
+  const media = has(m.media);
+  const inside = [el, ...el.querySelectorAll("*")].filter(visible);
+  const texts = inside.filter((node) => [...node.childNodes].some((child) => child.nodeType === Node.TEXT_NODE && child.textContent.trim()));
+  const need = m.needs[declared.kind];
+  const wants = {
+    media: ["an image, drawing, figure, frame or product view", () => media],
+    data: ["chart, table, figure or readout", () => has(m.data)],
+    control: ["control a reader can operate", () => has(m.control)],
+    "display-type": ["type at display size or above", () => texts.some((node) => Number.parseFloat(getComputedStyle(node).fontSize) >= display.min - sizeTolerance)],
+    motion: ["animation or transition", () => options.pass === "reduced-motion" || inside.some((node) => { const cs = getComputedStyle(node); return cs.animationName !== "none" || cs.transitionDuration.split(",").some((d) => Number.parseFloat(d) > 0); })],
+  }[need];
+  if (wants && !wants[1]()) push("DS-008", where, `declared ${declared.kind} but it holds no ${wants[0]}`, `a ${declared.kind} built from the page's content`);
+  const gradient = (node) => /gradient\(/u.test(getComputedStyle(node).backgroundImage) && !node.matches(".ui-scan, .ui-ruler");
+  const chain = [];
+  for (let node = el; node && node !== document.body && node !== document.documentElement; node = node.parentElement) chain.push(node);
+  const behind = chain.some(gradient) || inside.some((node) => { const b = node.getBoundingClientRect(); return gradient(node) && b.width * b.height >= m.coverShare * area; });
+  const biggest = texts.reduce((best, node) => (Number.parseFloat(getComputedStyle(node).fontSize) > (best ? Number.parseFloat(getComputedStyle(best).fontSize) : 0) ? node : best), null);
+  if (behind && !media && biggest && getComputedStyle(biggest).textAlign === "center") push("DS-008", where, "a generic gradient-and-centred-text hero", "a moment built from this page's content (composition, set piece, data, diagram, motion or object)");
+  return { findings, notVerified };
+}

package/plugin/skills/frontend-ui-ux/scripts/interface-probe-page.mjs

@@ -1,7 +1,7 @@
 // In-page measurement module for scripts/interface-probe.mjs.
 //
 // `measureInterface` runs inside the page under test. The driver serialises it with
-// Function.prototype.toString and evaluates it through the DevTools protocol, so the function stays
+// Function.prototype.toString and evaluates it through agent-browser, so the function stays
 // self-contained: no imports, no closure over module scope, no network. It reads the live DOM,
 // computed styles and same-origin stylesheets and returns plain JSON. It clicks, presses and
 // submits nothing: dialogs are stubbed before the first read, and the only state it touches is the
@@ -698,8 +698,10 @@ export function measureInterface(options) {
       const cluster = clusters.find((entry) => hueDistance(entry.h, tone.h) <= th.hueToleranceDeg);
       if (cluster) cluster.count += 1; else clusters.push({ h: tone.h, count: 1, el });
     }
-    if (clusters.length > th.maxClusters) {
-      add("CF-205", { selector: clusters.map((entry) => selectorOf(entry.el)).slice(0, 3).join(" | "), value: `${clusters.length} saturated hue clusters (${clusters.map((entry) => `${Math.round(entry.h)}°`).join(", ")})`, threshold: `≤ ${th.maxClusters}` });
+    // Rich is the default register; a lock recorded as calm keeps the single-accent limit.
+    const limit = options.density === "calm" ? th.calmMaxClusters : th.maxClusters;
+    if (clusters.length > limit) {
+      add("CF-205", { selector: clusters.map((entry) => selectorOf(entry.el)).slice(0, 3).join(" | "), value: `${clusters.length} saturated hue clusters (${clusters.map((entry) => `${Math.round(entry.h)}°`).join(", ")})`, threshold: `≤ ${limit}` });
     }
   }
 
@@ -800,7 +802,7 @@ export function measureInterface(options) {
   }
 
   // ---- CF-403: hard offset shadow outside an evidenced register ----------------------------------
-  if (on("CF-403")) {
+  if (on("CF-403") && options.register !== "neo-brutalist") {
     const th = t("CF-403");
     const hard = shown.filter((el) => shadowsOf(styleOf(el).boxShadow).some((s) => !s.inset && s.blur === 0 && s.spread === 0 && (Math.abs(s.x) > th.hairlinePx || Math.abs(s.y) > th.hairlinePx) && s.color));
     const bordered = hard.filter((el) => { const style = styleOf(el); return style.borderTopStyle === "solid" && px(style.borderTopWidth) >= th.registerBorderPx; });
@@ -1124,10 +1126,21 @@ export function measureInterface(options) {
 
   // ---- slop register: surfaces and type ---------------------------------------------------------
   const clippedToText = (style) => /text/u.test(`${style.backgroundClip} ${style.webkitBackgroundClip ?? ""}`);
+  // One gradient headline in the palette's own hues is craft. The reflex is a violet stop, the
+  // effect repeated across the page, or a stop the text cannot be read on.
   if (on("SLOP-009")) {
-    for (const el of textElements) {
-      const style = styleOf(el);
-      if (clippedToText(style) && /gradient\(/u.test(style.backgroundImage)) add("SLOP-009", { selector: selectorOf(el), value: `"${snippet(el, 30)}" filled with a gradient`, threshold: "solid text colour" });
+    const th = t("SLOP-009");
+    const violet = t("SLOP-008");
+    const filled = textElements.filter((el) => clippedToText(styleOf(el)) && /gradient\(/u.test(styleOf(el).backgroundImage));
+    for (const el of filled) {
+      const stops = colorsIn(styleOf(el).backgroundImage);
+      const surface = solidBehind(el);
+      const floor = px(styleOf(el).fontSize) >= th.largeFontPx ? th.largeStopContrast : th.minStopContrast;
+      const weakest = surface && stops.length ? Math.min(...stops.map((c) => ratio(blend(c, surface), surface))) : null;
+      const reason = stops.some((c) => spread(c) >= violet.minChannelSpread && hsl(c).h >= violet.hueMin && hsl(c).h <= violet.hueMax) ? "a violet stop"
+        : filled.length > th.maxElements ? `${filled.length} gradient-filled text elements`
+        : weakest !== null && weakest < floor ? `a stop at ${round(weakest)}:1` : null;
+      if (reason) add("SLOP-009", { selector: selectorOf(el), value: `"${snippet(el, 30)}" filled with a gradient (${reason})`, threshold: `≤ ${th.maxElements} gradient headline, palette hues, every stop ≥ ${floor}:1` });
     }
   }
   let bannedHue = false;
@@ -1150,12 +1163,18 @@ export function measureInterface(options) {
   }
   let blob = false;
   if (on("SLOP-011")) {
+    const blobs = [];
     for (const el of shown) {
       const style = styleOf(el);
       if (!/(absolute|fixed)/u.test(style.position) || !/radial-gradient/u.test(style.backgroundImage)) continue;
       if ((el.innerText ?? "").trim() || el.querySelector("img,svg,video,canvas,input,select,textarea,button,a[href]")) continue;
       const faint = Number(style.opacity) < t("SLOP-011").maxOpacity || colorsIn(style.backgroundImage).every((c) => c.a < t("SLOP-011").maxOpacity);
-      if (faint) { blob = true; candidate("SLOP-011", { selector: selectorOf(el), value: "unbound faint radial gradient" }); }
+      if (faint) blobs.push(el);
+    }
+    // One atmosphere layer is craft; scattered floating blobs are the generic decoration.
+    if (blobs.length >= t("SLOP-011").minCount) {
+      blob = true;
+      for (const el of blobs) candidate("SLOP-011", { selector: selectorOf(el), value: `unbound faint radial gradient (${blobs.length} on the page)` });
     }
   }
   if (on("SLOP-012") && (blob || bannedHue)) {
@@ -1204,8 +1223,8 @@ export function measureInterface(options) {
       }
     }
     for (const entry of scopes.values()) {
-      const hit = entry.b.length >= 1 ? entry.b : entry.a.length >= th.minCount ? entry.a : entry.c.length >= th.minCount ? entry.c : null;
-      if (hit) add("SLOP-015", { selector: selectorOf(hit[0]), value: `${hit.length} rounded element(s) with a coloured accent stripe`, threshold: `< ${th.minCount} per scope (inset form: none)` });
+      const hit = entry.b.length >= th.insetMinCount ? entry.b : entry.a.length >= th.minCount ? entry.a : entry.c.length >= th.minCount ? entry.c : null;
+      if (hit) add("SLOP-015", { selector: selectorOf(hit[0]), value: `${hit.length} rounded element(s) with a coloured accent stripe`, threshold: `< ${th.minCount} per scope (inset form: < ${th.insetMinCount})` });
     }
   }
   const declaredFaces = new Map();
@@ -1444,6 +1463,8 @@ export function measureInterface(options) {
     for (const svg of shown.filter((el) => el.matches("svg"))) {
       const r = svg.getBoundingClientRect();
       if (r.width < th.minSizePx || r.height < th.minSizePx || svg.querySelector("pattern")) continue;
+      // A drawing that names what it shows is an authored illustration; the generic stack is unnamed.
+      if (svg.querySelector(":scope > title") || ((svg.getAttribute("role") === "img") && (svg.getAttribute("aria-label")?.trim() || svg.hasAttribute("aria-labelledby")))) continue;
       const shapes = [...svg.querySelectorAll("rect,circle,ellipse,polygon")];
       const fills = new Set(shapes.map((shape) => getComputedStyle(shape).fill).filter((fill) => fill && !/^(none|transparent|rgba\(0, 0, 0, 0\))$/u.test(fill)));
       if (shapes.length >= th.minShapes && fills.size >= th.minFills && svg.querySelectorAll("text,tspan").length <= th.maxText) candidate("SLOP-051", { selector: selectorOf(svg), value: `${shapes.length} primitives in ${fills.size} fills` });

package/plugin/skills/frontend-ui-ux/scripts/interface-probe-rules.mjs

@@ -35,13 +35,13 @@ export const RULES = Object.freeze({
   "CF-201": { title: "Text contrast below WCAG 2", severity: "HIGH", tier: "derived", threshold: { body: 4.5, large: 3, largeFontPx: 24, boldLargeFontPx: 18.5, boldWeight: 700, largeSeverity: "MEDIUM" }, fix: "Darken or lighten the text or its surface until the ratio clears 4.5:1 (3:1 for large text)." },
   "CF-202": { title: "Focus indicator missing or weak", severity: "HIGH", tier: "measured", threshold: { minWidthPx: 2, minContrast: 3, weakSeverity: "MEDIUM", sample: 5 }, fix: "Give :focus-visible a visible change; a custom ring needs 2px or more and 3:1 against the colour just outside it." },
   "CF-204": { title: "Text over a gradient below WCAG 2", severity: "HIGH", tier: "derived", threshold: { body: 4.5, large: 3 }, fix: "Put the text on a solid scrim or move it off the gradient's light end until the worst stop clears the floor." },
-  "CF-205": { title: "More than one accent colour", severity: "MEDIUM", tier: "measured", threshold: { maxClusters: 1, hueToleranceDeg: 15, minSaturation: 0.4, minSurfacePx: 24, maxPillPx: 32, minLightness: 0.15, maxLightness: 0.85, statusTokens: ["success", "warning", "warn", "error", "danger", "destructive", "info", "critical"] }, fix: "Keep one saturated accent for actions in a view; move the other filled surfaces to neutrals." },
+  "CF-205": { title: "More accent hue families than the register holds", severity: "MEDIUM", tier: "measured", threshold: { maxClusters: 4, calmMaxClusters: 1, hueToleranceDeg: 15, minSaturation: 0.4, minSurfacePx: 24, maxPillPx: 32, minLightness: 0.15, maxLightness: 0.85, statusTokens: ["success", "warning", "warn", "error", "danger", "destructive", "info", "critical"] }, fix: "Hold a view to four saturated hue families (one in a calm lock); fold the extra fills into a family the page already uses or a neutral." },
 
   // Craft floor: spacing and surfaces
   "CF-301": { title: "Spacing off the 4px scale", severity: "LOW", tier: "measured", threshold: { stepPx: 4, tolerancePx: 1, minPx: 4, lowMax: 3, manySeverity: "MEDIUM" }, fix: "Snap padding, gaps and margins to the 4px scale (4, 8, 12, 16, 24, 32 …)." },
   "CF-304": { title: "Heading sits closer to the block above", severity: "LOW", tier: "measured", threshold: { ratio: 0.75, deficitPx: 12, labelMaxPx: 60, labelGapPx: 28 }, fix: "Give the heading more space above than below so it binds to the content it introduces." },
   "CF-401": { title: "Nested radius not concentric", severity: "LOW", tier: "measured", threshold: { tolerancePx: 2, maxParentPaddingPx: 24, edgeTolerancePx: 2, minChildPx: 32 }, fix: "Set the inner radius to the outer radius minus the padding between them." },
-  "CF-403": { title: "Hard offset shadow outside a register", severity: "MEDIUM", tier: "measured", threshold: { hairlinePx: 1, registerCount: 3, registerBorderPx: 2 }, fix: "Use a soft neutral shadow or none, unless the direction records a neo-brutalist register.", note: "clears when the recorded direction names a neo-brutalist register" },
+  "CF-403": { title: "Hard offset shadow outside a register", severity: "MEDIUM", tier: "measured", threshold: { hairlinePx: 1, registerCount: 3, registerBorderPx: 2 }, fix: "Use a soft neutral shadow or none, unless the direction records a neo-brutalist register.", note: "clears when the recorded direction names a neo-brutalist register: a design.lock.json with elevation \"offset\" (the neo-brutalism house style) records one" },
   "CF-404": { title: "Glow on the primary action", severity: "LOW", tier: "measured", threshold: { minBlurPx: 16, minSaturation: 0.4, maxOffsetPx: 2, minAlpha: 0.2 }, fix: "Replace the coloured halo with a small neutral shadow or a border; the button's fill already carries the emphasis." },
   "CF-406": { title: "Blurred modal scrim", severity: "LOW", tier: "measured", threshold: { minCover: 0.9 }, fix: "Use a solid or near-solid scrim (for example rgb(0 0 0 / 0.5)) instead of backdrop-filter: blur." },
 
@@ -62,14 +62,26 @@ export const RULES = Object.freeze({
   "CF-806": { title: "Placeholder is the only label", severity: "MEDIUM", tier: "measured", threshold: null, fix: "Add a real <label> (or aria-label) and keep the placeholder as an example value." },
   "CF-807": { title: "Placeholder contrast below 4.5:1", severity: "MEDIUM", tier: "derived", threshold: { min: 4.5 }, fix: "Darken the placeholder colour until it reaches 4.5:1 against the field." },
 
+  // Design lock (references/house-styles.md). These run only when the page's directory holds a
+  // design.lock.json written by scripts/design-lock.mjs, or when --lock names one; the lock is the
+  // run's own declaration, so drifting from it is a defect the build introduced.
+  "DS-001": { title: "Design lock not applied", severity: "HIGH", tier: "measured", threshold: { property: "--ui-lock" }, fix: "Link ui/tokens.css (written by scripts/design-lock.mjs) before any other stylesheet so the page renders the locked style." },
+  "DS-002": { title: "Font family outside the lock", severity: "HIGH", tier: "measured", threshold: null, fix: "Use var(--font-text), var(--font-display) or var(--font-mono); a new family needs a new lock, not a page rule." },
+  "DS-003": { title: "Colour outside the locked palette", severity: "HIGH", tier: "measured", threshold: { channelTolerance: 8, minAlpha: 0.05, highCount: 4, lowSeverity: "MEDIUM" }, fix: "Replace the literal colour with the var(--c-*) role that means the same thing; a colour with no role is a decoration to delete." },
+  "DS-004": { title: "Font size off the locked scale", severity: "MEDIUM", tier: "measured", threshold: { tolerancePx: 0.5 }, fix: "Use a var(--fs-*) step, or var(--fs-display) for the one display title." },
+  "DS-005": { title: "Corner radius off the lock", severity: "LOW", tier: "measured", threshold: { tolerancePx: 0.5 }, fix: "Use a var(--radius-*) value (inner radius one step below its container) or make it fully round." },
+  "DS-006": { title: "Starter slot left in the page", severity: "HIGH", tier: "measured", threshold: { pattern: "\\{\\{(?! )[^{}\\n]{1,80}(?<! )\\}\\}" }, fix: "Replace every {{slot}} from the kit layout with real content, or delete the element that holds it." },
+  "DS-007": { title: "Elevation outside the lock grammar", severity: "MEDIUM", tier: "measured", threshold: { hairlinePx: 1 }, fix: "Use var(--shadow-raised), var(--shadow-overlay) or var(--shadow-control): a flat lock takes no blurred or offset shadow, an offset lock takes no blurred one." },
+  "DS-008": { title: "Signature moment missing, buried or generic", severity: "HIGH", tier: "measured", threshold: { attribute: "data-ui-moment", boldMinAreaPx: 40000, smallMinAreaPx: 4800, smallMaxViewportShare: 0.5, foldMinViewportPx: 1024, foldMinVisiblePx: 120, phoneScreens: 1.5, coverShare: 0.5, needs: { "hero-composition": "media", "type-set-piece": "display-type", "data-moment": "data", diagram: "media", "motion-detail": "motion", "interactive-object": "control", chart: "data", "empty-state": null, "header-detail": null }, media: "svg, img, canvas, video, picture, figure, table, [role=\"img\"], .ui-pixel, .ui-frame, .ui-readout, .ui-panel, .ui-chart, .ui-meter, .ui-sticker, .ui-bignum", data: "svg, canvas, table, [role=\"img\"], .ui-chart, .ui-meter, .ui-readout, .ui-bignum", control: "input, select, textarea, details, [role=\"slider\"], [role=\"switch\"], [role=\"tab\"], [aria-pressed], [aria-expanded]" }, fix: "Record the page's one signature moment with design-lock.mjs (--moment or the moment command), build it from this page's content, mark that element with data-ui-moment=\"<kind>\", and keep a read-once page's moment in the first screen." },
+
   // Slop register. Only SLOP-057, SLOP-058 and SLOP-059 can be HIGH.
   "SLOP-002": { title: "Identical icon-heading-text tiles", severity: "MEDIUM", tier: "measured", threshold: { minTiles: 4, sizeTolerancePx: 4 }, fix: "Vary tile size or structure, or present the items as a list or table." },
   "SLOP-008": { title: "Reflex violet accent", severity: "MEDIUM", tier: "measured", threshold: { hueMin: 260, hueMax: 310, minChannelSpread: 50, headingFontPx: 20 }, fix: "Swap the violet for a neutral surface plus one hue from the actual brand." },
-  "SLOP-009": { title: "Gradient-filled text", severity: "MEDIUM", tier: "measured", threshold: null, fix: "Use a solid colour and a weight or size change for emphasis." },
-  "SLOP-010": { title: "Glow halo repeated across elements", severity: "MEDIUM", tier: "measured", threshold: { recurCount: 2 }, fix: "Drop the coloured halo; use a neutral offset shadow or none." },
-  "SLOP-011": { title: "Floating blob decoration", severity: "MEDIUM", tier: "derived", threshold: { maxOpacity: 0.3 }, fix: "Remove the blob or tie it to a real focal point.", judgment: "keep only with a stated atmospheric or focal purpose" },
+  "SLOP-009": { title: "Reflex gradient-filled text", severity: "MEDIUM", tier: "measured", threshold: { maxElements: 1, minStopContrast: 4.5, largeStopContrast: 3, largeFontPx: 24 }, fix: "Keep one gradient headline in the palette's own hues with every stop readable, or use a solid colour." },
+  "SLOP-010": { title: "Glow halo repeated across elements", severity: "MEDIUM", tier: "measured", threshold: { recurCount: 3 }, fix: "Keep a glow for the one surface it lights; drop the halo from the other controls and headings." },
+  "SLOP-011": { title: "Floating blob decoration", severity: "MEDIUM", tier: "derived", threshold: { maxOpacity: 0.3, minCount: 2 }, fix: "Keep one atmosphere layer tied to the focal point; remove the scattered extras.", judgment: "keep only with a stated atmospheric or focal purpose" },
   "SLOP-012": { title: "Decorative dot or grid background", severity: "MEDIUM", tier: "measured", threshold: { maxCellPx: 48, hairlinePx: 2, dataSvgPx: 48 }, fix: "Remove the pattern unless it stands in for a real chart or map." },
-  "SLOP-015": { title: "Accent stripe on rounded cards", severity: "MEDIUM", tier: "measured", threshold: { minStripePx: 2, neutralSidePx: 1, minSaturation: 0.3, minCount: 2, barMinPx: 3, barMaxPx: 12, barInsetPx: 20, minChannelSpread: 30, minAlpha: 0.1 }, fix: "Drop the coloured stripe; carry emphasis with the card fill or an icon." },
+  "SLOP-015": { title: "Accent stripe on rounded cards", severity: "MEDIUM", tier: "measured", threshold: { minStripePx: 2, neutralSidePx: 1, minSaturation: 0.3, minCount: 3, insetMinCount: 2, barMinPx: 3, barMaxPx: 12, barInsetPx: 20, minChannelSpread: 30, minAlpha: 0.1 }, fix: "Drop the coloured stripe; carry emphasis with the card fill or an icon." },
   "SLOP-016": { title: "Reflex default font", severity: "MEDIUM", tier: "measured", threshold: { families: ["inter", "roboto", "open sans", "lato", "montserrat", "arial", "helvetica", "fraunces", "mona sans", "plus jakarta sans", "space grotesk", "recoleta", "instrument sans", "instrument serif"] }, fix: "Choose a face that suits the product, or record why the common one was kept.", judgment: "not a finding when the design records a reason for the font" },
   "SLOP-019": { title: "Too many font families", severity: "MEDIUM", tier: "measured", threshold: { max: 3 }, fix: "Cut the page back to at most three families." },
   "SLOP-020": { title: "Long all-caps text", severity: "LOW", tier: "measured", threshold: { maxChars: 40 }, fix: "Keep uppercase for short labels; sentence-case the rest." },
@@ -90,7 +102,7 @@ export const RULES = Object.freeze({
   "SLOP-046": { title: "Decorative gauge or sparkline", severity: "MEDIUM", tier: "derived", threshold: { sparklineMaxPx: 64 }, fix: "Remove it unless it encodes a real, current data point; then label the value.", judgment: "clears when it encodes a real data point" },
   "SLOP-047": { title: "Illegible logo ticker", severity: "MEDIUM", tier: "measured", threshold: { maxLogos: 6, minLogoPx: 20, viewport: "1440" }, fix: "Slow it down, enlarge the logos, or show them as a static row." },
   "SLOP-048": { title: "Autoplay dots with no binding", severity: "LOW", tier: "derived", threshold: { dotMaxPx: 16, minDots: 2 }, fix: "Remove the dots or make each one a named, focusable button that picks its slide." },
-  "SLOP-051": { title: "Illustration stacked from primitives", severity: "MEDIUM", tier: "derived", threshold: { minShapes: 8, minSizePx: 200, minFills: 3, maxText: 2 }, fix: "Use a drawn or licensed illustration, or simplify it.", judgment: "a data graphic or diagram with an honest shape count clears it" },
+  "SLOP-051": { title: "Unlabelled illustration stacked from primitives", severity: "MEDIUM", tier: "derived", threshold: { minShapes: 8, minSizePx: 200, minFills: 3, maxText: 2 }, fix: "Name what the drawing shows (role=img with aria-label, or a <title>), or replace a generic primitive stack with a drawing of the subject.", judgment: "a data graphic or diagram with an honest shape count clears it" },
   "SLOP-052": { title: "Organic clip-path mask", severity: "LOW", tier: "measured", threshold: { minVertices: 10, grid: 25, gridTolerance: 0.5, minCurves: 3 }, fix: "Use a real photographic crop or a simple deliberate shape." },
   "SLOP-053": { title: "Emoji used as an icon", severity: "LOW", tier: "measured", threshold: { maxControlPx: 32 }, fix: "Use the project's icon set instead of emoji.", judgment: "not a finding when the brief asks for emoji" },
   "SLOP-057": { title: "Broken image", severity: "HIGH", tier: "measured", threshold: null, fix: "Fix the image source or remove the element." },

package/plugin/skills/frontend-ui-ux/scripts/interface-probe-static.mjs

@@ -91,9 +91,12 @@ export const DETECTORS = Object.freeze({
   "SLOP-040": (text) => every(/>[^<>{}]*(?:—|(\S)\s+–\s+(\S))[^<>{}]*</gu, copyOf(text), (m) => m[0].slice(1, -1).trim())
     .filter(({ value }) => value.includes("—") || [...value.matchAll(/(\S)\s+–\s+(\S)/gu)].some((m) => !(/\d/u.test(m[1]) && /\d/u.test(m[2])))),
   "SLOP-036": (text) => every(new RegExp(`>[^<>{}]*?(?<![\\p{L}\\p{N}])(${RULES["SLOP-036"].threshold.phrases.map(escapeRegExp).join("|")})(?![\\p{L}\\p{N}])[^<>{}]*<`, "giu"), copyOf(text), (m) => m[1]),
+  "DS-006": (text) => every(new RegExp(RULES["DS-006"].threshold.pattern, "gu"), copyOf(text)),
 });
 
 export const STATIC_RULES = Object.freeze(Object.keys(DETECTORS));
+// A detector listed here reads only these file types: framework templates use {{ }} on purpose.
+const DETECTOR_EXTENSIONS = Object.freeze({ "DS-006": [".html", ".htm"] });
 
 export function staticProbe(target) {
   const files = listSourceFiles(target);
@@ -103,6 +106,7 @@ export function staticProbe(target) {
   for (const file of files) {
     const text = readFileSync(file, "utf8");
     for (const id of STATIC_RULES) {
+      if (DETECTOR_EXTENSIONS[id] && !DETECTOR_EXTENSIONS[id].includes(extname(file).toLowerCase())) continue;
       for (const hit of DETECTORS[id](text)) {
         const selector = `${relative(root, file) || file}:${lineOf(text, hit.index)}`;
         if (RULES[id].judgment) {

package/plugin/skills/frontend-ui-ux/scripts/interface-probe.mjs

@@ -3,7 +3,7 @@
 // in-page measurement module, saves one screenshot per viewport, and reports findings.
 //
 //   node interface-probe.mjs <page.html | directory | http(s) URL> [--out <dir>] [--static]
-//                            [--viewports 320,390,...] [--json]
+//                            [--viewports 320,390,...] [--lock design.lock.json] [--json]
 //
 // Exit 0: all seven matrix rows ran and no measured or derived HIGH finding remains. Exit 1: at
 // least one such HIGH finding (this wins over an incomplete matrix). Exit 2: BLOCKED, printed as
@@ -13,12 +13,13 @@
 // chrome-driver.mjs (CHROME_PATH overrides). The browser is only resized, opened, read, hovered
 // (CF-506) and screenshotted; nothing is clicked, pressed or submitted.
 import { spawn } from "node:child_process";
-import { existsSync, mkdirSync, mkdtempSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 import process from "node:process";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { ChromeSession, probeChrome } from "./chrome-driver.mjs";
+import { measureLock } from "./interface-probe-lock.mjs";
 import { measureInterface, readHover } from "./interface-probe-page.mjs";
 import { BLOCKED_REASON, EXIT, LIMITS, MATRIX, RULES, SEVERITY_ORDER } from "./interface-probe-rules.mjs";
 import { staticProbe } from "./interface-probe-static.mjs";
@@ -27,20 +28,37 @@ const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
 const COMMAND_TIMEOUT_MS = 30_000;
 
 export function parseArgs(argv) {
-  const options = { target: null, out: null, static: false, json: false, viewports: null };
+  const options = { target: null, out: null, static: false, json: false, viewports: null, lock: null };
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index];
     if (arg === "--out") options.out = argv[++index];
     else if (arg === "--static") options.static = true;
     else if (arg === "--json") options.json = true;
+    else if (arg === "--lock") options.lock = argv[++index];
     else if (arg === "--viewports") options.viewports = argv[++index]?.split(",").map((value) => value.trim()).filter(Boolean);
     else if (!arg.startsWith("--") && options.target === null) options.target = arg;
     else throw new Error(`unknown argument ${arg}`);
   }
-  if (!options.target) throw new Error("usage: interface-probe.mjs <page.html | directory | URL> [--out <dir>] [--static] [--viewports ids] [--json]");
+  if (!options.target) throw new Error("usage: interface-probe.mjs <page.html | directory | URL> [--out <dir>] [--static] [--viewports ids] [--lock design.lock.json] [--json]");
   return options;
 }
 
+// The design lock beside the page (or named by --lock) turns on the DS-* rules. A lock that cannot
+// be read is reported, never silently skipped.
+export function findLock(target, explicit) {
+  const candidates = explicit ? [resolve(explicit)] : [target.root, target.sourceRoot && (existsSync(target.sourceRoot) && statSync(target.sourceRoot).isFile() ? dirname(target.sourceRoot) : target.sourceRoot)]
+    .filter(Boolean).map((dir) => join(dir, "design.lock.json"));
+  const path = candidates.find((candidate) => existsSync(candidate));
+  if (!path) return { lock: null, path: null, error: explicit ? `lock not found: ${explicit}` : null };
+  try {
+    const lock = JSON.parse(readFileSync(path, "utf8"));
+    if (lock.schema_id !== "litfamily.design-lock/v1" || typeof lock.style !== "string") return { lock: null, path, error: "design.lock.json is not a litfamily.design-lock/v1 file" };
+    return { lock, path, error: null };
+  } catch (error) {
+    return { lock: null, path, error: `design.lock.json unreadable: ${error.message}` };
+  }
+}
+
 // A local target is served from its directory; a directory serves its built or root index.html.
 export function resolveTarget(target) {
   if (/^https?:\/\//iu.test(target)) return { url: target, root: null, page: null, sourceRoot: null };
@@ -69,14 +87,15 @@ function startServer(root) {
   });
 }
 
-async function probeViewport(chrome, url, viewport, outDir) {
+async function probeViewport(chrome, url, viewport, outDir, lock) {
   let tab = null;
   try {
     tab = await chrome.newTab();
     await tab.setup(viewport);
     await tab.open(url, LIMITS.settleMs);
     const hover = RULES["CF-506"]?.threshold;
-    const options = { rules: RULES, limits: LIMITS, touch: viewport.touch, pass: viewport.pass, hoverSample: hover && viewport.id === hover.viewport ? hover.sample : 0 };
+    // A lock with offset elevation is the recorded neo-brutalist register CF-403 accepts.
+    const options = { rules: RULES, limits: LIMITS, touch: viewport.touch, pass: viewport.pass, hoverSample: hover && viewport.id === hover.viewport ? hover.sample : 0, register: lock?.elevation === "offset" ? "neo-brutalist" : null, density: lock?.density ?? null };
     let measured = await tab.evaluate(measureInterface, options);
     // A page still loading after the settle wait gets exactly one more wait, then counts as unsettled.
     if (measured.ready === "loading") {
@@ -84,6 +103,19 @@ async function probeViewport(chrome, url, viewport, outDir) {
       measured = await tab.evaluate(measureInterface, options);
       if (measured.ready === "loading") return { viewport: viewport.id, error: "page did not settle" };
     }
+    if (lock) {
+      let locked;
+      try {
+        locked = await tab.evaluate(measureLock, { rules: RULES, limits: LIMITS, lock, pass: viewport.pass });
+      } catch (error) {
+        locked = { error: error.message };
+      }
+      if (locked.error) measured.notVerified.push({ rule: "DS-001", reason: `design-lock pass failed: ${locked.error.slice(0, 120)}` });
+      else {
+        measured.findings.push(...locked.findings);
+        measured.notVerified.push(...locked.notVerified);
+      }
+    }
     const path = join(outDir, "screenshots", `${viewport.id}.png`);
     let shot = true;
     try { await tab.screenshot(path); } catch { shot = false; }
@@ -156,10 +188,26 @@ export function renderTable(report) {
   if (judgment.length) lines.push("", "Judgment calls (Inferred until a reviewer decides; severity applies only once confirmed):", ...grouped(judgment));
   if (unrun.length) lines.push("", "Not verified:", ...grouped(unrun));
   const high = blockingHigh(report.findings).length;
+  const shots = (report.manifest.screenshots ?? []).filter(({ viewport }) => ["1440", "390", "320"].includes(viewport));
+  if (shots.length) {
+    lines.push("", "Look before calling it done (open these screenshots; fix the two worst answers, re-run the probe, two look rounds at most):");
+    for (const shot of shots) lines.push(`- ${shot.viewport}: ${shot.path}`);
+    lines.push(...LOOK_RUBRIC.map(([id, text]) => `${id} ${text}`));
+  }
   lines.push("", `Verdict: ${report.manifest.blocked_reason ? `BLOCKED: ${report.manifest.blocked_reason}` : high ? `Block (${high} HIGH)` : "Approve (0 HIGH)"}`);
   return lines.join("\n");
 }
 
+// The fixed look rubric printed under every rendered run: concrete questions a screenshot answers.
+export const LOOK_RUBRIC = Object.freeze([
+  ["LOOK-1", "One focal point: the signature moment (data-ui-moment) is where the eye lands first at 1440 and at 390; nothing else competes with it."],
+  ["LOOK-2", "Shared edges: section content starts on the same left edge at 1440; no block floats on a width of its own."],
+  ["LOOK-3", "Grouping by space: gaps between groups are visibly larger than gaps inside them; no empty band separates nothing."],
+  ["LOOK-4", "Kit, not costume: every block is a kit part or a page rule on the locked tokens; nothing decorative without a job."],
+  ["LOOK-5", "Composed mobile: at 390 and 320 the title breaks well, navigation and tables stay usable, nothing is a squeezed desktop."],
+  ["LOOK-6", "Specific content: names, numbers and copy belong to this brief; no filler and no leftover slot."],
+]);
+
 // C.5: a driver or entry blocker is exit 2; otherwise a measured or derived HIGH is exit 1 (even
 // with rows missing); otherwise any missing matrix row is exit 2; otherwise exit 0.
 export function decideExit({ findings, viewportsRun, blockedReason }) {
@@ -185,8 +233,12 @@ export async function runProbe(options) {
     screenshots: [],
     exit_code: EXIT.blocked,
     blocked_reason: null,
+    design_lock: null,
   };
   const findings = [];
+  const lockState = findLock(target, options.lock);
+  if (lockState.lock) manifest.design_lock = { path: lockState.path, style: lockState.lock.style, family: lockState.lock.family ?? null };
+  else manifest.not_verified.push({ rule: "DS-001", reason: lockState.error ?? "no design.lock.json beside the page; lock conformance not checked" });
 
   const driver = options.static || target.missing ? null : probeChrome();
   const driverReady = driver?.status === "available";
@@ -209,7 +261,7 @@ export async function runProbe(options) {
           continue;
         }
         const passStarted = Date.now();
-        const result = await probeViewport(chrome, url, viewport, outDir);
+        const result = await probeViewport(chrome, url, viewport, outDir, lockState.lock);
         if (result.error) {
           manifest.not_verified.push({ rule: "*", viewport: viewport.id, reason: result.error.slice(0, 160) });
           continue;

package/plugin/skills/frontend-ui-ux/scripts/pixel-art.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+// Pixel art for the field-notes style: turns a character grid into an inline SVG whose cells are
+// filled with the locked colour roles, so the motif stays crisp at any size and follows dark mode.
+//
+//   node pixel-art.mjs <grid.txt> --label "<what it shows>" [--cell 8]
+//
+// Grid characters: i ink, a accent, b second accent, m support (mist), s sunken, p surface,
+// c canvas, l line-strong, 2 ink-2; `.` or space is empty. Every row must have the same width. The SVG
+// renders at cell × columns CSS px by default; never let it drop below 6 px per cell.
+import { readFileSync, realpathSync } from "node:fs";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+export const PIXEL_ROLES = Object.freeze({ i: "ink", a: "accent", b: "accent-2", m: "support", s: "sunken", p: "surface", c: "canvas", l: "line-strong", 2: "ink-2" });
+
+export function pixelSvg(grid, { label, cell = 8 } = {}) {
+  if (!label || !label.trim()) throw new Error("--label is required: say what the motif shows");
+  const rows = grid.replace(/\r/gu, "").split("\n").filter((row) => row.trim().length > 0);
+  if (rows.length === 0) throw new Error("the grid is empty");
+  const width = Math.max(...rows.map((row) => row.length));
+  if (rows.some((row) => row.trimEnd().length > width)) throw new Error("rows differ in width");
+  if (cell < 6) throw new Error("cells under 6 px stop reading as pixel art");
+  const rects = [];
+  rows.forEach((row, y) => {
+    const padded = row.padEnd(width, ".");
+    let x = 0;
+    while (x < width) {
+      const char = padded[x];
+      const role = PIXEL_ROLES[char];
+      if (char !== "." && char !== " " && !role) throw new Error(`unknown grid character "${char}" at row ${y + 1}`);
+      let end = x + 1;
+      while (end < width && padded[end] === char) end += 1;
+      if (role) rects.push(`<rect x="${x}" y="${y}" width="${end - x}" height="1" style="fill: var(--c-${role})"/>`);
+      x = end;
+    }
+  });
+  const escaped = label.replace(/[&<>"]/gu, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
+  return `<svg class="ui-pixel" viewBox="0 0 ${width} ${rows.length}" width="${width * cell}" height="${rows.length * cell}" role="img" aria-label="${escaped}" shape-rendering="crispEdges">${rects.join("")}</svg>`;
+}
+
+const startedDirectly = () => {
+  try {
+    return Boolean(process.argv[1]) && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+};
+
+if (startedDirectly()) {
+  const args = process.argv.slice(2);
+  const option = (name) => { const i = args.indexOf(`--${name}`); return i >= 0 ? args[i + 1] : undefined; };
+  const file = args.find((arg, i) => !arg.startsWith("--") && !args[i - 1]?.startsWith("--"));
+  try {
+    if (!file) throw new Error("usage: pixel-art.mjs <grid.txt> --label \"<what it shows>\" [--cell 8]");
+    process.stdout.write(`${pixelSvg(readFileSync(file, "utf8"), { label: option("label"), cell: Number(option("cell") ?? 8) })}\n`);
+  } catch (error) {
+    console.error(`pixel-art: ${error.message}`);
+    process.exitCode = 1;
+  }
+}