dontmakeitugly 0.1.0

package/README.md

@@ -0,0 +1,25 @@
+# dontmakeitugly
+
+A design contract for your repo, and a check that fails when it drifts.
+
+```sh
+npx dontmakeitugly init first-vibe-coded-app   # DESIGN.md + check config + AGENTS.md block
+# build with your agent, start the dev server, then:
+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.
+
+`check` screenshots your routes at desktop and mobile widths with Playwright and runs deterministic checks derived from the DESIGN.md tokens:
+
+- fonts outside the contract (error)
+- 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)
+- 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`.

package/dist/check.js

@@ -0,0 +1,113 @@
+import path from "node:path";
+import fs from "node:fs";
+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 { summarise, writeReport } from "./report.js";
+function slugify(s) {
+    return s.replace(/^\//, "").replace(/[^a-z0-9]+/gi, "-").replace(/^-|-$/g, "") || "home";
+}
+async function launch() {
+    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");
+        }
+        throw e;
+    }
+}
+async function reachable(url) {
+    try {
+        const res = await fetch(url, { method: "GET", redirect: "follow" });
+        return res.ok || res.status === 304;
+    }
+    catch {
+        return false;
+    }
+}
+export async function runCheck(opts) {
+    const log = opts.log ?? (() => { });
+    const overrides = {};
+    if (opts.routes?.length)
+        overrides.routes = opts.routes;
+    if (opts.baseUrl)
+        overrides.baseUrl = opts.baseUrl;
+    const cfg = loadConfig(opts.cwd, overrides);
+    const designFile = path.resolve(opts.cwd, cfg.designMd);
+    if (!fs.existsSync(designFile)) {
+        throw new Error(`${cfg.designMd} not found. Run "npx dontmakeitugly init <pack>" first, or point dmiu.config.json at your DESIGN.md.`);
+    }
+    const contract = loadContract(designFile);
+    log(`Contract: ${contract.name} — ${contract.fonts.length} font(s), ${contract.palette.length} colour(s), ${contract.spacing.length} spacing step(s)`);
+    const first = new URL(cfg.routes[0], cfg.baseUrl).toString();
+    if (!(await reachable(first))) {
+        throw new Error(`Nothing is answering at ${cfg.baseUrl}. Start the dev server (or pass --base-url) and run the check again.`);
+    }
+    const outDir = path.resolve(opts.cwd, cfg.outDir);
+    const shotsDir = path.join(outDir, "screenshots");
+    fs.mkdirSync(shotsDir, { recursive: true });
+    const browser = await launch();
+    const pages = [];
+    try {
+        for (const vp of cfg.viewports) {
+            const viewport = `${vp.width}x${vp.height}`;
+            const ctx = await browser.newContext({ viewport: vp, deviceScaleFactor: 1, reducedMotion: "no-preference" });
+            const reducedCtx = await browser.newContext({ viewport: vp, deviceScaleFactor: 1, reducedMotion: "reduce" });
+            for (const route of cfg.routes) {
+                const url = new URL(route, cfg.baseUrl).toString();
+                const name = `${slugify(route)}@${vp.width}`;
+                log(`Checking ${route} at ${viewport}`);
+                const page = await ctx.newPage();
+                await page.goto(url, { waitUntil: "domcontentloaded", timeout: 45000 });
+                await page.waitForLoadState("networkidle", { timeout: 15000 }).catch(() => { });
+                await page.evaluate(() => document.fonts?.ready).catch(() => { });
+                await page.waitForTimeout(600);
+                const collected = await collect(page, cfg.ignore);
+                const screenshotPath = path.join(shotsDir, `${name}.png`);
+                // Settle animations before the pixel comparison.
+                await page.waitForTimeout(1200);
+                const shot = await page.screenshot({ path: screenshotPath, fullPage: true, animations: "disabled" });
+                await page.close();
+                const reduced = await reducedCtx.newPage();
+                await reduced.goto(url, { waitUntil: "domcontentloaded", timeout: 45000 });
+                await reduced.waitForLoadState("networkidle", { timeout: 15000 }).catch(() => { });
+                await reduced.waitForTimeout(400);
+                const reducedCollected = await collect(reduced, cfg.ignore);
+                await reduced.close();
+                const checks = [
+                    checkFonts(collected.samples, contract),
+                    checkColors(collected.samples, contract, cfg.tolerance.color),
+                    checkContrast(collected.samples),
+                    checkGradients(collected.samples, cfg.forbidGradients),
+                    checkMotion(reducedCollected.runningAnimations, collected.samples),
+                    checkSpacing(collected.samples, contract, cfg.tolerance.spacing),
+                    checkRadius(collected.samples, contract),
+                    checkBaseline(shot, name, path.resolve(opts.cwd, cfg.baselines.dir), cfg.baselines.threshold, Boolean(opts.updateBaselines)).check,
+                ];
+                pages.push({ route, viewport, url, screenshot: path.relative(opts.cwd, screenshotPath), checks });
+            }
+            await ctx.close();
+            await reducedCtx.close();
+        }
+    }
+    finally {
+        await browser.close();
+    }
+    const summary = summarise(pages);
+    const report = {
+        ok: summary.errors === 0,
+        generatedAt: new Date().toISOString(),
+        designMd: cfg.designMd,
+        contract: { name: contract.name, fonts: contract.fonts, palette: contract.palette.length, spacing: contract.spacing, radii: contract.radii },
+        summary,
+        pages,
+    };
+    const files = writeReport(outDir, report);
+    return { report, files };
+}

package/dist/checks/baseline.js

@@ -0,0 +1,40 @@
+import fs from "node:fs";
+import path from "node:path";
+import { PNG } from "pngjs";
+import pixelmatch from "pixelmatch";
+import { result } from "./types.js";
+/**
+ * Compares a screenshot against the committed baseline. A missing baseline
+ * is written and reported as a pass, so the first run seeds the set.
+ */
+export function checkBaseline(shot, name, dir, threshold, update) {
+    fs.mkdirSync(dir, { recursive: true });
+    const file = path.join(dir, `${name}.png`);
+    if (!fs.existsSync(file) || update) {
+        fs.writeFileSync(file, shot);
+        return { check: result("baseline", "Screenshot baseline", "error", [], update ? `Baseline updated: ${file}` : `Baseline created: ${file}`), created: true };
+    }
+    const a = PNG.sync.read(fs.readFileSync(file));
+    const b = PNG.sync.read(shot);
+    if (a.width !== b.width || a.height !== b.height) {
+        return {
+            check: result("baseline", "Screenshot baseline", "error", [{ selector: name, value: `page size changed: ${a.width}×${a.height} → ${b.width}×${b.height}` }], "The page size differs from the baseline, so the pixels were not compared.", "If the change is intended, run with --update-baselines."),
+            created: false,
+        };
+    }
+    const diff = new PNG({ width: a.width, height: a.height });
+    const changed = pixelmatch(a.data, b.data, diff.data, a.width, a.height, { threshold: 0.1 });
+    const ratio = changed / (a.width * a.height);
+    const diffPath = path.join(dir, `${name}.diff.png`);
+    if (ratio > threshold) {
+        fs.writeFileSync(diffPath, PNG.sync.write(diff));
+        return {
+            check: result("baseline", "Screenshot baseline", "error", [{ selector: name, value: `${(ratio * 100).toFixed(2)}% of pixels changed (limit ${(threshold * 100).toFixed(1)}%)`, nearest: diffPath }], "The page drifted from its baseline.", "Open the diff image; if the change is intended, run with --update-baselines."),
+            created: false,
+            diffPath,
+        };
+    }
+    if (fs.existsSync(diffPath))
+        fs.rmSync(diffPath);
+    return { check: result("baseline", "Screenshot baseline", "error", [], `Matches baseline (${(ratio * 100).toFixed(2)}% changed).`), created: false };
+}

package/dist/checks/style.js

@@ -0,0 +1,228 @@
+import { parse as parseColor, converter, differenceEuclidean, wcagContrast, formatHex } from "culori";
+import { result } from "./types.js";
+const toOklab = converter("oklab");
+const toOklch = converter("oklch");
+const toRgb = converter("rgb");
+const deltaE = differenceEuclidean("oklab");
+const GENERIC_FAMILIES = new Set([
+    "serif", "sans-serif", "monospace", "cursive", "fantasy", "system-ui", "ui-serif", "ui-sans-serif",
+    "ui-monospace", "ui-rounded", "math", "emoji", "fangsong", "-apple-system", "blinkmacsystemfont",
+    "segoe ui", "roboto", "helvetica neue", "arial", "apple color emoji", "segoe ui emoji", "segoe ui symbol",
+]);
+/** next/font names look like "__Inter_a1b2c3" or "Inter Fallback"; normalise both. */
+function normaliseFamily(f) {
+    return f
+        .replace(/^["']|["']$/g, "")
+        .replace(/^__/, "")
+        .replace(/_[a-f0-9]{6}$/i, "")
+        .replace(/_/g, " ")
+        .replace(/\s+fallback$/i, "")
+        .trim()
+        .toLowerCase();
+}
+export function checkFonts(samples, contract) {
+    const allowed = new Set(contract.fonts);
+    const items = [];
+    if (allowed.size === 0)
+        return result("fonts", "Fonts", "warning", [], "DESIGN.md defines no typography, so fonts were not checked.");
+    for (const s of samples) {
+        if (!s.isText)
+            continue;
+        const first = normaliseFamily(s.fontFamily.split(",")[0] ?? "");
+        if (!first || allowed.has(first))
+            continue;
+        if (GENERIC_FAMILIES.has(first)) {
+            items.push({ selector: s.selector, value: first, text: s.text, nearest: "no contract font applied" });
+        }
+        else {
+            items.push({ selector: s.selector, value: first, text: s.text });
+        }
+    }
+    return result("fonts", "Fonts", "error", dedupe(items), items.length ? `${items.length} text element(s) use a typeface outside the contract (${contract.fonts.join(", ")}).` : `Every text element uses a contract typeface (${contract.fonts.join(", ")}).`, "Load the contract fonts and set them on body and headings; remove any other font-family declarations.");
+}
+/** Composite an rgba colour onto an opaque background. */
+function composite(fg, bg) {
+    const a = fg.alpha ?? 1;
+    if (a >= 1 || !bg)
+        return { ...fg, alpha: 1 };
+    return { mode: "rgb", r: fg.r * a + bg.r * (1 - a), g: fg.g * a + bg.g * (1 - a), b: fg.b * a + bg.b * (1 - a), alpha: 1 };
+}
+function effective(css, bgCss) {
+    const c = parseColor(css);
+    if (!c)
+        return null;
+    const rgb = toRgb(c);
+    if (!rgb)
+        return null;
+    if ((rgb.alpha ?? 1) === 0)
+        return null;
+    const bg = bgCss ? toRgb(parseColor(bgCss) ?? "white") ?? null : null;
+    return composite(rgb, bg);
+}
+export function checkColors(samples, contract, tolerance) {
+    if (contract.palette.length === 0)
+        return result("colors", "Palette", "warning", [], "DESIGN.md defines no colours, so the palette was not checked.");
+    const items = [];
+    const seen = new Set();
+    const consider = (s, css, role) => {
+        const rgb = effective(css, s.effectiveBackground);
+        if (!rgb)
+            return;
+        const hex = formatHex(rgb);
+        const lab = toOklab(rgb);
+        if (!lab)
+            return;
+        let best = { name: "", d: Infinity };
+        for (const p of contract.palette) {
+            const d = deltaE(lab, p.lab) * 100;
+            if (d < best.d)
+                best = { name: p.name, d };
+        }
+        if (best.d <= tolerance)
+            return;
+        const key = `${role}:${hex}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        items.push({ selector: s.selector, value: `${role} ${hex}`, nearest: `${best.name} (ΔE ${best.d.toFixed(1)})`, text: s.text || undefined });
+    };
+    for (const s of samples) {
+        if (s.isText)
+            consider(s, s.color, "text");
+        consider(s, s.backgroundColor, "background");
+        if (s.hasBorder)
+            consider(s, s.borderColor, "border");
+    }
+    return result("colors", "Palette", items.length > 6 ? "error" : "warning", items, items.length ? `${items.length} colour(s) in use are not in the palette (tolerance ΔE ${tolerance}).` : "Every colour in use is in the palette.", "Replace each off-palette value with the nearest token named here, or add the token to DESIGN.md if it was a deliberate omission.");
+}
+export function checkContrast(samples) {
+    const items = [];
+    for (const s of samples) {
+        if (!s.isText || s.effectiveBackground === null)
+            continue;
+        const fg = effective(s.color, s.effectiveBackground);
+        const bg = effective(s.backgroundColor, s.effectiveBackground) ?? toRgb(parseColor(s.effectiveBackground) ?? "white");
+        if (!fg || !bg)
+            continue;
+        const ratio = wcagContrast(fg, bg);
+        const large = s.fontSize >= 24 || (s.fontSize >= 18.66 && s.fontWeight >= 700);
+        const min = large ? 3 : 4.5;
+        if (ratio < min) {
+            items.push({ selector: s.selector, value: `${ratio.toFixed(2)}:1 (${formatHex(fg)} on ${formatHex(bg)}, ${s.fontSize}px)`, nearest: `needs ${min}:1`, text: s.text });
+        }
+    }
+    return result("contrast", "Contrast (WCAG AA)", "error", items, items.length ? `${items.length} text element(s) fall below WCAG AA contrast.` : "All text meets WCAG AA contrast.", "Use a darker text token or a lighter background for the elements listed; 4.5:1 for body text, 3:1 for text 24px and up.");
+}
+export function checkGradients(samples, forbid) {
+    const ai = [];
+    const other = [];
+    for (const s of samples) {
+        if (!s.backgroundImage.includes("gradient("))
+            continue;
+        const stops = (s.backgroundImage.match(/(rgba?\([^)]*\)|#[0-9a-f]{3,8}|oklch\([^)]*\)|hsla?\([^)]*\))/gi) ?? [])
+            .map((c) => parseColor(c))
+            .filter((c) => Boolean(c));
+        const hexes = new Set(stops.map((c) => formatHex(c)));
+        if (hexes.size <= 1)
+            continue; // single-colour "gradient" hairline hack, effectively flat
+        const purpleBlue = stops.some((c) => {
+            const lch = toOklch(c);
+            return lch && (lch.c ?? 0) > 0.08 && lch.h !== undefined && lch.h >= 220 && lch.h <= 300;
+        });
+        const item = { selector: s.selector, value: s.backgroundImage.slice(0, 90) };
+        if (purpleBlue)
+            ai.push(item);
+        else
+            other.push(item);
+    }
+    const items = [...ai, ...(forbid ? other : [])];
+    return result("gradients", "Gradients", ai.length ? "error" : "warning", items, ai.length
+        ? `${ai.length} purple/blue gradient(s) found. This is the signature of a generated interface.`
+        : items.length
+            ? `${items.length} gradient(s) found; the contract forbids gradients.`
+            : "No gradients.", "Replace the gradient with a flat token colour, or a photograph if the section needs texture.");
+}
+function nearestOnScale(v, scale, base, tol) {
+    let nearest = scale[0] ?? 0;
+    let best = Infinity;
+    for (const s of scale) {
+        const d = Math.abs(s - v);
+        if (d < best) {
+            best = d;
+            nearest = s;
+        }
+    }
+    if (best <= tol)
+        return { ok: true, nearest };
+    if (base && base > 0 && Math.abs(v / base - Math.round(v / base)) * base <= tol)
+        return { ok: true, nearest: Math.round(v / base) * base };
+    return { ok: false, nearest };
+}
+export function checkSpacing(samples, contract, tolerance) {
+    if (contract.spacing.length === 0)
+        return result("spacing", "Spacing scale", "warning", [], "DESIGN.md defines no spacing scale, so spacing was not checked.");
+    const items = [];
+    const seen = new Set();
+    for (const s of samples) {
+        const values = [
+            ...s.padding.map((v, i) => [`padding-${["top", "right", "bottom", "left"][i]}`, v]),
+            ...s.gap.map((v, i) => [i === 0 ? "row-gap" : "column-gap", v]),
+        ];
+        for (const [prop, v] of values) {
+            if (v <= 0 || v > 160)
+                continue;
+            const { ok, nearest } = nearestOnScale(v, contract.spacing, contract.spacingBase, tolerance);
+            if (ok)
+                continue;
+            const key = `${prop}:${v}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            items.push({ selector: s.selector, value: `${prop}: ${v}px`, nearest: `${nearest}px` });
+        }
+    }
+    return result("spacing", "Spacing scale", "warning", items, items.length ? `${items.length} padding/gap value(s) are off the spacing scale (${contract.spacing.join(", ")}px).` : "All padding and gap values sit on the spacing scale.", "Snap each value to the nearest step named here.");
+}
+export function checkRadius(samples, contract) {
+    if (contract.radii.length === 0)
+        return result("radius", "Corner radii", "warning", [], "DESIGN.md defines no radii, so corners were not checked.");
+    const items = [];
+    const seen = new Set();
+    for (const s of samples) {
+        for (const r of s.borderRadius) {
+            if (r <= 0)
+                continue;
+            const pill = r >= Math.min(s.width, s.height) / 2;
+            if (pill)
+                continue;
+            const ok = contract.radii.some((x) => Math.abs(x - r) <= 0.5);
+            if (ok || seen.has(r))
+                continue;
+            seen.add(r);
+            const nearest = contract.radii.reduce((a, b) => (Math.abs(b - r) < Math.abs(a - r) ? b : a));
+            items.push({ selector: s.selector, value: `border-radius: ${r}px`, nearest: `${nearest}px` });
+        }
+    }
+    return result("radius", "Corner radii", "warning", items, items.length ? `${items.length} radius value(s) are not in the contract (${contract.radii.join(", ")}px).` : "All corner radii are in the contract.", "Use the rounded tokens from DESIGN.md; pills (fully rounded) are always allowed.");
+}
+export function checkMotion(running, samples) {
+    const items = running
+        .filter((a) => a.duration > 100)
+        .map((a) => ({ selector: a.selector, value: `${a.name} (${Math.round(a.duration)}ms) still running with prefers-reduced-motion: reduce` }));
+    const slow = samples.filter((s) => s.transitionDuration > 200).slice(0, 4);
+    return result("motion", "Reduced motion", "error", items, items.length
+        ? `${items.length} animation(s) keep running when the user asks for reduced motion.`
+        : slow.length
+            ? `Reduced motion is respected. Note: ${slow.length} element(s) have transitions over 200ms.`
+            : "Reduced motion is respected.", "Wrap animations in a prefers-reduced-motion media query or set their duration to 0.01ms under it.");
+}
+function dedupe(items) {
+    const seen = new Set();
+    return items.filter((i) => {
+        const k = `${i.value}|${i.selector.split(" > ").pop()}`;
+        if (seen.has(k))
+            return false;
+        seen.add(k);
+        return true;
+    });
+}

package/dist/checks/types.js

@@ -0,0 +1,5 @@
+export const MAX_ITEMS = 12;
+export function result(id, title, severity, items, message, fix) {
+    const status = items.length === 0 ? "pass" : severity === "error" ? "fail" : "warn";
+    return { id, title, status, message, fix, items: items.slice(0, MAX_ITEMS), count: items.length };
+}

package/dist/cli.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { runInit } from "./init.js";
+import { runCheck } from "./check.js";
+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 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).
+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.
+
+Packs: ${SITE}/packs
+`;
+async function main() {
+    const { values, positionals } = parseArgs({
+        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" },
+            "base-url": { type: "string" },
+            site: { type: "string" },
+            help: { type: "boolean", short: "h", default: false },
+        },
+    });
+    const [cmd, arg] = positionals;
+    const cwd = process.cwd();
+    const log = (l) => {
+        if (!values.json)
+            console.log(l);
+    };
+    if (values.help || !cmd) {
+        console.log(HELP);
+        process.exit(cmd ? 0 : 1);
+    }
+    if (cmd === "init") {
+        if (!arg) {
+            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 });
+        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");
+        return;
+    }
+    if (cmd === "check") {
+        const routes = values.routes?.split(",").map((r) => r.trim()).filter(Boolean);
+        const { report, files } = await runCheck({ cwd, updateBaselines: values["update-baselines"], routes, baseUrl: values["base-url"], log });
+        if (values.json) {
+            console.log(JSON.stringify(report, null, 2));
+        }
+        else {
+            console.log("");
+            for (const p of report.pages) {
+                console.log(`${p.route} at ${p.viewport}`);
+                for (const c of p.checks)
+                    console.log(`  ${c.status === "pass" ? "✓" : c.status === "warn" ? "!" : "✗"} ${c.title}: ${c.message}`);
+            }
+            console.log("");
+            console.log(`${report.ok ? "✓ passed" : "✗ failed"} — ${report.summary.errors} error(s), ${report.summary.warnings} warning(s). Report: ${files.md}`);
+        }
+        process.exit(report.ok ? 0 : 1);
+    }
+    console.error(`Unknown command "${cmd}".\n\n${HELP}`);
+    process.exit(1);
+}
+main().catch((e) => {
+    console.error(`✗ ${e.message}`);
+    process.exit(1);
+});

package/dist/collect.js

@@ -0,0 +1,141 @@
+/**
+ * Walks the visible DOM and returns one sample per distinct (tag, class,
+ * computed subset) so a 200-row table costs one entry, not 200.
+ */
+export async function collect(page, ignore) {
+    return page.evaluate((ignoreSelectors) => {
+        const SKIP_TAGS = new Set(["SCRIPT", "STYLE", "NOSCRIPT", "TEMPLATE", "HEAD", "META", "LINK", "TITLE", "BR", "WBR", "svg", "path", "IMG", "VIDEO", "CANVAS", "IFRAME", "PICTURE", "SOURCE"]);
+        const ignored = (el) => {
+            if (el.closest('[data-design-check="ignore"]'))
+                return true;
+            for (const s of ignoreSelectors) {
+                try {
+                    if (el.closest(s))
+                        return true;
+                }
+                catch {
+                    /* bad selector; ignore */
+                }
+            }
+            return false;
+        };
+        const px = (v) => {
+            const n = parseFloat(v);
+            return Number.isFinite(n) ? Math.round(n * 100) / 100 : 0;
+        };
+        const transparent = (c) => /^(transparent|rgba?\(\s*\d+,?\s*\d+,?\s*\d+,?\s*(\/\s*)?0\))$/.test(c.replace(/\s+/g, "")) || c === "rgba(0, 0, 0, 0)";
+        const shortSelector = (el) => {
+            const parts = [];
+            let cur = el;
+            let depth = 0;
+            while (cur && cur !== document.documentElement && depth < 4) {
+                let part = cur.tagName.toLowerCase();
+                if (cur.id) {
+                    parts.unshift(`#${cur.id}`);
+                    break;
+                }
+                const cls = Array.from(cur.classList).filter((c) => !/[\[\]:/]/.test(c)).slice(0, 2);
+                if (cls.length)
+                    part += "." + cls.join(".");
+                const parent = cur.parentElement;
+                if (parent) {
+                    const same = Array.from(parent.children).filter((c) => c.tagName === cur.tagName);
+                    if (same.length > 1)
+                        part += `:nth-of-type(${same.indexOf(cur) + 1})`;
+                }
+                parts.unshift(part);
+                cur = cur.parentElement;
+                depth++;
+            }
+            return parts.join(" > ");
+        };
+        const effectiveBg = (el) => {
+            let cur = el.parentElement;
+            while (cur) {
+                const cs = getComputedStyle(cur);
+                if (cs.backgroundImage && cs.backgroundImage !== "none")
+                    return null;
+                if (!transparent(cs.backgroundColor))
+                    return cs.backgroundColor;
+                cur = cur.parentElement;
+            }
+            return "rgb(255, 255, 255)";
+        };
+        const seen = new Map();
+        const all = document.body.querySelectorAll("*");
+        let total = 0;
+        for (const el of Array.from(all)) {
+            if (SKIP_TAGS.has(el.tagName) || SKIP_TAGS.has(el.tagName.toLowerCase()))
+                continue;
+            if (ignored(el))
+                continue;
+            const cs = getComputedStyle(el);
+            if (cs.display === "none" || cs.visibility === "hidden" || parseFloat(cs.opacity) === 0)
+                continue;
+            const rect = el.getBoundingClientRect();
+            if (rect.width < 1 || rect.height < 1)
+                continue;
+            total++;
+            const ownText = Array.from(el.childNodes)
+                .filter((n) => n.nodeType === Node.TEXT_NODE)
+                .map((n) => n.textContent ?? "")
+                .join(" ")
+                .replace(/\s+/g, " ")
+                .trim();
+            const isText = ownText.length > 0;
+            const key = [
+                el.tagName,
+                Array.from(el.classList).sort().join("."),
+                cs.fontFamily,
+                cs.fontSize,
+                cs.fontWeight,
+                cs.color,
+                cs.backgroundColor,
+                cs.backgroundImage,
+                cs.padding,
+                cs.margin,
+                cs.gap,
+                cs.borderRadius,
+                isText ? "t" : "",
+            ].join("|");
+            if (seen.has(key))
+                continue;
+            const hasBorder = ["Top", "Right", "Bottom", "Left"].some((s) => px(cs.getPropertyValue(`border-${s.toLowerCase()}-width`)) > 0 && cs.getPropertyValue(`border-${s.toLowerCase()}-style`) !== "none");
+            seen.set(key, {
+                selector: shortSelector(el),
+                tag: el.tagName.toLowerCase(),
+                text: ownText.slice(0, 60),
+                isText,
+                fontFamily: cs.fontFamily,
+                fontSize: px(cs.fontSize),
+                fontWeight: parseInt(cs.fontWeight, 10) || 400,
+                color: cs.color,
+                backgroundColor: cs.backgroundColor,
+                effectiveBackground: effectiveBg(el),
+                backgroundImage: cs.backgroundImage,
+                borderColor: cs.borderTopColor,
+                hasBorder,
+                padding: [cs.paddingTop, cs.paddingRight, cs.paddingBottom, cs.paddingLeft].map(px),
+                margin: [cs.marginTop, cs.marginRight, cs.marginBottom, cs.marginLeft].map(px),
+                gap: [cs.rowGap, cs.columnGap].map((g) => (g === "normal" ? 0 : px(g))),
+                borderRadius: [cs.borderTopLeftRadius, cs.borderTopRightRadius, cs.borderBottomRightRadius, cs.borderBottomLeftRadius].map(px),
+                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)),
+            });
+            if (seen.size > 4000)
+                break;
+        }
+        const runningAnimations = document.getAnimations().flatMap((a) => {
+            if (a.playState !== "running")
+                return [];
+            const timing = a.effect?.getTiming();
+            const duration = typeof timing?.duration === "number" ? timing.duration : 0;
+            const target = a.effect?.target;
+            if (!target || ignored(target))
+                return [];
+            return [{ selector: shortSelector(target), duration, name: a.animationName ?? a.id ?? "animation" }];
+        });
+        return { samples: Array.from(seen.values()), totalElements: total, runningAnimations };
+    }, ignore);
+}

package/dist/config.js

@@ -0,0 +1,40 @@
+import fs from "node:fs";
+import path from "node:path";
+export const CONFIG_FILE = "dmiu.config.json";
+export const SITE = process.env.DMIU_SITE ?? "https://dontmakeitugly.com";
+const DEFAULTS = {
+    designMd: "DESIGN.md",
+    baseUrl: "http://localhost:3000",
+    routes: ["/"],
+    viewports: [
+        { width: 1280, height: 800 },
+        { width: 390, height: 844 },
+    ],
+    tolerance: { color: 6, spacing: 1 },
+    forbidGradients: true,
+    ignore: [],
+    baselines: { dir: ".dmiu/baselines", threshold: 0.02 },
+    outDir: ".dmiu",
+};
+export function loadConfig(cwd, overrides = {}) {
+    const file = path.join(cwd, CONFIG_FILE);
+    let fromFile = {};
+    if (fs.existsSync(file)) {
+        try {
+            fromFile = JSON.parse(fs.readFileSync(file, "utf8"));
+        }
+        catch (e) {
+            throw new Error(`${CONFIG_FILE} is not valid JSON: ${e.message}`);
+        }
+    }
+    const cfg = {
+        ...DEFAULTS,
+        ...fromFile,
+        ...overrides,
+        tolerance: { ...DEFAULTS.tolerance, ...fromFile.tolerance, ...overrides.tolerance },
+        baselines: { ...DEFAULTS.baselines, ...fromFile.baselines, ...overrides.baselines },
+    };
+    if (!Array.isArray(cfg.routes) || cfg.routes.length === 0)
+        cfg.routes = ["/"];
+    return cfg;
+}

package/dist/contract.js

@@ -0,0 +1,79 @@
+import fs from "node:fs";
+import { parse as parseYaml } from "yaml";
+import { parse as parseColor, converter } from "culori";
+const toOklab = converter("oklab");
+export function primaryFamily(fontFamily) {
+    return fontFamily.split(",")[0].trim().replace(/^["']|["']$/g, "");
+}
+/** "16px" | "1rem" | 16 -> px number, or null when not a length. */
+export function toPx(v) {
+    if (typeof v === "number")
+        return v;
+    if (typeof v !== "string")
+        return null;
+    const m = v.trim().match(/^(-?\d*\.?\d+)(px|rem|em)?$/);
+    if (!m)
+        return null;
+    const n = parseFloat(m[1]);
+    if (m[2] === "rem" || m[2] === "em")
+        return n * 16;
+    return n;
+}
+export function loadContract(file) {
+    const raw = fs.readFileSync(file, "utf8");
+    const m = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+    if (!m)
+        throw new Error(`${file}: expected a YAML front-matter block`);
+    const fm = (parseYaml(m[1]) ?? {});
+    const body = m[2];
+    const fonts = new Set();
+    for (const t of Object.values(fm.typography ?? {})) {
+        if (t?.fontFamily)
+            fonts.add(primaryFamily(String(t.fontFamily)).toLowerCase());
+    }
+    const palette = [];
+    for (const [name, css] of Object.entries(fm.colors ?? {})) {
+        const parsed = parseColor(String(css));
+        if (!parsed)
+            continue;
+        const lab = toOklab(parsed);
+        if (lab)
+            palette.push({ name, css: String(css), lab });
+    }
+    const spacingEntries = Object.entries(fm.spacing ?? {});
+    const spacing = new Set();
+    let spacingBase = null;
+    for (const [k, v] of spacingEntries) {
+        const px = toPx(v);
+        if (px === null)
+            continue;
+        if (k === "base")
+            spacingBase = px;
+        // Layout dimensions (sidebar, measure, container) are not rhythm values.
+        if (px <= 160)
+            spacing.add(px);
+    }
+    const radii = new Set();
+    for (const v of Object.values(fm.rounded ?? {})) {
+        const px = toPx(v);
+        if (px !== null)
+            radii.add(px);
+    }
+    const dontsSection = body.split(/^## +/m).find((s) => /^do'?s and don'?ts/i.test(s.replace(/[’]/g, "'")));
+    const donts = dontsSection
+        ? dontsSection
+            .split("\n")
+            .slice(1)
+            .map((l) => l.replace(/^\s*[-*]\s*/, "").trim())
+            .filter(Boolean)
+        : [];
+    return {
+        name: String(fm.name ?? "DESIGN.md"),
+        fonts: [...fonts],
+        palette,
+        spacing: [...spacing].sort((a, b) => a - b),
+        spacingBase,
+        radii: [...radii].sort((a, b) => a - b),
+        donts,
+    };
+}

package/dist/init.js

@@ -0,0 +1,87 @@
+import fs from "node:fs";
+import path from "node:path";
+import { SITE, CONFIG_FILE } from "./config.js";
+const BEGIN = "<!-- BEGIN:dontmakeitugly -->";
+const END = "<!-- END:dontmakeitugly -->";
+/** Inserts or replaces the marker block so re-running init is safe. */
+export function upsertBlock(existing, block) {
+    const start = existing.indexOf(BEGIN);
+    const end = existing.indexOf(END);
+    if (start !== -1 && end !== -1 && end > start) {
+        return existing.slice(0, start) + block + existing.slice(end + END.length);
+    }
+    const sep = existing.length === 0 ? "" : existing.endsWith("\n\n") ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
+    return existing + sep + block + "\n";
+}
+export async function fetchManifest(site, pack) {
+    const url = `${site.replace(/\/$/, "")}/packs/${pack}.json`;
+    const res = await fetch(url);
+    if (res.status === 404)
+        throw new Error(`No pack called "${pack}". See ${site}/packs for the list.`);
+    if (!res.ok)
+        throw new Error(`Could not fetch ${url} (${res.status}).`);
+    return (await res.json());
+}
+export async function runInit(opts) {
+    const log = opts.log ?? (() => { });
+    const site = opts.site ?? SITE;
+    const manifest = await fetchManifest(site, opts.pack);
+    log(`Pack: ${manifest.name} (${manifest.version}) from ${manifest.url}`);
+    const written = [];
+    const skipped = [];
+    for (const f of manifest.files) {
+        const target = path.resolve(opts.cwd, f.path);
+        if (!target.startsWith(path.resolve(opts.cwd)))
+            throw new Error(`Refusing to write outside the project: ${f.path}`);
+        if (fs.existsSync(target) && f.overwrite === "never" && !opts.force) {
+            skipped.push(f.path);
+            continue;
+        }
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, f.content);
+        written.push(f.path);
+    }
+    // Agent instructions: create AGENTS.md if missing, only touch CLAUDE.md if it exists.
+    for (const [name, create] of [["AGENTS.md", true], ["CLAUDE.md", false]]) {
+        const file = path.join(opts.cwd, name);
+        const exists = fs.existsSync(file);
+        if (!exists && !create)
+            continue;
+        const before = exists ? fs.readFileSync(file, "utf8") : "";
+        const after = upsertBlock(before, manifest.agentsSnippet);
+        if (after !== before) {
+            fs.writeFileSync(file, after);
+            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 */
+            }
+        }
+    }
+    // Keep generated output out of git without touching an existing rule.
+    const gi = path.join(opts.cwd, ".gitignore");
+    const rule = ".dmiu/screenshots/";
+    if (fs.existsSync(gi)) {
+        const g = fs.readFileSync(gi, "utf8");
+        if (!g.split("\n").some((l) => l.trim() === rule || l.trim() === ".dmiu/")) {
+            fs.writeFileSync(gi, g + (g.endsWith("\n") ? "" : "\n") + `\n# dontmakeitugly check output (baselines and report stay)\n${rule}\n`);
+            written.push(".gitignore");
+        }
+    }
+    return { written, skipped };
+}
+export { CONFIG_FILE };

package/dist/report.js

@@ -0,0 +1,68 @@
+import fs from "node:fs";
+import path from "node:path";
+export function summarise(pages) {
+    let errors = 0;
+    let warnings = 0;
+    for (const p of pages) {
+        for (const c of p.checks) {
+            if (c.status === "fail")
+                errors++;
+            else if (c.status === "warn")
+                warnings++;
+        }
+    }
+    return { errors, warnings, pages: pages.length };
+}
+/** The markdown report is written for the agent: what failed, where, what to change. */
+export function toMarkdown(r) {
+    const out = [];
+    out.push(`# Design check: ${r.ok ? "passed" : "failed"}`);
+    out.push("");
+    out.push(`Contract: ${r.designMd} (${r.contract.name}). ${r.summary.errors} error(s), ${r.summary.warnings} warning(s) across ${r.summary.pages} page render(s). Generated ${r.generatedAt}.`);
+    out.push("");
+    if (r.ok && r.summary.warnings === 0) {
+        out.push("Nothing to fix. Every check passed on every route and viewport.");
+        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");
+        out.push("");
+        out.push("Errors must be fixed. Warnings are worth a look. Do not edit DESIGN.md to make a check pass; change the code.");
+        out.push("");
+        for (const { p, c } of failing) {
+            out.push(`### ${c.status === "fail" ? "Error" : "Warning"}: ${c.title} on ${p.route} at ${p.viewport}`);
+            out.push("");
+            out.push(c.message);
+            if (c.fix)
+                out.push(`\nFix: ${c.fix}`);
+            out.push("");
+            for (const i of c.items) {
+                const bits = [`\`${i.selector}\``, i.value, i.nearest ? `→ ${i.nearest}` : "", i.text ? `("${i.text}")` : ""].filter(Boolean);
+                out.push(`- ${bits.join(" ")}`);
+            }
+            if (c.count > c.items.length)
+                out.push(`- …and ${c.count - c.items.length} more`);
+            out.push("");
+        }
+    }
+    out.push("## Every check");
+    out.push("");
+    for (const p of r.pages) {
+        out.push(`### ${p.route} at ${p.viewport}`);
+        out.push("");
+        for (const c of p.checks)
+            out.push(`- ${c.status === "pass" ? "✓" : c.status === "warn" ? "!" : "✗"} ${c.title}: ${c.message}`);
+        out.push(`- Screenshot: ${p.screenshot}`);
+        out.push("");
+    }
+    return out.join("\n");
+}
+export function writeReport(outDir, report) {
+    fs.mkdirSync(outDir, { recursive: true });
+    const json = path.join(outDir, "report.json");
+    const md = path.join(outDir, "report.md");
+    fs.writeFileSync(json, JSON.stringify(report, null, 2) + "\n");
+    fs.writeFileSync(md, toMarkdown(report));
+    return { json, md };
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "dontmakeitugly",
+  "version": "0.1.0",
+  "description": "Put a DESIGN.md contract in your repo and check the result against it. From dontmakeitugly.com.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "dontmakeitugly": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "culori": "^4.0.2",
+    "pixelmatch": "^7.1.0",
+    "playwright": "^1.62.1",
+    "pngjs": "^7.0.0",
+    "yaml": "^2.8.0"
+  },
+  "devDependencies": {
+    "@types/culori": "^4.0.0",
+    "@types/node": "^20",
+    "@types/pixelmatch": "^5.2.6",
+    "@types/pngjs": "^6.0.5",
+    "typescript": "^5"
+  },
+  "keywords": [
+    "design",
+    "design-system",
+    "DESIGN.md",
+    "coding-agents",
+    "playwright",
+    "visual-regression"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gorock007/dontmakeitugly.git",
+    "directory": "packages/dontmakeitugly"
+  },
+  "homepage": "https://dontmakeitugly.com/packs"
+}