trykeyline 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,340 @@
+#!/usr/bin/env node
+/**
+ * Inventory the design values a codebase actually uses, with no dependencies.
+ *
+ *   node scan.mjs [root]            a markdown summary, top values first
+ *   node scan.mjs [root] --json     everything, for when the summary isn't enough
+ *   node scan.mjs [root] --ignore src/content --ignore docs
+ *                                   leave out paths holding prose or examples, not UI
+ *
+ * This is evidence, not a verdict. It counts what's written in the source —
+ * custom properties, Tailwind utilities, raw CSS values, motion configs — so that
+ * setup can see which values are the system and which are strays. Frequency is
+ * the signal: a size used 400 times is a role, a size used twice is a question.
+ *
+ * It reads text, not a compiled stylesheet, so it can't resolve a value computed
+ * 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";
+
+const argv = process.argv.slice(2);
+const json = argv.includes("--json");
+const ignores = [];
+const positional = [];
+for (let i = 0; i < argv.length; i++) {
+  if (argv[i] === "--ignore") ignores.push(argv[++i] ?? "");
+  else if (!argv[i].startsWith("-")) positional.push(argv[i]);
+}
+const root = positional[0] ?? ".";
+if (!existsSync(root)) {
+  console.error(`scan: no such directory: ${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);
+
+/* ── Tallies ──────────────────────────────────────────────────────────────── */
+
+const tallies = {};
+function count(bucket, value, file) {
+  const v = String(value).trim().replace(/\s+/g, " ");
+  if (!v) return;
+  tallies[bucket] ??= new Map();
+  const entry = tallies[bucket].get(v) ?? { n: 0, files: new Set() };
+  entry.n++;
+  entry.files.add(relative(root, file));
+  tallies[bucket].set(v, entry);
+}
+
+/** Custom property definitions: name → the values it's given, and where. */
+const props = new Map();
+const propUses = new Map();
+/**
+ * Every class-like word in markup, variant prefixes stripped, so a Tailwind v4
+ * `@theme` token (`--color-ink-soft`) can be credited with its utility uses
+ * (`text-ink-soft`, `hover:border-ink-soft/50`) and not only its `var()` uses.
+ */
+const classWords = new Map();
+
+const signals = {};
+function signal(name, file) {
+  signals[name] ??= new Set();
+  signals[name].add(relative(root, file));
+}
+
+/** Tailwind's scale names, so `text-sm` counts as a size and `text-red-500` doesn't. */
+const TW_SIZE = "xs|sm|base|md|lg|xl|[2-9]xl";
+const TW_PREFIX = String.raw`(?<![\w-])(?:[a-z0-9-]+:)*!?`;
+const tw = (body) => new RegExp(TW_PREFIX + body + String.raw`(?![\w-])`, "g");
+
+const RULES = [
+  // [bucket, regex, group index, only in]
+  ["color.literal", /#[0-9a-fA-F]{8}\b|#[0-9a-fA-F]{6}\b|#[0-9a-fA-F]{3,4}\b|\b(?:rgba?|hsla?|oklch|oklab|lab|lch)\([^)]*\)/g, 0, "all"],
+  ["font-size", /font-size\s*:\s*([^;}"'\n]+)/g, 1, "all"],
+  ["font-size", tw(`text-(${TW_SIZE})`), 1, "markup"],
+  ["font-size", tw(String.raw`text-\[(\d[\d.]*(?:px|rem|em))\]`), 1, "markup"],
+  ["font-weight", /font-weight\s*:\s*([^;}"'\n]+)/g, 1, "all"],
+  ["font-weight", tw("font-(thin|extralight|light|normal|medium|semibold|bold|extrabold|black)"), 1, "markup"],
+  ["font-weight", tw(String.raw`font-\[(\d+)\]`), 1, "markup"],
+  ["line-height", /line-height\s*:\s*([^;}"'\n]+)/g, 1, "all"],
+  ["line-height", tw(String.raw`leading-(none|tight|snug|normal|relaxed|loose|\d+|\[[^\]]+\])`), 1, "markup"],
+  ["letter-spacing", /letter-spacing\s*:\s*([^;}"'\n]+)/g, 1, "all"],
+  ["letter-spacing", tw(String.raw`tracking-(tighter|tight|normal|wide|wider|widest|\[[^\]]+\])`), 1, "markup"],
+  ["font-family", /font-family\s*:\s*([^;}\n]+)/g, 1, "all"],
+  ["font-style", /font-style\s*:\s*(italic|oblique)/g, 1, "all"],
+  ["font-style", tw("(italic)"), 1, "markup"],
+  ["radius", /border-radius\s*:\s*([^;}"'\n]+)/g, 1, "all"],
+  ["radius", tw(String.raw`rounded(?:-[trblse]{1,2})?(?:-(none|xs|sm|md|lg|xl|2xl|3xl|full|\[[^\]]+\]))?`), 0, "markup"],
+  ["z-index", /z-index\s*:\s*([^;}"'\n]+)/g, 1, "all"],
+  ["z-index", tw(String.raw`-?z-(\d+|\[[^\]]+\])`), 0, "markup"],
+  ["shadow", /(?<![(\w-])box-shadow\s*:\s*([^;}\n]+)/g, 1, "all"],
+  ["shadow", tw(String.raw`shadow(?:-(xs|sm|md|lg|xl|2xl|inner|none|\[[^\]]+\]))?`), 0, "markup"],
+  ["backdrop", /(?<![(\w-])backdrop-filter\s*:\s*([^;}\n]+)/g, 1, "all"],
+  ["backdrop", tw(String.raw`backdrop-(?:blur|saturate)(?:-[a-z0-9\[\].%]+)?`), 0, "markup"],
+  ["max-width", /(?<!\(\s*)max-width\s*:\s*([^;}"'\n]+)/g, 1, "all"],
+  ["max-width", tw(String.raw`max-w-([a-z0-9]+|\[[^\]]+\])`), 1, "markup"],
+  ["spacing", tw(String.raw`(?:p|px|py|pt|pb|pl|pr|m|mx|my|mt|mb|ml|mr|gap|gap-x|gap-y|space-x|space-y)-(\d+(?:\.5)?|px|\[[^\]]+\])`), 1, "markup"],
+  ["duration", /(?:transition|animation)(?:-duration)?\s*:[^;}\n]*?(\d*\.?\d+m?s)\b/g, 1, "all"],
+  ["duration", tw(String.raw`duration-(\d+|\[[^\]]+\])`), 1, "markup"],
+  ["duration", /\bduration\s*:\s*(\d*\.?\d+)\b/g, 1, "markup"],
+  ["easing", /cubic-bezier\([^)]*\)/g, 0, "all"],
+  ["easing", /\b(?:ease|ease-in|ease-out|ease-in-out|linear)(?=[\s;,"'])/g, 0, "style"],
+  ["easing", /\bease\s*:\s*(\[[^\]]*\]|"[^"]*"|'[^']*')/g, 1, "markup"],
+  ["spring", /stiffness\s*:\s*(\d+)[^}]*?damping\s*:\s*(\d+)(?:[^}]*?mass\s*:\s*([\d.]+))?/g, "spring", "markup"],
+  ["breakpoint", /@media[^{]*?\((?:min|max)-width\s*:\s*([^)]+)\)/g, 1, "style"],
+  ["breakpoint", /(?<![\w-])(sm|md|lg|xl|2xl):(?=[a-z!-])/g, 1, "markup"],
+];
+
+const SIGNALS = [
+  ["theme: prefers-color-scheme", /prefers-color-scheme/],
+  ["theme: data-theme attribute", /data-theme/],
+  ["theme: .dark class / dark: variant", /\.dark\b|(?<![\w-])dark:/],
+  ["theme: color-scheme declared", /color-scheme\s*:/],
+  ["a11y: prefers-reduced-motion", /prefers-reduced-motion|useReducedMotion|motion-reduce:|motion-safe:/],
+  ["a11y: prefers-reduced-transparency", /prefers-reduced-transparency/],
+  ["a11y: prefers-contrast", /prefers-contrast/],
+  ["a11y: :focus-visible", /:focus-visible|focus-visible:/],
+  ["a11y: bare :focus (check it isn't the ring)", /:focus(?![-\w])/],
+  ["a11y: outline removed", /outline\s*:\s*(none|0)\b|outline-none/],
+  ["tailwind v4 @theme block", /@theme\b/],
+  ["css layers", /@layer\b/],
+  ["font: @font-face", /@font-face/],
+  ["font: next/font", /from\s+["']next\/font\//],
+  ["font: Google Fonts link", /fonts\.googleapis\.com/],
+  ["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 [bucket, re, group, only] of RULES) {
+    if (only !== "all" && only !== kind) continue;
+    for (const m of text.matchAll(re)) {
+      if (group === "spring") count(bucket, `stiffness ${m[1]}, damping ${m[2]}${m[3] ? `, mass ${m[3]}` : ""}`, file);
+      else if (m[group] !== undefined) count(bucket, m[group], file);
+    }
+  }
+
+  // A declaration starts after `{`, `;` or whitespace and ends at `;` or `}` — so a BEM
+  // modifier in a selector (`.btn--primary:hover {`) is neither a property nor a value.
+  for (const m of text.matchAll(/(?<=[{;\s])(--[\w-]+)\s*:\s*([^;{}]+)(?=[;}])/g)) {
+    // `@property --x` blocks and Tailwind's `--tw-*` internals are noise.
+    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));
+    props.set(m[1], entry);
+  }
+  if (kind === "markup") {
+    for (const m of text.matchAll(/(?<![\w-])(?:[a-z0-9-]+:)*!?(-?[a-z][a-z0-9-]*(?:-[a-z0-9.]+)+)(?:\/\d+)?(?![\w-])/g)) {
+      classWords.set(m[1], (classWords.get(m[1]) ?? 0) + 1);
+    }
+  }
+  for (const m of text.matchAll(/var\(\s*(--[\w-]+)/g)) {
+    propUses.set(m[1], (propUses.get(m[1]) ?? 0) + 1);
+  }
+
+  for (const [name, re] of SIGNALS) if (re.test(text)) signal(name, file);
+}
+
+/**
+ * Tailwind v4 namespaces: `--<namespace>-<name>` becomes utilities ending in
+ * `-<name>`. A heuristic — it can over-credit a name that's also a plain word —
+ * 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) {
+  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;
+}
+const uses = (prop) => (propUses.get(prop) ?? 0) + utilityUses(prop);
+
+/* ── Stack ────────────────────────────────────────────────────────────────── */
+
+const stack = {};
+const pkgPath = join(root, "package.json");
+if (existsSync(pkgPath)) {
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    const KNOWN = [
+      "next", "react", "vue", "nuxt", "svelte", "@sveltejs/kit", "astro", "solid-js", "@angular/core",
+      "tailwindcss", "sass", "styled-components", "@emotion/react", "@vanilla-extract/css", "@stitches/react",
+      "@pandacss/dev", "@mui/material", "@chakra-ui/react", "@mantine/core", "@radix-ui/themes",
+      "motion", "framer-motion", "gsap", "@react-spring/web", "react-aria-components", "@headlessui/react",
+      "bootstrap", "class-variance-authority", "tailwind-merge",
+    ];
+    for (const name of KNOWN) if (deps[name]) stack[name] = deps[name];
+    if (Object.keys(deps).some((d) => d.startsWith("@radix-ui/react-"))) stack["@radix-ui primitives"] = "yes";
+  } catch {
+    stack["package.json"] = "unreadable";
+  }
+}
+for (const f of ["components.json", "tailwind.config.js", "tailwind.config.ts", "tailwind.config.mjs", "tailwind.config.cjs", "theme.json", "tokens.json"]) {
+  if (existsSync(join(root, f))) stack[f] = "present";
+}
+
+/* ── Token files: where the system is declared ────────────────────────────── */
+
+const defsPerFile = new Map();
+for (const [, entry] of props) for (const f of entry.files) defsPerFile.set(f, (defsPerFile.get(f) ?? 0) + 1);
+const tokenFiles = [...defsPerFile].sort((a, b) => b[1] - a[1]).slice(0, 8);
+
+/* ── Output ───────────────────────────────────────────────────────────────── */
+
+const sorted = (bucket) => [...(tallies[bucket] ?? new Map())].sort((a, b) => b[1].n - a[1].n);
+
+if (json) {
+  const out = {
+    root,
+    filesScanned: files.length,
+    stack,
+    tokenFiles: Object.fromEntries(tokenFiles),
+    customProperties: Object.fromEntries(
+      [...props].map(([k, v]) => [k, { values: v.values, definedIn: [...v.files], varUses: propUses.get(k) ?? 0, utilityUses: utilityUses(k) }]),
+    ),
+    values: Object.fromEntries(
+      Object.keys(tallies).map((b) => [b, sorted(b).map(([v, e]) => ({ value: v, count: e.n, files: e.files.size }))]),
+    ),
+    signals: Object.fromEntries(Object.entries(signals).map(([k, v]) => [k, [...v]])),
+  };
+  console.log(JSON.stringify(out, null, 2));
+  process.exit(0);
+}
+
+const lines = [];
+const say = (s = "") => lines.push(s);
+
+say(`# Design inventory — ${basename(join(process.cwd(), root))}`);
+say();
+say(`${files.length} source files scanned. Counts are occurrences in source text; "files" is how many files use the value.`);
+say();
+
+say("## Stack");
+say();
+if (Object.keys(stack).length === 0) say("No package.json signals found.");
+for (const [k, v] of Object.entries(stack)) say(`- ${k} ${v === "present" || v === "yes" ? "" : v}`.trimEnd());
+say();
+
+say("## Where tokens are declared");
+say();
+if (tokenFiles.length === 0) say("No custom property declarations found — values are likely inline or in a JS theme object.");
+for (const [f, n] of tokenFiles) say(`- \`${f}\` — ${n} custom properties`);
+say();
+
+const TOP = 15;
+/** Long values (a four-layer shadow) are clipped; --json has them whole. */
+const clip = (v, n = 90) => (v.length > n ? `${v.slice(0, n)}…` : v).replace(/\|/g, "\\|");
+const SECTIONS = [
+  ["Colour literals", "color.literal", "A long tail here means colours bypass the tokens."],
+  ["Font sizes", "font-size", "Many sizes with low counts usually means no ladder."],
+  ["Font weights", "font-weight"],
+  ["Line heights", "line-height"],
+  ["Letter spacing", "letter-spacing"],
+  ["Font families", "font-family"],
+  ["Italic", "font-style", "Relevant if the system reserves or bans italic."],
+  ["Max widths (measures)", "max-width"],
+  ["Spacing utilities", "spacing"],
+  ["Radii", "radius"],
+  ["Z-index", "z-index"],
+  ["Shadows", "shadow"],
+  ["Backdrop filters", "backdrop"],
+  ["Durations", "duration", "Bare numbers from JS configs are usually seconds."],
+  ["Easing", "easing"],
+  ["Springs", "spring"],
+  ["Breakpoints", "breakpoint"],
+];
+
+for (const [title, bucket, note] of SECTIONS) {
+  const rows = sorted(bucket);
+  if (rows.length === 0) continue;
+  say(`## ${title}`);
+  say();
+  if (note) say(`_${note}_`), say();
+  say("| Value | Count | Files |");
+  say("|---|---|---|");
+  for (const [v, e] of rows.slice(0, TOP)) say(`| \`${clip(v)}\` | ${e.n} | ${e.files.size} |`);
+  if (rows.length > TOP) say(`| … ${rows.length - TOP} more distinct values | | |`);
+  say();
+}
+
+if (props.size > 0) {
+  say("## Custom properties");
+  say();
+  say("_Most used first. A property defined but never used is a candidate for removal; one used everywhere is a role._");
+  say();
+  say("| Property | Uses (var · utility) | Values seen | Defined in |");
+  say("|---|---|---|---|");
+  const byUse = [...props].sort((a, b) => uses(b[0]) - uses(a[0]));
+  for (const [k, v] of byUse.slice(0, 60)) {
+    const values = v.values.map((x) => `\`${clip(x.replace(/\s+/g, " "), 48)}\``).join(" · ");
+    say(`| \`${k}\` | ${propUses.get(k) ?? 0} · ${utilityUses(k)} | ${values} | ${[...v.files].slice(0, 2).join(", ")} |`);
+  }
+  if (props.size > 60) say(`| … ${props.size - 60} more | | | |`);
+  say();
+}
+
+say("## Signals");
+say();
+if (Object.keys(signals).length === 0) say("None found.");
+for (const [k, v] of Object.entries(signals).sort()) say(`- ${k} — ${v.size} file${v.size === 1 ? "" : "s"}`);
+say();
+
+console.log(lines.join("\n"));

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

@@ -0,0 +1,136 @@
+# The `DESIGN.md` format
+
+One file at the project root. It is the contract between the project and every Keyline command: they read it before touching an interface, and write decisions back to it when a decision changes.
+
+It is written for two readers at once — a person skimming it to learn the system, and a model looking up one row. That settles most format questions: tables for anything looked up, a sentence of reasoning for anything decided, and **stable section headings**, because each command finds its section by its heading.
+
+## Rules
+
+- **The project's names, always.** The `Name here` column holds whatever the codebase already calls the thing — a Tailwind class, a CSS custom property, a theme key, a component prop. The `Role` column holds the canonical role from `roles.md`. Never rename a project's tokens to match the canonical roles; the mapping is the whole point.
+- **Where the project has no name for a role it needs**, propose one in the project's existing naming style and mark it `proposed`. Detect the style from what's there — `--color-text-muted` implies `--color-text-<tier>`; `ink.soft` implies `ink.<adjective>`; a project with evocative names (`dek`, `keyline`, `whisper`) gets evocative proposals. Don't import a naming scheme the project doesn't use.
+- **Values as the code states them.** `14px`, `0.875rem`, `text-sm` — whichever the source uses, with the resolved pixel value in parentheses where it's a scale step or a unit conversion. A value that differs per theme gets a column per theme.
+- **Contrast is written down, not implied.** Every text tier carries its measured ratio against the surface it's checked on, per theme. Setup computes them with `scripts/contrast.mjs`.
+- **Leave out what isn't there.** No dark theme, no dark column. No prose, no `lead` row. An empty row reads as a requirement.
+- **Decisions carry a reason and a date.** Anything that moves a dial off its preset, or knowingly breaks a law, goes under `## Decisions`. A command that meets a decision respects it; a command that would break a law without one asks first and then records the answer here.
+- **Changes a law forced are recorded too.** A change made because of a law that a later session might undo — a white page replacing a grey one, a removed animation — goes under `## Decisions` marked *law*, so it isn't "fixed" back.
+- **The decisions log reads as the current state, not a diary.** Each entry is dated and marked by who decided — *user decision*, *client feedback*, or *law* — newest first. A new decision on a subject replaces the entry it supersedes rather than sitting below it; git history keeps the old one. A session reads the log before changing anything it covers, so a decided value isn't "fixed" back.
+- **The detector reads tables, not prose.** `scripts/check.mjs` takes the preset from the `Preset` row under `## Profile`, durations from every table row under `## Motion` (the duration ladder and the named exemptions), and z-index values from `## Layout` rows whose role starts `z.` or whose `Name here` is a z utility. A value written only in a sentence, or only as `var(--…)`, is invisible to it, so these tables state values. **Every value in those tables is approved**, so record the ladder the code mostly uses, not every value it contains: a duration or z-index used once or twice, or a few ms from a neighbour, is an open issue to snap, not a rung. The detector warns when a `duration.*` role is no longer than the role for a smaller change.
+- **Findings are not fixes.** Setup lists what violates a law under `## Open issues` and leaves the code alone unless asked. The list is how a later session knows what's known.
+
+## Template
+
+Copy this shape. Drop any table or row that doesn't apply; add project roles under the canonical role they refine.
+
+````markdown
+# Design system
+
+> Keyline reads this before touching UI, and writes back to it when a decision changes. Edit it by hand whenever you like — it is the source of truth for intent, the code is the source of truth for values. Set up YYYY-MM-DD.
+
+## Profile
+
+| | |
+|---|---|
+| Product | One line: what it is and who it's for |
+| Reader | What the reader is mostly doing — reading, working, or being persuaded |
+| Preset | `editorial` · `product` · `expressive` · `glass` |
+| Areas | Routes or directories on a different preset, e.g. `app/(marketing)/** → expressive` |
+| Stack | Framework, styling approach, component library |
+| Tokens live in | Paths, e.g. `src/styles/tokens.css`, `tailwind.config.ts` |
+| Themes | `light`, `dark` — and the mechanism: attribute, class, media query |
+| Motion | CSS only, or the library in use |
+
+## Type
+
+**Families** — `family.text`: Inter (self-hosted, `next/font`), `family.mono`: JetBrains Mono.
+
+| Role | Name here | Size | Leading | Tracking | Weight | Tier |
+|---|---|---|---|---|---|---|
+| `type.title` | `text-title` | 20px | 1.25 | −0.02em | 600 | `text.primary` |
+| `type.body` | `text-base` | 15px | 1.6 | 0 | 400 | `text.primary` |
+| ↳ `pull-quote` (project role) | `.pull` | 18px | 1.4 | 0 | 400 italic | `text.primary` — separated by a 3px rule and the italic voice |
+
+**Weights** — `weight.regular` 400, `weight.strong` 600.
+
+## Colour
+
+**Text** — checked against `surface.page` unless noted.
+
+| Role | Name here | Light | Ratio | Dark | Ratio |
+|---|---|---|---|---|---|
+| `text.primary` | `--ink` | `#16161a` | 17.4:1 | `#ececef` | 16.1:1 |
+
+**Surfaces**, **Lines and fills**, **Signal** — same columns, without ratios except for `focus` (3:1 against its worst surface).
+
+**Exceptions** — each chromatic spend beyond the accent, with what it's for and why that reason can't spread.
+
+## Layout
+
+| Role | Name here | Value |
+|---|---|---|
+| `measure.reading` | `max-w-prose` | 65ch (≈ 620px) |
+
+**Radius ladder**
+
+| Role | Name here | Value |
+|---|---|---|
+| `radius.control` | `rounded-md` | 6px |
+| `radius.card` | `rounded-xl` | 12px |
+
+**z-index ladder** — low to high, rows `z.below`, `z.raised`, `z.popover`, `z.dismiss`, `z.nav`, `z.overlay`, `z.toast`, `z.skip-link` as used.
+
+| Role | Name here | Value |
+|---|---|---|
+| `z.popover` | `z-popover` | 20 |
+| `z.overlay` | `z-overlay` | 60 |
+| `z.toast` | `z-toast` | 70 |
+
+**Breakpoints**
+
+| Role | Name here | Value | What changes |
+|---|---|---|---|
+| `bp.rail` | `lg` | 1024px | The table of contents moves into the margin rail |
+
+Plus any forks (places where touch and pointer get different components).
+
+## Surfaces
+
+| Level | Surface | Edge | Shadow | Layer |
+|---|---|---|---|---|
+| `elevation.floating` | `bg-popover` | `border-subtle` | `shadow-md` | `z-popover` |
+
+Plus `material.translucent` tiers, if any, and their fallbacks.
+
+## Motion
+
+| Role | Name here | Value | Used for |
+|---|---|---|---|
+| `duration.state` | `--dur-fast` | 150ms | hover colour, icon swaps |
+| `ease.standard` | `--ease-out` | `cubic-bezier(0.2, 0, 0, 1)` | everything but colour |
+
+**Named exemptions** — motion off the ladder on purpose: set pieces, exits, spring opacity, crossfade pairs.
+
+| Exemption | Values | Why |
+|---|---|---|
+| Greeting | 900ms | Set piece: plays once a session, so it is not state (motion law 4) |
+| Menu exit | 120ms | Closing runs faster than opening |
+
+Plus springs by character, and the reduced-motion policy in one sentence.
+
+## Patterns
+
+**Nouns** — one per kind of thing: task (never "issue"), note, project, member. **Row second line** — `{type} from {origin}`. **Destructive** — delete, remove, sign out: last in menu, no icon; projects and accounts need a typed word. **Shortcuts** — ⌘K palette, J/K, F filter, Escape one layer. **Remembered views** — tasks and meetings per page; folders pinned to folders.
+
+## 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 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
+
+- `text.tertiary` (`--ink-faint`) is 3.1:1 on `surface.subtle` in light — fails 4.5:1. Used in 14 files.
+````
+
+## When the file already exists
+
+Read it first; never regenerate over it. Setup's job on a second run is to **reconcile**: re-scan, show what drifted (a token added, a value changed, an issue fixed), and propose edits to the file — keeping every `Decisions` entry and every name the user chose, even where the scan would have proposed something else.

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

@@ -0,0 +1,53 @@
+# Reading a codebase's design system
+
+Where each kind of project keeps its decisions, and what to read once `scan.mjs` has pointed you at the right files. The scan counts; this is how to interpret what it counted.
+
+## Where the tokens live
+
+| Stack signal | Look in | Notes |
+|---|---|---|
+| Tailwind v4 (`@theme` in the scan's signals) | The CSS file with the `@theme` block — usually `app/globals.css`, `src/index.css`, `src/styles/*.css` | Tokens are custom properties in namespaces (`--color-*`, `--text-*`, `--radius-*`, `--ease-*`) and are used as utilities, so a token with no `var()` uses can still be everywhere. The scan's "utility" count is the one to read |
+| Tailwind v3 (`tailwind.config.*` present) | `theme.extend` in the config, plus any `@layer base` custom properties | Values in `theme` (not `extend`) *replace* Tailwind's defaults — note which scales were replaced, because that's a deliberate ladder |
+| shadcn/ui (`components.json`) | The CSS variables block it generated (`--background`, `--foreground`, `--muted-foreground`, `--border`, `--ring`, …) and `components/ui/*` | The names are already semantic, and many map one-to-one onto canonical roles. `--muted-foreground` is almost always `text.secondary` or `text.tertiary` — check its contrast before deciding which |
+| CSS custom properties only | Whichever file the scan lists first under "Where tokens are declared" | Look for a `:root` block and a theme block (`[data-theme="dark"]`, `.dark`, or a media query) |
+| Sass (`sass` dependency) | `_variables.scss`, `_tokens.scss`, `abstracts/`, `settings/` | Sass variables compile away, so the scan's custom-property table will be thin. Read the partials directly |
+| CSS-in-JS (`styled-components`, `@emotion/react`, `@stitches/react`, `@vanilla-extract/css`, `@pandacss/dev`) | The theme object: `theme.ts`, `stitches.config.ts`, `*.css.ts`, `panda.config.ts` | Values live in JS, so the scan finds them as literals. Tokens are the object's keys |
+| A component library (`@mui/material`, `@chakra-ui/react`, `@mantine/core`, `@radix-ui/themes`) | The `createTheme` / `extendTheme` call, or the `Theme` provider's props | The library supplies a full system; the project's decisions are the *overrides*. Map the library's roles, then record the overrides as the project's dials |
+| Design tokens JSON (`tokens.json`, Style Dictionary, Tokens Studio) | The JSON source, not the generated output | The generated CSS is downstream. Point `DESIGN.md` at the source file |
+
+## Fonts
+
+- **`next/font`** — the import in the root layout names the family, the weights loaded and the CSS variable it's exposed as. Weights loaded is a strong hint at weights *intended*.
+- **`@font-face`** — the `font-weight` ranges declared are what exists; anything else is faux-bolded by the browser.
+- **Google Fonts `<link>`** — the `wght@` list in the URL.
+- **System stack only** — the project has chosen not to ship a font. Record it as a decision, not an absence.
+
+A family loaded at five weights and used at two is worth a line in open issues: the other three are download cost with no job.
+
+## Themes
+
+| Signal | Mechanism |
+|---|---|
+| `data-theme` attribute | An explicit toggle that can override the OS — the more robust setup |
+| `.dark` class / `dark:` variant | The same, via a class. Check whether Tailwind's dark variant is set to the class or to the media query |
+| `prefers-color-scheme` only | Follows the OS with no override. A toggle can't be added without changing the mechanism |
+| `color-scheme` missing | Native scrollbars and form controls won't re-tint. An open issue if there's a dark theme |
+
+Look for the pre-paint script as well: a theme set by React after hydration flashes the wrong theme on every load.
+
+## Motion
+
+- **CSS** — `transition` and `animation` declarations, `@keyframes`, and any duration or easing custom properties.
+- **Motion / Framer Motion** — `transition={{ … }}` props, `variants` objects, shared presets (often a `motion.ts` or `transitions.ts`). Durations there are **seconds**, not milliseconds; the scan reports them as bare numbers.
+- **GSAP, React Spring** — timelines and `config` objects. React Spring's `tension`/`friction` map roughly to stiffness/damping.
+- **Reduced motion** — `prefers-reduced-motion` in CSS, `useReducedMotion()`, `MotionConfig reducedMotion`, Tailwind's `motion-safe:`/`motion-reduce:`. Note *what* happens under it — removed entirely, or replaced with a fade? The motion guide treats those very differently.
+
+## Reading a component
+
+The scan can't tell you how values combine. Three components read end to end tell you most of it:
+
+1. **A page** — the reading measure, the heading sizes, the section rhythm, what the `h1` looks like.
+2. **A card or list row** — the radius, the border, the surface, the hover state, the text tiers inside it.
+3. **A menu, popover or dialog** — the elevation, the z-index, the open and close motion, focus handling.
+
+Between them you will see the roles in use, which is what the mapping needs. A value that looks like a token but is never used together with its siblings is often a leftover.

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

@@ -0,0 +1,97 @@
+# Design System Setup
+
+Keyline's domain guides know how a type ladder, a colour system or a motion system should behave. They don't know *your* project: what it calls its greys, which font it ships, whether it has a dark theme, whether its reader is skimming a dashboard or reading an essay. This guide finds out once and writes it down in `DESIGN.md` at the project root, so every later session and every other command starts from the same facts.
+
+The job is **translation, not replacement.** A project that calls its quietest text `whisper` keeps calling it `whisper`; setup records that `whisper` is `text.tertiary`, the lowest tier that must still be readable, so the colour guide can check it clears 4.5:1 and the type guide can put captions on it.
+
+The contract lives in `system/`: `roles.md` (the canonical roles, and which may share a token), `presets.md` (the four starting characters and how to choose), `design-md.md` (the file's format, a template, and how to reconcile).
+
+## 0. If `DESIGN.md` already exists
+
+Don't regenerate it. Rescan and **reconcile**: report what drifted (new tokens, changed values, issues fixed or new), propose edits, and keep every name and `Decisions` entry the user chose. A second run is an audit, not a rewrite; the rest of this file is the first run.
+
+## 1. Scan
+
+From the project root:
+
+```sh
+node <keyline>/scripts/scan.mjs . --ignore src/content
+```
+
+`--ignore` takes a path prefix and repeats; use it for directories of prose, documentation or code samples, or their example values count as the project's. The output is a markdown inventory — the stack, where custom properties are declared, every value by frequency, and signals for theming, reduced motion, focus handling and font loading. `--json` gives everything.
+
+The scan reads source text, so it can't see a value computed at runtime, a class assembled from strings, or a theme passed through a provider. Open the top token file and the root layout, and read a page, a card and a menu end to end. `system/detection.md` lists where each stack keeps its tokens.
+
+**Frequency is the signal.** A size used in 40 files is a role; a size used once is a stray or a genuine one-off, and deserves a look rather than an assumption.
+
+## 2. Map what's there onto the roles
+
+For each canonical role in `roles.md`: which of the project's names does that job, and with what value? Map by usage, not by name — a `gray-500` that every caption uses *is* `text.tertiary`.
+
+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.
+- **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:
+
+```sh
+node <keyline>/scripts/contrast.mjs --ladder "#ffffff" "#16161a" "#4b4b52" "#6b6b73"
+```
+
+`--ladder` takes a surface then the text tiers, top first, and checks each clears 4.5:1 **and** that they strictly descend — every tier passing while two are indistinguishable means the hierarchy is gone. Run it per theme against the worst surface each tier lands on; use `--min 3` for icons, borders and the focus ring.
+
+## 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 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`.
+
+Code that contradicts the preset — a `product` codebase with five weights — doesn't change the preset. It's a decision to record with its reason, or an issue to list.
+
+## 4. Ask only what the code can't answer
+
+At most four questions, each with your recommendation first:
+
+1. **The preset**, if the evidence doesn't settle it or you're proposing something the codebase doesn't yet look like.
+2. **Themes**, if only one exists: is a second planned? It changes how tokens should be structured now.
+3. **Couplings**, where splitting one changes what users see — "captions and borders share `gray-500`; split them?"
+4. **Names**, only when proposing several at once and the project's style is ambiguous.
+
+Don't ask what you can find out, and don't ask for approval of the whole mapping — write it and let the user correct the file.
+
+**When you can't stop to ask** — a headless or scheduled run, or a user who said to go ahead — take your recommendation for each question, write the file, and list each one under `## Decisions` marked *(?) assumed*, with the alternative, so the user can overturn it in one edit. A later command treats an *(?) assumed* entry like any decision until the user changes it.
+
+## 5. Write `DESIGN.md`
+
+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). 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
+
+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`.
+
+## Checklist
+
+- [ ] An existing `DESIGN.md` was reconciled, not overwritten; every user-chosen name and decision survived.
+- [ ] The scan ignored prose and example directories, and its findings were checked against the code.
+- [ ] Every role is mapped by **usage**, not by what the token is called.
+- [ ] The project's names are unchanged; new names are `proposed` and in the project's style.
+- [ ] Project roles sit under a canonical parent, each with the signal that separates it.
+- [ ] Tokens doing two jobs are listed as issues, not silently split.
+- [ ] Boxes per main screen counted; every card holding more than one object, every nested card and every tile grid listed as an issue.
+- [ ] Every text tier has a measured ratio per theme against its worst surface, and the ladder strictly descends.
+- [ ] The preset is justified by evidence about the reader; mixed projects list areas by path.
+- [ ] `glass` was offered only when the user wants modimihir.com's exact system.
+- [ ] At most four questions, each about something the code couldn't answer.
+- [ ] Open issues carry evidence; nothing was fixed without being asked.
+- [ ] Generated tokens use the project's existing mechanism and naming.