trykeyline 0.1.0 → 0.1.2

package/plugins/keyline/skills/keyline/glass/type/scale.md

@@ -17,7 +17,7 @@ A modular scale gives too few sizes in the 11–16px band, where Glass needs 11,
 - 12.5px code. Monospace runs wide, so it steps down to occupy the same measure as the prose around it — the one size that compensates for a *family* rather than a role.
 - 12px. Tags, prev/next labels, hover-card titles; small enough to read as annotation.
 - 11px. Tooltips and avatar initials. The floor for anything a user is expected to read.
-- 8.5px lettermarks, 7.5px card lettering. Below the floor on purpose — recognised rather than read, which is also why 7.5px is the one place a 600 weight is allowed.
+- 8.5px lettermarks, 7.5px card lettering. Below the floor on purpose — recognised rather than read (the 600 exception: §2 of the guide).
 
 **What was deleted**
 
@@ -44,11 +44,7 @@ In the 11–16px band the steps are 1px, and that is enough (`domains/type/ladde
 
 ## Fixed sizes, not `rem`, and why that's a choice
 
-The reference implementation uses `px` throughout (`text-[14px]`, not `text-sm` or `0.875rem`).
-
-The trade: `rem` respects a user's browser font-size setting and `px` doesn't, a real accessibility cost. But this hierarchy depends on precise 1px relationships in the 11–16 band, a root scaled to 20px turns them into 15px steps that break the ladder, and browser *zoom* — which everyone uses, and which scales `px` fine — already covers the need.
-
-If your audience skews toward users who set a root font size — documentation, government, healthcare — use `rem` and accept a looser ladder. Convert at a fixed 16px root: 18px → 1.125rem, 14px → 0.875rem, 13px → 0.8125rem. Never mix the two (the domain's unit dial).
+The reference implementation uses `px` throughout (`text-[14px]`, not `text-sm` or `0.875rem`), to keep the 1px steps of the 11–16 band exact under a scaled root; the trade is the domain's unit dial. Moving to `rem`, convert at a fixed 16px root: 18px → 1.125rem, 14px → 0.875rem, 13px → 0.8125rem.
 
 ## Keeping every element on it
 

package/plugins/keyline/skills/keyline/glass/type/weight-and-tracking.md

@@ -16,13 +16,11 @@ All body copy. All prose. Deks. Meta lines. Tags. Tooltips. Timestamps. Quiet na
 **500 — structure and state.**
 Headings h1–h4. `<strong>`. The active row in a table of contents. Names and wordmarks. Captions that label an image rather than describe it. Lettermarks. Company/role titles in a list, where the role is structural and the date supporting.
 
-### Quiet and lifted, by scenario
+The lists are defaults; the choice is made per spot (domain law 5): the same 13px line is 400 as a date under a title and 500 as the name heading a group.
 
-The lists above are defaults; the choice is made per spot, by the rules in domain law 5. The same 13px line is 400 as a date under a title and 500 as the name heading a group, because the job changed, not the importance. With two weights, a step is the whole axis, so when a screen feels heavy the fix is moving lines back to 400, one context at a time; there's never a lighter scale to reach for.
+### 300
 
-### When 300 is legitimate
-
-Rarely, and never for text read at length: at a very large display size (48px+), where 400 starts to look heavy, or a decorative numeral. If your interface tops out at 30px — most do — you don't need it. The reference implementation loaded 300 for a while and never used it; dropping it from the font request was a straight performance win.
+Not loaded. The reference implementation loaded it for a while and never used it; dropping it from the font request was a straight performance win.
 
 ### Weight as an accessibility signal
 
@@ -32,23 +30,9 @@ The active table-of-contents row takes the primary text colour *and* weight 500
 className={`… ${tone} ${state === "active" ? "font-medium" : ""}`}
 ```
 
-Weight is cheaper here than a background pill, border or icon, each of which adds visual weight to a list meant to be quiet.
-
 ## Tracking
 
-### The ladder
-
-| Size | Tracking | Reasoning |
-|---|---|---|
-| 7.5px | −0.01em | Card lettering, set solid. The exception below the floor — see the note. |
-| 8.5–11px | +0.02em | Tiny glyphs and near-caps need air or the counters close up. |
-| 12–14px | 0 | Default metrics are designed for this range. Leave them. |
-| 16px | −0.015em | Enough to look set; small enough to be invisible as a decision. |
-| 18px | −0.02em | A page title is a tighter, more deliberate object than a section heading two pixels below. |
-
-Only two rows are the negative-tracking-at-size rule, because the ladder tops out at 18px. An earlier table ran to 30px at −0.025em, with separate values for a 19px heading and a 19px quote; all three sizes left the ladder and took their tracking with them.
-
-The 7.5px row doesn't contradict the 8.5–11px one: that lettering is set solid at near-caps size on a card, so the tightening compensates for the *setting*, not the size. It's also the one place a 600 weight is allowed. Two exceptions in one place hint you're outside the text system — which you are, since nobody reads it.
+The values are §4 of `glass/type/guide.md`. Only 16px and 18px are the negative-tracking-at-size rule, because the ladder tops out at 18px. The 7.5px card lettering's −0.01em doesn't contradict the lettermarks' +0.02em: it is set solid at near-caps size, so the tightening compensates for the *setting*, not the size.
 
 ### The 8.5px lettermark
 

package/plugins/keyline/skills/keyline/scripts/check/css.mjs

@@ -13,12 +13,6 @@ export function blankComments(text) {
   return text.replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, " "));
 }
 
-export function lineAt(text, offset) {
-  let line = 1;
-  for (let i = 0; i < offset && i < text.length; i++) if (text.charCodeAt(i) === 10) line++;
-  return line;
-}
-
 /** Lines start offsets, for fast offset → line lookups on big files. */
 export function lineIndex(text) {
   const starts = [0];
@@ -44,8 +38,7 @@ export function parseCss(source, baseLine = 1) {
   const at = lineIndex(text);
   const decls = [];
   const atRules = [];
-  const blocks = []; // { selector, atRules, decls }
-  const stack = []; // open blocks: { kind: 'rule'|'at', prelude, block }
+  const stack = []; // open blocks: { kind: 'rule'|'at', prelude, block: { decls } }
   let start = 0;
   let quote = null;
   let paren = 0;
@@ -65,7 +58,7 @@ export function parseCss(source, baseLine = 1) {
     const value = raw.slice(colon + 1).trim();
     const lead = from + raw.search(/\S/);
     const ctx = context();
-    const d = { prop, value, line: at(lead) + baseLine - 1, offset: lead, selector: ctx.selector, atRules: ctx.atRules, block: ctx.block };
+    const d = { prop, value, line: at(lead) + baseLine - 1, selector: ctx.selector, atRules: ctx.atRules, block: ctx.block };
     decls.push(d);
     ctx.block?.decls.push(d);
   };
@@ -85,10 +78,8 @@ export function parseCss(source, baseLine = 1) {
       const prelude = text.slice(start, i).trim().replace(/\s+/g, " ");
       const kind = prelude.startsWith("@") ? "at" : "rule";
       const lead = start + text.slice(start, i).search(/\S/);
-      const block = { selector: kind === "rule" ? prelude : context().selector, atRules: [...context().atRules, ...(kind === "at" ? [prelude] : [])], decls: [], line: at(Math.max(lead, 0)) + baseLine - 1 };
-      if (kind === "at") atRules.push({ prelude, line: block.line });
-      blocks.push(block);
-      stack.push({ kind, prelude, block });
+      if (kind === "at") atRules.push({ prelude, line: at(Math.max(lead, 0)) + baseLine - 1 });
+      stack.push({ kind, prelude, block: { decls: [] } });
       start = i + 1;
     } else if (c === ";") {
       if (stack.length) pushDecl(start, i);
@@ -103,7 +94,7 @@ export function parseCss(source, baseLine = 1) {
       start = i + 1;
     }
   }
-  return { decls, atRules, blocks };
+  return { decls, atRules };
 }
 
 /** Parse a `style="..."` attribute's body. */

package/plugins/keyline/skills/keyline/scripts/check/design.mjs

@@ -50,7 +50,9 @@ export function readDesign(root) {
   // or mentions one — their values are the ladder.
   const layout = section(md, "Layout");
   const zLadder = new Set();
-  for (const row of layout.split("\n").filter((l) => /^\|\s*`?z\./.test(l) || (l.startsWith("|") && /`-?z-\[?-?\d|`z\./.test(l)))) {
+  // A project rung (`--z-header`, `$z-header`, a `z-header` utility) counts when it opens the token cell, the row's second.
+  const zCell = (c) => /^`(--|\$)?z-[\w-]+`/.test(c);
+  for (const row of layout.split("\n").filter((l) => /^\|\s*`?z\./.test(l) || (l.startsWith("|") && (/`-?z-\[?-?\d|`z\./.test(l) || zCell((l.split("|")[2] ?? "").trim()))))) {
     const cells = row.split("|").slice(1, -1).map((c) => c.trim());
     for (const c of cells.slice(1)) for (const m of c.matchAll(/(?<![\w.#-])(-?\d+)(?![\w.%])/g)) zLadder.add(Number(m[1]));
   }

package/plugins/keyline/skills/keyline/scripts/check/files.mjs

@@ -1,44 +1,88 @@
 /**
- * Which files the detector reads. The same skips as scan.mjs, so the two never
- * disagree about what counts as the project's interface.
+ * Which files Keyline reads. One walker for the detector (check.mjs) and the
+ * inventory (scan.mjs), so the two skip the same folders and match ignores the
+ * same way; each passes only the extensions and filters its job needs.
  */
 import { readdirSync, statSync } from "node:fs";
-import { extname, join, relative, sep } from "node:path";
+import { basename, extname, join, relative, sep } from "node:path";
 
+/** Dependencies, build output, served assets and reports. Dot-folders are skipped wholesale, bar `.storybook`. */
 export const SKIP_DIRS = new Set([
-  "node_modules", ".git", ".next", ".nuxt", ".output", ".svelte-kit", ".turbo",
-  ".vercel", ".cache", "dist", "build", "out", "coverage", "vendor",
-  "storybook-static", ".claude", ".agents", "public", "static",
+  "node_modules", "dist", "build", "out", "coverage", "vendor", "storybook-static", "public", "static",
+  "keyline-report", "smoke-report",
 ]);
 export const STYLE = new Set([".css", ".scss", ".sass", ".less", ".pcss"]);
 export const MARKUP = new Set([".tsx", ".jsx", ".ts", ".js", ".mjs", ".vue", ".svelte", ".astro", ".html", ".mdx"]);
-const SKIP_FILES = /\.(min|d|test|spec|stories|config)\.[a-z]+$|^(eslint|postcss|tailwind|next|vite|vitest|jest|playwright)\.config\./;
+/** Minified, declaration, test and story files: generated, or not the interface. */
+export const GENERATED = /\.(min|test|spec|stories)\.|\.d\.[a-z]+$/;
+/** Tool configs. Not the interface, though a Tailwind config holds theme values. */
+export const CONFIG = /\.config\.[a-z]+$|^(eslint|postcss|tailwind|next|vite|vitest|jest|playwright)\.config\./;
 
-/** Every style and markup file under `paths`, relative to `root`, minus ignores. */
-export function collect(root, paths, ignores) {
+const clean = (ig) => ig.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+
+/** A test for paths relative to the root: `src/content` drops `src/content/a.tsx`, never `src/contentful`. */
+export function ignoredBy(ignores = []) {
+  const list = ignores.map(clean).filter(Boolean);
+  return (rel) => list.some((ig) => rel === ig || rel.startsWith(ig + "/"));
+}
+
+/**
+ * Every file under `paths` whose extension is in `accept` and whose name `skip`
+ * doesn't match, up to `maxSize` bytes (bigger is a bundle, not source). Folders
+ * in SKIP_DIRS and dot-folders are passed over unless named in `paths`;
+ * symlinked folders aren't followed.
+ * @returns {{ abs: string, rel: string, ext: string }[]} rel is relative to root, with `/`
+ */
+export function walk(root, { paths = [root], accept, skip = GENERATED, maxSize = 400_000, ignores = [] }) {
   const out = [];
-  const ignored = (rel) => ignores.some((ig) => ig && (rel === ig || rel.startsWith(ig.endsWith("/") ? ig : ig + "/")));
-  const visit = (abs) => {
-    const rel = relative(root, abs).split(sep).join("/");
-    if (rel && ignored(rel)) return;
-    let st;
+  const ignored = ignoredBy(ignores);
+  const rel = (abs) => relative(root, abs).split(sep).join("/");
+  const file = (abs, name, size) => {
+    const ext = extname(name);
+    if (!accept.has(ext) || skip?.test(name)) return;
+    if ((size ?? statSync(abs).size) > maxSize) return;
+    out.push({ abs, rel: rel(abs) || name, ext });
+  };
+  const dir = (abs) => {
+    let entries;
     try {
-      st = statSync(abs);
+      entries = readdirSync(abs, { withFileTypes: true });
     } catch {
       return;
     }
-    if (st.isDirectory()) {
-      const name = abs.split(sep).pop();
-      if (rel && (SKIP_DIRS.has(name) || (name.startsWith(".") && name !== ".storybook"))) return;
-      for (const e of readdirSync(abs)) visit(join(abs, e));
-      return;
+    for (const e of entries) {
+      const child = join(abs, e.name);
+      if (ignored(rel(child))) continue;
+      if (e.isDirectory()) {
+        if (!SKIP_DIRS.has(e.name) && (!e.name.startsWith(".") || e.name === ".storybook")) dir(child);
+      } else {
+        try {
+          file(child, e.name);
+        } catch {}
+      }
     }
-    const ext = extname(abs);
-    if (!(STYLE.has(ext) || MARKUP.has(ext))) return;
-    if (SKIP_FILES.test(abs.split(sep).pop())) return;
-    if (st.size > 400_000) return; // generated bundles, not source
-    out.push({ abs, rel: rel || abs.split(sep).pop(), ext, kind: STYLE.has(ext) ? "style" : "markup" });
   };
-  for (const p of paths) visit(p);
+  for (const p of paths) {
+    const r = rel(p);
+    if (r && ignored(r)) continue;
+    let st;
+    try {
+      st = statSync(p);
+    } catch {
+      continue;
+    }
+    if (st.isDirectory()) dir(p);
+    else file(p, basename(p), st.size);
+  }
   return out;
 }
+
+const DETECTOR_SKIP = new RegExp(`${GENERATED.source}|${CONFIG.source}`);
+
+/** The detector's files: style and markup, minus generated files and tool configs. */
+export function collect(root, paths, ignores) {
+  return walk(root, { paths, ignores, accept: new Set([...STYLE, ...MARKUP]), skip: DETECTOR_SKIP }).map((f) => ({
+    ...f,
+    kind: STYLE.has(f.ext) ? "style" : "markup",
+  }));
+}

package/plugins/keyline/skills/keyline/scripts/check/markup.mjs

@@ -57,7 +57,7 @@ export function readMarkup(source, ext) {
   text = text.replace(/<!--[\s\S]*?-->/g, (m) => m.replace(/[^\n]/g, " "));
   const at = lineIndex(text);
 
-  const classLists = []; // { value, offset, line, tokens: [{...splitClass, line}] }
+  const classLists = []; // { line, tokens: [{...splitClass, line}], tag }
   const seen = new Set();
   const addList = (value, offset, origin) => {
     if (seen.has(offset)) return;
@@ -66,7 +66,7 @@ export function readMarkup(source, ext) {
     const re = /\S+/g;
     let m;
     while ((m = re.exec(value))) tokens.push({ ...splitClass(m[0]), line: at(offset + m.index) });
-    if (tokens.length) classLists.push({ value, offset, line: at(offset), tokens, origin, tag: origin === "attribute" ? tagAround(offset, value.length) : "" });
+    if (tokens.length) classLists.push({ line: at(offset), tokens, tag: origin === "attribute" ? tagAround(offset, value.length) : "" });
   };
 
   /** The opening tag a class attribute sits in, for rules that need its element or attributes. */
@@ -93,7 +93,7 @@ export function readMarkup(source, ext) {
       addList(s[1] === "`" ? staticParts(s[2]) : s[2], open + 1 + s.index + 1, "helper");
     }
   }
-  if (!isHtmlLike || ext !== ".html") {
+  if (ext !== ".html") {
     for (const m of text.matchAll(EXPR_STRING)) {
       const value = m[2];
       if (value.length < 3 || !CLASSY.test(value) || !TAILWINDISH.test(value)) continue;

package/plugins/keyline/skills/keyline/scripts/check/rules.mjs

@@ -226,8 +226,16 @@ const colorRules = [
         // recipe, not a palette colour; the recipe itself is what depth law 4 wants
         // kept in one definition. A tinted shadow (a blue glow) still counts.
         if (/^(box-shadow|text-shadow)$/.test(d.prop) && neutralOnly(d.value)) continue;
+        // Gradient stops and filter lights only exist inside SVG artwork, which colour law 1 exempts.
+        if (/^(stop-color|flood-color|lighting-color)$/.test(d.prop)) continue;
         const c = literalColor(d.value);
-        if (c) out.push({ ...where(d), severity: "warning", message: `\`${c}\` typed into \`${d.prop}\`${d.inline ? " in an inline style" : ""}. Give it a token named for its job (a text tier, a border, a status), so a theme or a contrast fix changes it once.` });
+        if (!c) continue;
+        // fill and stroke paint SVG: artwork (exempt) or an icon (should be currentColor). A regex can't tell which.
+        if (/^(fill|stroke)$/.test(d.prop)) {
+          out.push({ ...where(d), severity: "info", message: `\`${c}\` painted into \`${d.prop}\`. Inside artwork marked \`role="img"\` that's fine (colour law 1); on an icon, use \`currentColor\` so it follows its label.` });
+          continue;
+        }
+        out.push({ ...where(d), severity: "warning", message: `\`${c}\` typed into \`${d.prop}\`${d.inline ? " in an inline style" : ""}. Give it a token named for its job (a text tier, a border, a status), so a theme or a contrast fix changes it once.` });
       }
       for (const c of tw(facts, (b) => TAILWIND_ARBITRARY_COLOR.test(b))) {
         out.push({ ...where(c), severity: "warning", message: `\`${c.base}\` puts a raw colour in a class. Map it to a token named for its job.` });

package/plugins/keyline/skills/keyline/scripts/check.mjs

@@ -92,8 +92,8 @@ export function gather(root, files) {
       const VIEWPORT_VALUE = /<meta\b[^>]*\bviewport\b[^>]*>|["'`][^"'`\n<>]*width\s*=\s*device-width[^"'`\n<>]*["'`]/gi;
       for (const v of m.text.matchAll(VIEWPORT_VALUE)) for (const z of v[0].matchAll(LOCK)) facts.zoomLocks.push({ file: f.rel, line: at(v.index + z.index) });
       for (const z of m.text.matchAll(/\bmaximumScale\s*:\s*1\b|\buserScalable\s*:\s*false\b/g)) facts.zoomLocks.push({ file: f.rel, line: at(z.index) });
-      if (MOTION_IMPORT.test(m.text)) {
-        const imp = m.text.match(MOTION_IMPORT);
+      const imp = m.text.match(MOTION_IMPORT);
+      if (imp) {
         noteAnimation({ file: f.rel, line: at(imp.index) });
         for (const d of m.text.matchAll(/\bduration\s*:\s*(\d*\.?\d+)\b/g)) {
           // A spring's duration is a settling time set by its character, not a tier.
@@ -277,6 +277,9 @@ export function run(argv) {
   }
 
   const result = check({ root: opts.root, paths: opts.paths.length ? opts.paths : ["."], ignores: opts.ignores, rules: opts.rules });
+  // The verdict counts every finding, so --quiet trims the output, never the exit code.
+  const all = summarise(result.findings);
+  const failed = all.error > 0 || (opts.strict && all.warning > 0);
   if (opts.quiet) result.findings = result.findings.filter((f) => f.severity === "error");
   const s = summarise(result.findings);
 
@@ -286,7 +289,7 @@ export function run(argv) {
   } else {
     console.log(human(result, { all: opts.all, color: process.stdout.isTTY && !process.env.NO_COLOR }));
   }
-  return s.error > 0 || (opts.strict && s.warning > 0) ? 1 : 0;
+  return failed ? 1 : 0;
 }
 
 if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {

package/plugins/keyline/skills/keyline/scripts/contrast.mjs

@@ -150,4 +150,6 @@ if (ladder) {
 if (rest.length !== 2) die("give a foreground and a background (or --ladder)");
 const r = ratio(rest[0], rest[1]);
 console.log(`${r >= floor ? "✓" : "✗"} ${fmt(r)} (floor ${floor}:1)`);
+// 1:1 means the two colours came out identical — nearly always the arguments, not the design.
+if (r < 1.01) console.error(`contrast: ${rest[0]} and ${rest[1]} come out as the same colour. Check the order: <fg> <bg>, or --over <backdrop> <fg> <bg>, or --ladder <bg> <fg>…`);
 process.exit(r >= floor ? 0 : 2);

package/plugins/keyline/skills/keyline/scripts/scan.mjs

@@ -16,8 +16,9 @@
  * at runtime or a class built by string concatenation. When the summary and the
  * code disagree, the code wins — open the file the summary points at.
  */
-import { readdirSync, readFileSync, statSync, existsSync } from "node:fs";
-import { join, relative, extname, basename } from "node:path";
+import { readFileSync, existsSync } from "node:fs";
+import { join, basename, resolve } from "node:path";
+import { walk, STYLE as CHECKED_STYLE, MARKUP as CHECKED_MARKUP } from "./check/files.mjs";
 
 const argv = process.argv.slice(2);
 const json = argv.includes("--json");
@@ -33,37 +34,14 @@ if (!existsSync(root)) {
   process.exit(1);
 }
 
-const SKIP_DIRS = new Set([
-  "node_modules", ".git", ".next", ".nuxt", ".output", ".svelte-kit", ".turbo",
-  ".vercel", ".cache", "dist", "build", "out", "coverage", "vendor",
-  "storybook-static", ".claude", "public", "static",
-]);
-const STYLE = new Set([".css", ".scss", ".sass", ".less", ".pcss", ".styl"]);
-const MARKUP = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".vue", ".svelte", ".astro", ".html", ".mdx"]);
-
-/* ── Walk ─────────────────────────────────────────────────────────────────── */
-
-const files = [];
-(function walk(dir) {
-  let entries;
-  try {
-    entries = readdirSync(dir, { withFileTypes: true });
-  } catch {
-    return;
-  }
-  for (const e of entries) {
-    if (e.name.startsWith(".") && e.isDirectory() && e.name !== ".storybook") continue;
-    const path = join(dir, e.name);
-    if (ignores.some((ig) => ig && relative(root, path).startsWith(ig))) continue;
-    if (e.isDirectory()) {
-      if (!SKIP_DIRS.has(e.name)) walk(path);
-    } else if (STYLE.has(extname(e.name)) || MARKUP.has(extname(e.name))) {
-      if (/\.min\.|\.d\.ts$|\.test\.|\.spec\.|\.stories\./.test(e.name)) continue;
-      if (statSync(path).size > 1_000_000) continue;
-      files.push(path);
-    }
-  }
-})(root);
+/*
+ * The detector's walker and folder skips, read wider: an inventory wants every
+ * hand-written value, so it also reads Stylus and CommonJS, keeps tool configs
+ * (a Tailwind config is where a theme is declared) and allows files up to 1 MB.
+ */
+const STYLE = new Set([...CHECKED_STYLE, ".styl"]);
+const MARKUP = new Set([...CHECKED_MARKUP, ".cjs"]);
+const files = walk(resolve(root), { accept: new Set([...STYLE, ...MARKUP]), maxSize: 1_000_000, ignores });
 
 /* ── Tallies ──────────────────────────────────────────────────────────────── */
 
@@ -74,7 +52,7 @@ function count(bucket, value, file) {
   tallies[bucket] ??= new Map();
   const entry = tallies[bucket].get(v) ?? { n: 0, files: new Set() };
   entry.n++;
-  entry.files.add(relative(root, file));
+  entry.files.add(file);
   tallies[bucket].set(v, entry);
 }
 
@@ -91,7 +69,7 @@ const classWords = new Map();
 const signals = {};
 function signal(name, file) {
   signals[name] ??= new Set();
-  signals[name].add(relative(root, file));
+  signals[name].add(file);
 }
 
 /** Tailwind's scale names, so `text-sm` counts as a size and `text-red-500` doesn't. */
@@ -156,9 +134,9 @@ const SIGNALS = [
   ["numerals: tabular-nums", /tabular-nums|font-variant-numeric/],
 ];
 
-for (const file of files) {
-  const text = readFileSync(file, "utf8");
-  const kind = STYLE.has(extname(file)) ? "style" : "markup";
+for (const { abs, rel: file, ext } of files) {
+  const text = readFileSync(abs, "utf8");
+  const kind = STYLE.has(ext) ? "style" : "markup";
 
   for (const [bucket, re, group, only] of RULES) {
     if (only !== "all" && only !== kind) continue;
@@ -175,7 +153,7 @@ for (const file of files) {
     if (m[1].startsWith("--tw-")) continue;
     const entry = props.get(m[1]) ?? { values: [], files: new Set() };
     if (entry.values.length < 4 && !entry.values.includes(m[2].trim())) entry.values.push(m[2].trim());
-    entry.files.add(relative(root, file));
+    entry.files.add(file);
     props.set(m[1], entry);
   }
   if (kind === "markup") {
@@ -196,14 +174,20 @@ for (const file of files) {
  * but it's the difference between "unused" and "used in 40 files".
  */
 const NAMESPACES = ["color", "font", "text", "radius", "shadow", "ease", "animate", "container", "spacing", "tracking", "leading", "breakpoint", "blur", "inset-shadow", "drop-shadow"];
-function utilityUses(prop) {
+/** Class-word uses by every tail after a hyphen: `hover:text-ink-soft` counts for `ink-soft` and `soft`. */
+const bySuffix = new Map();
+for (const [word, c] of classWords) {
+  for (let i = word.indexOf("-"); i >= 0; i = word.indexOf("-", i + 1)) {
+    const tail = word.slice(i + 1);
+    bySuffix.set(tail, (bySuffix.get(tail) ?? 0) + c);
+  }
+}
+const utilityCount = new Map();
+for (const prop of props.keys()) {
   const ns = NAMESPACES.find((n) => prop.startsWith(`--${n}-`));
-  if (!ns) return 0;
-  const name = prop.slice(ns.length + 3);
-  let n = 0;
-  for (const [word, c] of classWords) if (word.endsWith(`-${name}`) && word !== name) n += c;
-  return n;
+  utilityCount.set(prop, ns ? (bySuffix.get(prop.slice(ns.length + 3)) ?? 0) : 0);
 }
+const utilityUses = (prop) => utilityCount.get(prop) ?? 0;
 const uses = (prop) => (propUses.get(prop) ?? 0) + utilityUses(prop);
 
 /* ── Stack ────────────────────────────────────────────────────────────────── */

package/plugins/keyline/skills/keyline/system/design-md.md

@@ -80,9 +80,9 @@ Copy this shape. Drop any table or row that doesn't apply; add project roles und
 
 | Role | Name here | Value |
 |---|---|---|
-| `z.popover` | `z-popover` | 50 |
-| `z.overlay` | `z-overlay` | 80 |
-| `z.toast` | `z-toast` | 90 |
+| `z.popover` | `z-popover` | 20 |
+| `z.overlay` | `z-overlay` | 60 |
+| `z.toast` | `z-toast` | 70 |
 
 **Breakpoints**
 
@@ -123,7 +123,7 @@ Plus springs by character, and the reduced-motion policy in one sentence.
 ## Decisions
 
 - YYYY-MM-DD — Card titles at 500, not 600: they read heavy beside the pane title. (User decision; the type guide dial.)
-- YYYY-MM-DD — Three weights, not two: the billing table needs a middle weight for column totals. (Client feedback; the type guide dial override.)
+- YYYY-MM-DD — Three weights, not two: the billing screens need a 600 heading weight above the 500 that lifts lines inside rows. (Client feedback; the type guide dial override.)
 - YYYY-MM-DD — Page on white `surface.page`, not the grey `bg-neutral-50`: the text tiers failed against the grey. (Law; the colour guide.)
 
 ## Open issues

package/plugins/keyline/skills/keyline/system/guide.md

@@ -33,7 +33,7 @@ Five places projects have quietly broken a law:
 - **One token doing two jobs.** A grey used for borders and text: a border needs 3:1, text 4.5:1, and one value rarely serves both. Record the coupling as an open issue; don't split it yet.
 - **A job with no token.** Captions at six greys, durations typed inline. Propose a name in the project's style (`design-md.md` says how to detect it) and mark it `proposed`. Where a whole domain has no tokens — no type tokens, no motion tokens — record that as one open issue, not one per role; that domain's refining pass proposes a full set in the project's style, marked `proposed`.
 - **Roles the list doesn't have.** A `keyline`, a `pull-quote`, a `kicker`: record each as a project role under its nearest canonical parent, with what separates it — size, weight, leading, colour or a rule. If nothing does, that's a finding.
-- **Boxes as the default.** Every section, stat and list in a card, cards inside cards, a bento grid of unlike sections, tinted strips behind labels, uppercase eyebrows, several chip shapes, a second hue that calls for attention (a hue family answering what, where or who under `product` is not one), success colour on done steps where completion isn't the news (a sequence the reader passes through, not a board or queue). Count the boxes per main screen and list each that holds more than one object (depth law 2, layout law 3). If the user has a reference interface they've already approved, screenshot each main screen beside it; the gaps are open issues.
+- **Boxes as the default.** Every section, stat and list in a card, cards inside cards, a bento grid of unlike sections, tinted strips behind labels, uppercase eyebrows (outside an `expressive` eyebrow role), several chip shapes, a second hue that calls for attention (a hue family answering what, where or who under `product` is not one), success colour on done steps where completion isn't the news (a sequence the reader passes through, not a board or queue). Count the boxes per main screen and list each that holds more than one object (depth law 2, layout law 3); a panel that layout law 3's table gives a settings or form group is not one. If the user has a reference interface they've already approved, screenshot each main screen beside it; the gaps are open issues.
 - **Values on no ladder.** Twenty-three font sizes, fourteen radii. Cluster them by usage, propose the ladder, list the strays that could snap to a neighbour unseen.
 
 Compute contrast; don't estimate it:
@@ -46,7 +46,7 @@ node <keyline>/scripts/contrast.mjs --ladder "#ffffff" "#16161a" "#4b4b52" "#6b6
 
 ## 3. Choose the preset
 
-From what the reader is mostly doing — reading, working, or being persuaded — propose `editorial`, `product` or `expressive` (`presets.md`). Offer `glass` only when the user wants modimihir.com's exact system rather than their own; it fills the dials from `glass/`, under the project's existing names wherever it has them.
+From what the reader is mostly doing — reading, working, or being persuaded — propose `editorial`, `product` or `expressive` (`presets.md`). Offer `glass` only when the user wants modimihir.com's exact system rather than their own; it fills the dials from the tables in each `glass/<domain>/guide.md`, under the project's existing names wherever it has them.
 
 State the evidence: *"Mostly long-form pages under `app/blog`, two weights in use, one accent — this reads as `editorial`."* Mixed projects get a base preset plus areas: `product`, with `app/(marketing)/** → expressive`.
 
@@ -70,20 +70,16 @@ Don't ask what you can find out, and don't ask for approval of the whole mapping
 Follow `system/design-md.md`: the project's names in `Name here`, canonical roles in `Role`, values as the source states them, measured contrast for every text tier, per-theme columns only where themes exist, nothing for roles the project lacks. Then:
 
 - **`## Decisions`** — every dial set differently from the preset, with its reason, or a question mark if unknown.
-- **`## Open issues`** — every law the code breaks, one line each with evidence (a ratio, a count, a file). Before writing them, read the law headings (the `### N.` lines) of each domain guide you cite, so every citation names the right law. **Don't fix anything** unless asked; a setup run that also rewrites forty components can't be reviewed.
+- **`## Open issues`** — every law the code breaks, one line each with evidence (a ratio, a count, a file). Cite each law by the right number (`commands/init.md`). **Don't fix anything** unless asked; a setup run that also rewrites forty components can't be reviewed.
 
 Tell the user briefly: the preset and why, how many roles mapped cleanly, what you proposed names for, and the three most important open issues.
 
 ## 6. Generating tokens, only when asked
 
-The set ships no token files, because the right file depends on the stack. Asked for tokens — for a new project, or to fill `proposed` rows — generate them **in the project's existing mechanism**: a Tailwind v4 `@theme` block, a `tailwind.config` extension, CSS custom properties, a JS theme object, a design-tokens JSON. Match the existing layout and naming; never add a second token system beside the first.
+Apart from the `glass` preset's drop-in files under `glass/<domain>/assets/`, the set ships no token files, because the right file depends on the stack. Asked for tokens — for a new project, or to fill `proposed` rows — generate them **in the project's existing mechanism**: a Tailwind v4 `@theme` block, a `tailwind.config` extension, CSS custom properties, a JS theme object, a design-tokens JSON. Match the existing layout and naming; never add a second token system beside the first.
 
 With no tokens yet, `presets.md` and each domain guide's `## Dials` section give defaults. Say they're defaults, choose names with the user, and record the choices in `DESIGN.md`.
 
-## How the other commands use this file
-
-Each domain command reads `DESIGN.md`, finds its section, and works in the project's names. If the file is missing, it runs steps 1–2 for its own domain, does the task and recommends `/keyline init` — it doesn't refuse. A decision that changes the system — a new role, a moved dial, a law knowingly broken, a change a law forced that a later session might undo — goes back under `Decisions` — dated, marked user decision, client feedback or law, newest first, replacing what it supersedes — which is what keeps the file true after the first day.
-
 ## Checklist
 
 - [ ] An existing `DESIGN.md` was reconciled, not overwritten; every user-chosen name and decision survived.

package/plugins/keyline/skills/keyline/system/presets.md

@@ -25,34 +25,34 @@ When the evidence doesn't settle it, propose one, say what evidence you used, an
 
 *The interface should disappear so the reading doesn't.* Restraint is the point, and a single loud moment reads as craft because nothing else competes with it.
 
-- **Type** — a dense ladder that keeps the reading loudest, with an article's title clearly opening the piece (up to 2.25 × body); index and chrome titles lower. Two weights. A sans for interface text is allowed beside a serif reading face. Roles that share a size separate on weight, leading or a rule.
-- **Colour** — near-monochrome. One accent, spent on focus. At most one further chromatic exception, justified structurally. Links usually in the text colour.
-- **Layout** — one reading measure every page shares; rails and asides live outside it. Generous, asymmetric vertical rhythm.
-- **Surfaces** — mostly flat. Elevation reserved for things that float; translucency, if any, only on chrome.
-- **Motion** — short, and only where it makes a change legible. Nothing loops. One set piece, at most, once a session.
+- **Type** — a dense ladder that keeps the reading loudest.
+- **Colour** — near-monochrome, the accent spent on focus.
+- **Layout** — one reading measure every page shares.
+- **Surfaces** — mostly flat; translucency, if any, only on chrome.
+- **Motion** — short, and only where it makes a change legible.
 
 ## `product`
 
 *The interface is a tool, and the reader is fluent in it.* Density, predictability and scannability beat atmosphere. Signal has to survive a screen full of data.
 
-- **Type** — tighter, smaller steps; UI and data roles dominate. Two weights, strong at 500; labels in sentence case, never uppercase eyebrows. Tabular figures on every number, scoped to numeric elements.
-- **Colour** — near-monochrome neutral ground with a real status palette (danger, warning, success, info), each a foreground/background pair. One accent hue for primary action, focus, selection (the current nav item on a 25% accent tint with accent icon and label) and the primary data series, and no second highlight hue. Brand colour already in the design stays where it has a job. Colour marks what needs a person, not what is finished. Colour for meaning, never for decoration.
-- **Layout** — an app shell rather than a single measure: one navigation surface — a sidebar holding every destination, no top bar repeating it — then content and an optional inspector, every page under its own header bar, forms and settings capped at a form measure. Improving one screen keeps the navigation it has. Sections stack, each opened by its heading, and peer sections are parted by a full-bleed hairline; no bento mosaics or stat tiles. That is the default for a new system; an existing design keeps its own section device (`commands/refine.md`, the limits). Tighter spacing, still grouped asymmetrically. Prose inside the product (settings help, empty-state copy) still sits at a reading measure.
-- **Surfaces** — content on the page, rows parted by hairlines; a data table may take one hairline frame; a settings group that saves together takes a hairline panel; a card only for one object, never a card in a card. A clear, small elevation ladder: flat page, raised cards, floating menus, modal overlays. Hairlines do more work than shadows.
-- **Motion** — shortest of the three. State feedback is near-instant; nothing delays a repeated action. Springs only where something is dragged or thrown.
+- **Type** — tighter, smaller steps; UI and data roles dominate.
+- **Colour** — near-monochrome with a real status palette, and one accent hue that acts.
+- **Layout** — an app shell rather than a single measure; tighter spacing, still grouped.
+- **Surfaces** — content on the page, rows parted by hairlines; a card only for one object.
+- **Motion** — shortest of the three; nothing delays a repeated action.
 
 ## `expressive`
 
 *The interface is making an impression, usually once.* Scale, colour and motion are allowed to carry brand — but still by rule, or it turns into a template.
 
-- **Type** — a real display tier far above body, possibly a second family for it. Display, title and section headings fluid. Wider scale, still assigned to roles rather than derived from a ratio. Tracking correction matters most here.
-- **Colour** — a brand palette used broadly, with rules about where each colour may go. Chromatic exceptions still named and counted, just more of them.
-- **Layout** — sections may break the reading measure and go full-bleed; the measure still governs any paragraph longer than two lines.
-- **Surfaces** — depth, gradients and translucency allowed as brand material, each with its fallback.
-- **Motion** — longer and more characterful on entrances; exits still get out of the way. A few set pieces, each once. Reduced motion still gets a real alternative.
+- **Type** — a real display tier far above body, possibly a second family.
+- **Colour** — a brand palette used broadly, each colour placed by rule.
+- **Layout** — sections may go full-bleed; paragraphs keep the measure.
+- **Surfaces** — depth, gradients and translucency as brand material, each with its fallback.
+- **Motion** — longer and more characterful on entrances; exits still get out of the way.
 
 ## `glass`
 
-The Glass preset's exact values: `editorial` in character, with every dial already decided on [modimihir.com](https://modimihir.com). Offer it only when the user wants that system itself rather than their own — `/keyline init` copies its values from `glass/` into `DESIGN.md`, in the project's own names wherever the project already has names, and `glass/<domain>/guide.md` supplies the exact recipes, with drop-in token files and components under each `assets/`.
+The Glass preset's exact values: `editorial` in character, with every dial already decided on [modimihir.com](https://modimihir.com). Offer it only when the user wants that system itself rather than their own — `/keyline init` copies its values from the tables in each `glass/<domain>/guide.md` into `DESIGN.md`, in the project's own names wherever the project already has names, and each guide supplies the exact recipes, with drop-in token files and components under its `assets/`.
 
 A `glass` project can still override a dial. It should expect to: the Glass values were chosen for one text-heavy portfolio, and a project that isn't one will find the places they don't fit.