dontmakeitugly 0.1.0 → 0.2.0

package/README.md

@@ -8,7 +8,7 @@ npx dontmakeitugly init first-vibe-coded-app   # DESIGN.md + check config + AGEN
 npx dontmakeitugly check                       # .dmiu/report.md for the agent to read
 ```
 
-`init` fetches a pack from [dontmakeitugly.com/packs](https://dontmakeitugly.com/packs): a `DESIGN.md` on Google's open format, reference screens, and a `dmiu.config.json`. It appends an instruction block to `AGENTS.md` (and `CLAUDE.md` if you have one) telling the agent to read the contract before writing UI and to run the check before saying it's done.
+`init` fetches a pack from [dontmakeitugly.com/packs](https://dontmakeitugly.com/packs): a `DESIGN.md` on Google's open format, a `dmiu.config.json`, the reference screens as links in `.dmiu/references/README.md` (never downloaded; they belong to their owners), and `.dmiu/critic.md`. It appends an instruction block to `AGENTS.md` (and `CLAUDE.md` if you have one) telling the agent to read the contract before writing UI, discover a direction before the first layout, run the check before saying it's done, and run the critic once the check is clean.
 
 `check` screenshots your routes at desktop and mobile widths with Playwright and runs deterministic checks derived from the DESIGN.md tokens:
 
@@ -16,10 +16,15 @@ npx dontmakeitugly check                       # .dmiu/report.md for the agent t
 - colours off the palette, within a tolerance (error above a handful, else warning)
 - WCAG AA contrast on text (error)
 - purple/blue gradients (error) and any gradient when the contract forbids them (warning)
+- coloured glows: a chromatic box- or text-shadow with a wide blur (error when the contract forbids gradients, else warning)
+- glassmorphism: backdrop blur on a translucent surface (same rule)
+- card soup: three or more sibling cards that each open with an icon, then a heading, then a paragraph (warning; three-column layouts can be legitimate)
 - animations that keep running under `prefers-reduced-motion: reduce` (error)
 - padding and gaps off the spacing scale, radii off the rounded scale (warnings)
 - screenshot baselines with pixel diffs (error above the threshold; `--update-baselines` to accept)
 
 Skip an element and its subtree with `data-design-check="ignore"`, or add selectors to `ignore` in `dmiu.config.json`.
 
-Chromium is needed once: `npx playwright install chromium`.
+The report ends with the path of every screenshot it took. When the report has zero errors, the agent hands those screenshots and the pack's reference previews to `.dmiu/critic.md`: a prompt for a subagent in a fresh context that ranks them by polish and names the three biggest gaps. It is advisory and it never calls a model from the CLI; the agent you already run does the critique. The check stays the gate.
+
+The first `check` installs a headless Chromium for Playwright (about 200 MB) if it isn't already there.

package/dist/check.js

@@ -1,25 +1,43 @@
 import path from "node:path";
 import fs from "node:fs";
+import { execFileSync } from "node:child_process";
+import { createRequire } from "node:module";
 import { chromium } from "playwright";
 import { loadConfig } from "./config.js";
 import { loadContract } from "./contract.js";
 import { collect } from "./collect.js";
 import { checkColors, checkContrast, checkFonts, checkGradients, checkMotion, checkRadius, checkSpacing } from "./checks/style.js";
 import { checkBaseline } from "./checks/baseline.js";
+import { checkCardSoup, checkGlass, checkGlow } from "./checks/tells.js";
 import { summarise, writeReport } from "./report.js";
 function slugify(s) {
     return s.replace(/^\//, "").replace(/[^a-z0-9]+/gi, "-").replace(/^-|-$/g, "") || "home";
 }
-async function launch() {
+function isMissingBrowser(e) {
+    return /Executable doesn't exist|browserType\.launch|playwright install/.test(e.message ?? "");
+}
+/** Installs the Chromium build that this copy of Playwright expects. */
+function installChromium(log) {
+    const require = createRequire(import.meta.url);
+    // "playwright/cli" is not an exported subpath; go via the package root.
+    const cli = path.join(path.dirname(require.resolve("playwright/package.json")), "cli.js");
+    log("Chromium is not installed for Playwright yet. Installing the headless build once (about 200 MB)…");
+    execFileSync(process.execPath, [cli, "install", "chromium", "--only-shell"], { stdio: "inherit" });
+}
+async function launch(log) {
     try {
         return await chromium.launch();
     }
     catch (e) {
-        const msg = e.message;
-        if (/Executable doesn't exist|browserType.launch/.test(msg)) {
-            throw new Error("Chromium is not installed for Playwright. Run: npx playwright install chromium");
+        if (!isMissingBrowser(e))
+            throw e;
+        try {
+            installChromium(log);
+        }
+        catch (installError) {
+            throw new Error(`Chromium could not be installed automatically (${installError.message.split("\n")[0]}). Run: npx playwright install chromium`);
         }
-        throw e;
+        return chromium.launch();
     }
 }
 async function reachable(url) {
@@ -52,7 +70,7 @@ export async function runCheck(opts) {
     const outDir = path.resolve(opts.cwd, cfg.outDir);
     const shotsDir = path.join(outDir, "screenshots");
     fs.mkdirSync(shotsDir, { recursive: true });
-    const browser = await launch();
+    const browser = await launch(log);
     const pages = [];
     try {
         for (const vp of cfg.viewports) {
@@ -85,6 +103,9 @@ export async function runCheck(opts) {
                     checkColors(collected.samples, contract, cfg.tolerance.color),
                     checkContrast(collected.samples),
                     checkGradients(collected.samples, cfg.forbidGradients),
+                    checkGlow(collected.samples, cfg.forbidGradients),
+                    checkGlass(collected.samples, cfg.forbidGradients),
+                    checkCardSoup(collected.cardGroups),
                     checkMotion(reducedCollected.runningAnimations, collected.samples),
                     checkSpacing(collected.samples, contract, cfg.tolerance.spacing),
                     checkRadius(collected.samples, contract),
@@ -106,6 +127,7 @@ export async function runCheck(opts) {
         designMd: cfg.designMd,
         contract: { name: contract.name, fonts: contract.fonts, palette: contract.palette.length, spacing: contract.spacing, radii: contract.radii },
         summary,
+        critic: fs.existsSync(path.join(outDir, "critic.md")) ? path.relative(opts.cwd, path.join(outDir, "critic.md")) : null,
         pages,
     };
     const files = writeReport(outDir, report);

package/dist/checks/tells.js

@@ -0,0 +1,106 @@
+import { parse as parseColor, converter, formatHex } from "culori";
+import { result } from "./types.js";
+/**
+ * The "tells" of a generated interface that the pack contracts forbid in prose:
+ * coloured glows, frosted glass and rows of icon cards. The severity of the
+ * first two follows the contract's stance on gradients, since the same Don't
+ * line lists them together.
+ */
+const toOklch = converter("oklch");
+const toRgb = converter("rgb");
+/** Split a comma-separated CSS list without breaking inside colour functions. */
+function splitList(css) {
+    const out = [];
+    let depth = 0;
+    let cur = "";
+    for (const ch of css) {
+        if (ch === "(")
+            depth++;
+        if (ch === ")")
+            depth--;
+        if (ch === "," && depth === 0) {
+            out.push(cur.trim());
+            cur = "";
+        }
+        else
+            cur += ch;
+    }
+    if (cur.trim())
+        out.push(cur.trim());
+    return out;
+}
+/** Chromium serialises shadows as "<color> <x> <y> <blur> [<spread>] [inset]". */
+function parseShadows(css) {
+    if (!css || css === "none")
+        return [];
+    return splitList(css).map((raw) => {
+        const colorMatch = raw.match(/^(rgba?\([^)]*\)|hsla?\([^)]*\)|oklch\([^)]*\)|oklab\([^)]*\)|color\([^)]*\)|#[0-9a-f]{3,8}|[a-z]+)\s/i);
+        const color = colorMatch ? toRgb(parseColor(colorMatch[1]) ?? "black") ?? null : null;
+        const lengths = (raw.match(/-?\d*\.?\d+px/g) ?? []).map((v) => parseFloat(v));
+        return { color, lengths, inset: /\binset\b/.test(raw), raw };
+    });
+}
+/** Chroma of the shadow colour once its alpha has been laid over the surface it sits on. */
+function compositedChroma(color, surface) {
+    const a = color.alpha ?? 1;
+    const bg = toRgb(parseColor(surface ?? "white") ?? "white") ?? { mode: "rgb", r: 1, g: 1, b: 1 };
+    const mixed = { mode: "rgb", r: color.r * a + bg.r * (1 - a), g: color.g * a + bg.g * (1 - a), b: color.b * a + bg.b * (1 - a), alpha: 1 };
+    return toOklch(mixed)?.c ?? 0;
+}
+const GLOW_CHROMA = 0.04;
+const BOX_GLOW_BLUR = 12;
+const TEXT_GLOW_BLUR = 8;
+export function checkGlow(samples, forbid) {
+    const items = [];
+    const seen = new Set();
+    const consider = (s, prop, css) => {
+        const blurIndex = 2; // x, y, blur[, spread]
+        const minBlur = prop === "box-shadow" ? BOX_GLOW_BLUR : TEXT_GLOW_BLUR;
+        for (const sh of parseShadows(css)) {
+            if (!sh.color || (sh.color.alpha ?? 1) === 0)
+                continue;
+            const blur = sh.lengths[blurIndex] ?? 0;
+            if (blur < minBlur)
+                continue;
+            if (compositedChroma(sh.color, s.effectiveBackground) <= GLOW_CHROMA)
+                continue;
+            const key = `${prop}:${sh.raw}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            items.push({ selector: s.selector, value: `${prop}: ${sh.raw}`, nearest: `${formatHex(sh.color)} at ${blur}px blur`, text: s.text || undefined });
+        }
+    };
+    for (const s of samples) {
+        consider(s, "box-shadow", s.boxShadow);
+        if (s.isText)
+            consider(s, "text-shadow", s.textShadow);
+    }
+    return result("glow", "Glows", forbid ? "error" : "warning", items, items.length ? `${items.length} coloured glow(s) found (a chromatic shadow with a wide blur).` : "No coloured glows.", "Remove the coloured shadow. If the element needs lift, use a neutral shadow at low alpha or a hairline border from the palette.");
+}
+function alphaOf(css) {
+    const c = parseColor(css);
+    if (!c)
+        return 1;
+    return c.alpha ?? 1;
+}
+export function checkGlass(samples, forbid) {
+    const items = [];
+    const seen = new Set();
+    for (const s of samples) {
+        if (!/blur\(/.test(s.backdropFilter))
+            continue;
+        if (alphaOf(s.backgroundColor) >= 1)
+            continue;
+        const key = `${s.backdropFilter}|${s.backgroundColor}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        items.push({ selector: s.selector, value: `backdrop-filter: ${s.backdropFilter} on ${s.backgroundColor}`, text: s.text || undefined });
+    }
+    return result("glass", "Glassmorphism", forbid ? "error" : "warning", items, items.length ? `${items.length} frosted-glass surface(s) found (backdrop blur on a translucent background).` : "No glassmorphism.", "Give the surface an opaque background token and remove backdrop-filter.");
+}
+export function checkCardSoup(groups) {
+    const items = groups.map((g) => ({ selector: g.selector, value: `${g.count} sibling cards, each icon + heading + paragraph`, nearest: `first card: ${g.example}` }));
+    return result("cards", "Card soup", "warning", items, items.length ? `${items.length} row(s) of icon cards found. Three matching cards with an icon on top is the most common generated layout.` : "No rows of icon cards.", "Write the features as a list or a two-column section with real content, and keep icons only where they carry meaning. Mark a deliberate grid with data-design-check=\"ignore\".");
+}

package/dist/cli.js

@@ -6,14 +6,16 @@ import { SITE } from "./config.js";
 const HELP = `dontmakeitugly — a design contract for your repo, and a check that fails when it drifts.
 
 Usage:
-  npx dontmakeitugly init <pack> [--force] [--with-screens]
+  npx dontmakeitugly init <pack> [--force]
   npx dontmakeitugly check [--routes /,/pricing] [--base-url http://localhost:3000] [--update-baselines] [--json]
 
-init   Fetches a pack from ${SITE} and writes DESIGN.md, dmiu.config.json and
-       .dmiu/references/README.md, and adds a block to AGENTS.md (and CLAUDE.md if present).
+init   Fetches a pack from ${SITE} and writes DESIGN.md, dmiu.config.json,
+       .dmiu/references/README.md and .dmiu/critic.md (a prompt for a fresh-context
+       design critic), and adds a block to AGENTS.md (and CLAUDE.md if present).
 check  Screenshots the routes in dmiu.config.json at each viewport and checks fonts,
-       palette, contrast, gradients, reduced motion, spacing, radii and baselines
-       against DESIGN.md. Writes .dmiu/report.md and .dmiu/report.json. Exit 1 on errors.
+       palette, contrast, gradients, glows, glassmorphism, card soup, reduced motion,
+       spacing, radii and baselines against DESIGN.md. Writes .dmiu/report.md and
+       .dmiu/report.json. Exit 1 on errors.
 
 Packs: ${SITE}/packs
 `;
@@ -22,7 +24,6 @@ async function main() {
         allowPositionals: true,
         options: {
             force: { type: "boolean", default: false },
-            "with-screens": { type: "boolean", default: false },
             "update-baselines": { type: "boolean", default: false },
             json: { type: "boolean", default: false },
             routes: { type: "string" },
@@ -46,15 +47,14 @@ async function main() {
             console.error(`Which pack? Try: npx dontmakeitugly init first-vibe-coded-app\nAll packs: ${SITE}/packs`);
             process.exit(1);
         }
-        const { written, skipped } = await runInit({ cwd, pack: arg, force: values.force, withScreens: values["with-screens"], site: values.site, log });
+        const { written, skipped } = await runInit({ cwd, pack: arg, force: values.force, site: values.site, log });
         for (const w of written)
             log(`  wrote  ${w}`);
         for (const s of skipped)
             log(`  kept   ${s} (already exists; use --force to overwrite)`);
         log("");
         log("Next: build with your agent, then start the dev server and run `npx dontmakeitugly check`.");
-        if (!process.env.CI)
-            log("If Chromium isn't installed for Playwright yet: npx playwright install chromium");
+        log("The first check installs a headless Chromium for Playwright (about 200 MB) if it isn't there yet.");
         return;
     }
     if (cmd === "check") {

package/dist/collect.js

@@ -96,6 +96,9 @@ export async function collect(page, ignore) {
                 cs.margin,
                 cs.gap,
                 cs.borderRadius,
+                cs.boxShadow,
+                cs.textShadow,
+                cs.getPropertyValue("backdrop-filter"),
                 isText ? "t" : "",
             ].join("|");
             if (seen.has(key))
@@ -122,6 +125,9 @@ export async function collect(page, ignore) {
                 width: Math.round(rect.width),
                 height: Math.round(rect.height),
                 transitionDuration: Math.max(0, ...cs.transitionDuration.split(",").map((d) => (d.trim().endsWith("ms") ? parseFloat(d) : parseFloat(d) * 1000)).filter(Number.isFinite)),
+                boxShadow: cs.boxShadow,
+                textShadow: cs.textShadow,
+                backdropFilter: cs.getPropertyValue("backdrop-filter"),
             });
             if (seen.size > 4000)
                 break;
@@ -136,6 +142,45 @@ export async function collect(page, ignore) {
                 return [];
             return [{ selector: shortSelector(target), duration, name: a.animationName ?? a.id ?? "animation" }];
         });
-        return { samples: Array.from(seen.values()), totalElements: total, runningAnimations };
+        // Card soup: three or more siblings that each open with an icon, then a heading, then a paragraph.
+        // The icon-first order is what separates the feature-card cliché from an ordinary list of things.
+        const visible = (el) => {
+            const r = el.getBoundingClientRect();
+            return r.width >= 1 && r.height >= 1;
+        };
+        const isCard = (el) => {
+            if (!visible(el))
+                return false;
+            const headings = el.querySelectorAll("h1, h2, h3, h4, h5, h6, [role='heading']");
+            if (headings.length !== 1)
+                return false;
+            if (!el.querySelector("p"))
+                return false;
+            // An icon is small; a preview image or illustration above a heading is a different layout.
+            const icon = Array.from(el.querySelectorAll("svg, img, [class*='icon' i]")).find((c) => {
+                const r = c.getBoundingClientRect();
+                return r.width >= 8 && r.height >= 8 && r.width <= 48 && r.height <= 48;
+            });
+            if (!icon)
+                return false;
+            const iconFirst = Boolean(icon.compareDocumentPosition(headings[0]) & Node.DOCUMENT_POSITION_FOLLOWING);
+            return iconFirst && (el.textContent ?? "").trim().length <= 600;
+        };
+        const cardGroups = [];
+        for (const el of Array.from(all)) {
+            if (ignored(el) || !visible(el))
+                continue;
+            const cs = getComputedStyle(el);
+            if (!/grid|flex/.test(cs.display))
+                continue;
+            const kids = Array.from(el.children).filter((k) => !ignored(k) && !SKIP_TAGS.has(k.tagName));
+            if (kids.length < 3)
+                continue;
+            const cards = kids.filter(isCard);
+            if (cards.length < 3)
+                continue;
+            cardGroups.push({ selector: shortSelector(el), count: cards.length, example: shortSelector(cards[0]) });
+        }
+        return { samples: Array.from(seen.values()), totalElements: total, runningAnimations, cardGroups };
     }, ignore);
 }

package/dist/init.js

@@ -54,24 +54,8 @@ export async function runInit(opts) {
             written.push(name);
         }
     }
-    if (opts.withScreens) {
-        const dir = path.join(opts.cwd, ".dmiu", "references");
-        fs.mkdirSync(dir, { recursive: true });
-        for (const r of manifest.references) {
-            try {
-                const res = await fetch(r.image);
-                if (!res.ok)
-                    continue;
-                const buf = Buffer.from(await res.arrayBuffer());
-                const file = path.join(dir, `${r.resource}.jpg`);
-                fs.writeFileSync(file, buf);
-                written.push(path.relative(opts.cwd, file));
-            }
-            catch {
-                /* a missing preview is not fatal */
-            }
-        }
-    }
+    // Reference previews stay as URLs in .dmiu/references/README.md and .dmiu/critic.md.
+    // They belong to their owners; init never downloads them into the project.
     // Keep generated output out of git without touching an existing rule.
     const gi = path.join(opts.cwd, ".gitignore");
     const rule = ".dmiu/screenshots/";

package/dist/report.js

@@ -24,6 +24,17 @@ export function toMarkdown(r) {
         out.push("Nothing to fix. Every check passed on every route and viewport.");
         out.push("");
     }
+    out.push("## Screenshots");
+    out.push("");
+    for (const p of r.pages)
+        out.push(`- ${p.route} at ${p.viewport}: ${p.screenshot}`);
+    out.push("");
+    if (r.critic) {
+        out.push(r.ok
+            ? `Zero errors. Next: hand these screenshots and the reference previews to the critic in ${r.critic}, in a fresh context with no code. Apply its three gaps, run the check again, at most twice.`
+            : `Fix the errors first. The critic in ${r.critic} runs once this report has none.`);
+        out.push("");
+    }
     const failing = r.pages.flatMap((p) => p.checks.filter((c) => c.status !== "pass").map((c) => ({ p, c })));
     if (failing.length) {
         out.push("## What to fix");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dontmakeitugly",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Put a DESIGN.md contract in your repo and check the result against it. From dontmakeitugly.com.",
   "license": "MIT",
   "type": "module",