trykeyline 0.0.0-stage → 0.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "name": "keyline",
+  "owner": {
+    "name": "Mihir Modi",
+    "url": "https://github.com/Mihirmodi27"
+  },
+  "metadata": {
+    "description": "Keyline: interface design laws for coding agents, applied in your project's own tokens.",
+    "version": "0.1.0"
+  },
+  "plugins": [
+    {
+      "name": "keyline",
+      "source": "./plugins/keyline",
+      "description": "One skill with eleven commands — init, sync, critique, audit, type, color, layout, depth, motion, patterns, polish — that applies one set of interface laws through a DESIGN.md written in your project's own names."
+    }
+  ]
+}

package/LICENSE

@@ -0,0 +1,37 @@
+MIT License
+
+Copyright (c) 2026 Mihir Modi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+WHAT THIS LICENCE DOES AND DOESN'T COVER
+
+The licence above covers the template: the components, hooks, styles, build
+configuration and scripts.
+
+It does not cover content. Text, photographs, designs, writing, résumés, logos
+and brand marks belong to whoever made them, are not licensed here, and are not
+yours to republish by virtue of having a copy of this repository. If you cloned
+this from someone's personal site, replace their content with your own.
+
+Third-party marks in `src/lib/stackIcons.tsx` are generated from simple-icons
+(CC0-1.0). The brands they represent remain the property of their owners and
+their trademark guidelines still apply.

package/README.md

@@ -1,3 +1,118 @@
-# Temporary Holding Version
+# Keyline
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Interface design laws for coding agents.
+
+Keyline reads your codebase once and writes a `DESIGN.md` that maps your own token names onto its roles and picks a preset for your reader. From then on your agent critiques, audits and fixes type, colour, layout, depth, motion and product patterns through that file: the same laws on every project, your values on yours.
+
+```sh
+npx trykeyline install
+```
+
+The npm package is `trykeyline`, because npm holds `keyline` too close to an older package's name. Everything else, the skill and the commands in your agent, is `keyline`.
+
+Then, in your agent:
+
+```
+/keyline init
+```
+
+## Commands
+
+| Command | Does |
+|---|---|
+| `/keyline init` | Scans the codebase, maps its tokens onto roles, picks a preset, writes `DESIGN.md` with the open issues it found |
+| `/keyline sync` | Reconciles `DESIGN.md` with code that has moved since |
+| `/keyline critique` | A designer's read of one screen: what the reader feels first, what's working, the few changes that matter |
+| `/keyline audit` | Every law checked with evidence, per domain, scored 0–4 |
+| `/keyline type` | Type scale, weights, leading, tracking, emphasis, numerals, font loading |
+| `/keyline color` | Tokens by intent, text tiers by measured contrast, status colours, themes |
+| `/keyline layout` | Measure, spacing that groups, radii, line weights, z-index, breakpoints, empty states |
+| `/keyline depth` | Elevation, shadows, edges, scrims, translucent surfaces and their fallbacks |
+| `/keyline motion` | Durations, curves, springs, open and close, reduced motion, scroll |
+| `/keyline patterns` | Labels, buttons, destructive actions, forms, agent UIs, dashboards |
+| `/keyline polish` | All six domains in order, one reviewable pass each |
+
+You don't have to name a command: ask for "tighter spacing" or "a review of the settings page" and the agent picks one.
+
+`critique`, `audit`, `init` and `sync` change no code. The refining commands change only what their domain owns, in your token names, and write decisions back to `DESIGN.md` so the next session starts from them.
+
+## The detector
+
+Twenty-four of the laws can be checked from source alone, with no model and no API key:
+
+```sh
+npx trykeyline check            # human report; exits 1 on errors
+npx trykeyline check --json     # every finding, for CI or an agent
+npx trykeyline check --strict   # warnings fail the run too
+```
+
+It reads CSS, Tailwind classes, inline styles, `<style>` blocks and CSS-in-JS, in React, Vue, Svelte, Astro and plain HTML, and it reads `DESIGN.md` so the verdicts follow your preset and your motion and z-index ladders. A few of the things it catches: `transition: all`; animation with no reduced-motion branch; an outline removed with nothing in its place; `100vh`; `z-index: 9999`; colours typed inline instead of tokens; translucency with no `@supports` fallback; pinch-zoom disabled; uppercase labels and Title Case buttons where the preset says sentence case. `npx trykeyline check --rules` lists all of them, each with the law it comes from.
+
+`/keyline audit` runs it first and spends its own reading on what a detector can't see — hierarchy, grouping, whether a box should exist at all.
+
+Silence a line with a `keyline-ignore` comment on it or the line above, naming the rule if you like (`/* keyline-ignore type/uppercase */`); a whole file with `keyline-ignore-file`. Leave out paths with `--ignore src/content`.
+
+In CI:
+
+```yaml
+- run: npx trykeyline check
+```
+
+## Presets
+
+The laws hold everywhere. A preset sets the dials — how far the type scale climbs, how much colour is spent, how long motion runs — for what your reader is doing:
+
+| Preset | For a reader who is |
+|---|---|
+| `editorial` | Reading: articles, docs, portfolios, changelogs |
+| `product` | Working: dashboards, tools, anything used daily |
+| `expressive` | Being persuaded: landing pages, launches, campaigns |
+| `glass` | Getting [modimihir.com](https://modimihir.com)'s exact system, with drop-in tokens and components |
+
+Mixed projects are normal: `product`, with the marketing routes on `expressive`. Any dial can be moved, and the move is recorded in `DESIGN.md` with its reason.
+
+## Installing
+
+`npx trykeyline install` asks which agent you use and copies the skill into that agent's folder. Flags answer up front:
+
+```sh
+npx trykeyline install --tool codex,cursor     # several agents
+npx trykeyline install --tool claude-code --user   # every project on this machine
+npx trykeyline update                          # refresh every copy already installed
+```
+
+| Agent | `--tool` | This project | Every project (`--user`) |
+|---|---|---|---|
+| Claude Code | `claude-code` | `.claude/skills` | `~/.claude/skills` |
+| Codex | `codex` | `.agents/skills` | `~/.codex/skills` |
+| Cursor | `cursor` | `.agents/skills` | `~/.cursor/skills` |
+| Gemini CLI | `gemini-cli` | `.agents/skills` | `~/.gemini/skills` |
+| GitHub Copilot | `github-copilot` | `.agents/skills` | `~/.copilot/skills` |
+| OpenCode | `opencode` | `.agents/skills` | `~/.config/opencode/skills` |
+| Windsurf | `windsurf` | `.windsurf/skills` | `~/.codeium/windsurf/skills` |
+| Any agent that reads `.agents/skills` | `agents` | `.agents/skills` | `~/.agents/skills` |
+
+**Claude Code plugin:**
+
+```
+/plugin marketplace add Mihirmodi27/keyline
+/plugin install keyline@keyline
+```
+
+Claude Code names a plugin's skills after the plugin, so installed this way the command is `/keyline:keyline init`, `/keyline:keyline critique` and so on. Installed with `npx trykeyline install`, it's `/keyline`.
+
+**With the [`skills` CLI](https://github.com/vercel-labs/skills):** `npx skills add Mihirmodi27/keyline --agent claude-code`.
+
+Or run the installer straight from GitHub: `npx github:Mihirmodi27/keyline install`.
+
+### Coming from interface-skills
+
+Keyline replaces both interface-skills packages: the adaptable set became the commands, and the Glass package became the `glass` preset. `npx trykeyline install` finds the old skills and offers to remove them, since their descriptions would compete with Keyline's for the same requests. A `DESIGN.md` written by the old setup skill works as it is.
+
+## Requirements
+
+Node 18 or later, for the installer and for the three scripts the skill runs: the detector, a token inventory and a contrast checker. None of them needs a dependency, a model or an API key.
+
+## Licence
+
+MIT © Mihir Modi

package/bin/keyline.mjs

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+/**
+ * Keyline's command line.
+ *
+ *   npx trykeyline install                      asks which coding agent
+ *   npx trykeyline install --tool codex,cursor  answers up front
+ *   npx trykeyline install --user               for every project on this machine
+ *   npx trykeyline update                       refresh every copy already installed
+ *
+ * Keyline is one skill folder. Each coding agent reads skills from its own
+ * folder: Claude Code and Windsurf have their own; Codex, Cursor, Gemini CLI,
+ * GitHub Copilot, OpenCode and most others share `.agents/skills` in a project.
+ * The folder is always copied, never symlinked, so an agent reads real files,
+ * and agents that share a folder share one copy.
+ *
+ * The skill ships inside this package, so installing copies rather than
+ * downloads: it works offline and installs exactly the version npx resolved.
+ */
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import { join, relative, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+
+const SOURCE = fileURLToPath(new URL("../plugins/keyline/skills/keyline/", import.meta.url));
+const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+const NAME = "keyline";
+
+/**
+ * Where each agent reads skills from — in a project, and for the whole machine.
+ * The ids and folders match the `skills` CLI (vercel-labs/skills), so a skill
+ * installed either way lands in the same place.
+ */
+const home = homedir();
+const configHome = process.env.XDG_CONFIG_HOME?.trim() || join(home, ".config");
+const TOOLS = {
+  "claude-code": {
+    title: "Claude Code",
+    project: ".claude/skills",
+    global: join(process.env.CLAUDE_CONFIG_DIR?.trim() || join(home, ".claude"), "skills"),
+  },
+  codex: {
+    title: "Codex",
+    project: ".agents/skills",
+    global: join(process.env.CODEX_HOME?.trim() || join(home, ".codex"), "skills"),
+  },
+  cursor: { title: "Cursor", project: ".agents/skills", global: join(home, ".cursor", "skills") },
+  "gemini-cli": { title: "Gemini CLI", project: ".agents/skills", global: join(home, ".gemini", "skills") },
+  "github-copilot": { title: "GitHub Copilot", project: ".agents/skills", global: join(home, ".copilot", "skills") },
+  opencode: { title: "OpenCode", project: ".agents/skills", global: join(configHome, "opencode", "skills") },
+  windsurf: { title: "Windsurf", project: ".windsurf/skills", global: join(home, ".codeium", "windsurf", "skills") },
+  agents: {
+    title: "Any other agent that reads .agents/skills",
+    project: ".agents/skills",
+    global: join(home, ".agents", "skills"),
+  },
+};
+const ALIASES = { claude: "claude-code", gemini: "gemini-cli", copilot: "github-copilot", other: "agents" };
+const TOOL_IDS = Object.keys(TOOLS);
+
+/**
+ * Keyline replaces the interface-skills packages. Left installed beside it,
+ * their descriptions compete with Keyline's for the same requests, so install
+ * offers to remove them.
+ */
+const SUPERSEDED = [
+  "design-system-setup",
+  "typographic-system",
+  "color-and-theming",
+  "layout-and-hierarchy",
+  "surfaces-and-depth",
+  "interface-motion",
+  "product-patterns",
+  "glass-typography",
+  "glass-color",
+  "glass-layout",
+  "glass-and-depth",
+  "glass-motion",
+];
+
+const USAGE = `Keyline ${version} — interface design laws for coding agents.
+
+  npx trykeyline install [options]   install the skill
+  npx trykeyline update  [options]   refresh every copy already installed
+  npx trykeyline check  [paths…]     the laws that can be checked without a model
+                                     (--json, --strict; see npx trykeyline check --help)
+  npx trykeyline tools               list the agents it installs for
+
+Options:
+  -t, --tool <tool[,tool…]>   which agent — asked for when not given, Claude Code
+                              when there's no terminal to ask on. One of:
+                              ${TOOL_IDS.join(", ")}
+  --user                      for every project on this machine, not just this one
+  --dir <path>                into <path>, whatever the agent
+  -f, --force                 overwrite a copy that's already there
+  -h, --help                  this
+  -v, --version               the version
+
+Then, in your agent: /keyline init`;
+
+function die(message) {
+  console.error(`keyline: ${message}`);
+  process.exit(1);
+}
+
+function toolId(name) {
+  const id = ALIASES[name] ?? name;
+  if (!TOOLS[id]) die(`no agent called '${name}' — use one of: ${TOOL_IDS.join(", ")}`);
+  return id;
+}
+
+/* ── Arguments ──────────────────────────────────────────────────────────── */
+
+const argv = process.argv.slice(2);
+
+// `check` is the detector, which lives in the skill so an agent can run it without this CLI.
+if (argv[0] === "check") {
+  const { run } = await import(new URL("../plugins/keyline/skills/keyline/scripts/check.mjs", import.meta.url));
+  process.exit(run(argv.slice(1)));
+}
+const command = argv[0] && !argv[0].startsWith("-") ? argv.shift() : null;
+let dir = null;
+let user = false;
+let force = false;
+const tools = [];
+
+for (let i = 0; i < argv.length; i++) {
+  const arg = argv[i];
+  const value = () => (arg.includes("=") ? arg.slice(arg.indexOf("=") + 1) : argv[++i]);
+  if (arg === "--user") user = true;
+  else if (arg === "--dir" || arg.startsWith("--dir=")) {
+    const path = value();
+    if (!path) die("--dir needs a path");
+    dir = resolve(path);
+  } else if (["-t", "--tool", "--agent"].includes(arg) || arg.startsWith("--tool=") || arg.startsWith("--agent=")) {
+    const v = value();
+    if (!v) die("--tool needs an agent name");
+    for (const name of v.split(",").map((s) => s.trim()).filter(Boolean)) tools.push(toolId(name));
+  } else if (arg === "-f" || arg === "--force") force = true;
+  else if (arg === "-h" || arg === "--help") {
+    console.log(USAGE);
+    process.exit(0);
+  } else if (arg === "-v" || arg === "--version") {
+    console.log(version);
+    process.exit(0);
+  } else die(`unknown option: ${arg} (try --help)`);
+}
+
+if (!command) {
+  console.log(USAGE);
+  process.exit(0);
+}
+if (command === "tools") {
+  for (const id of TOOL_IDS) console.log(`${id.padEnd(16)} ${TOOLS[id].title}`);
+  process.exit(0);
+}
+if (command !== "install" && command !== "update") die(`no command called '${command}' (try --help)`);
+
+/* ── Helpers ────────────────────────────────────────────────────────────── */
+
+const interactive = process.stdin.isTTY && process.stdout.isTTY;
+
+async function prompt(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return (await rl.question(question)).trim();
+  } catch {
+    // Ctrl+C or Ctrl+D at a question: stop quietly, having written nothing yet for this question.
+    console.log("\nCancelled.");
+    process.exit(130);
+  } finally {
+    rl.close();
+  }
+}
+
+async function askTools() {
+  if (!interactive) {
+    console.log("No terminal to ask on, so installing for Claude Code. Pass --tool to choose (try `keyline tools`).\n");
+    return ["claude-code"];
+  }
+  console.log("Which agent?\n");
+  TOOL_IDS.forEach((id, i) => console.log(`  ${i + 1}) ${TOOLS[id].title}`));
+  console.log();
+  for (;;) {
+    const answer = (await prompt("Choose one or more, like 1 or 1,2 [1]: ")) || "1";
+    const picks = answer.split(/[\s,]+/).filter(Boolean).map(Number);
+    if (picks.length && picks.every((n) => Number.isInteger(n) && n >= 1 && n <= TOOL_IDS.length)) {
+      console.log();
+      return [...new Set(picks.map((n) => TOOL_IDS[n - 1]))];
+    }
+    console.log(`  Type numbers from 1 to ${TOOL_IDS.length}, separated by commas.`);
+  }
+}
+
+const shown = (path) => (path.startsWith(process.cwd()) ? `./${relative(process.cwd(), path)}` : path.replace(home, "~"));
+
+/** The folders to install into, each with the agents that read it. */
+function destinations(ids, global) {
+  const byPath = new Map();
+  for (const id of ids) {
+    const path = global ? TOOLS[id].global : resolve(TOOLS[id].project);
+    byPath.set(path, [...(byPath.get(path) ?? []), TOOLS[id].title]);
+  }
+  // More than two readers only happens on an update sweep of the shared
+  // .agents/skills folder, where naming all six says less than naming the folder.
+  return [...byPath].map(([path, readers]) => ({
+    path,
+    label: readers.length > 2 ? `Every agent that reads ${shown(path)}` : readers.join(", "),
+  }));
+}
+
+const installedAt = (path) => existsSync(join(path, NAME, "SKILL.md"));
+const supersededAt = (path) => SUPERSEDED.filter((s) => existsSync(join(path, s)));
+
+function copyTo(path) {
+  const target = join(path, NAME);
+  mkdirSync(path, { recursive: true });
+  rmSync(target, { recursive: true, force: true });
+  cpSync(SOURCE, target, { recursive: true });
+}
+
+async function retire(path) {
+  const old = supersededAt(path);
+  if (old.length === 0) return;
+  console.log(`  Found interface-skills here, which Keyline replaces: ${old.join(", ")}.`);
+  const links = old.filter((s) => lstatSync(join(path, s)).isSymbolicLink());
+  if (links.length) console.log(`  (${links.join(", ")} ${links.length === 1 ? "is a link" : "are links"}; removing ${links.length === 1 ? "it" : "them"} leaves the target alone.)`);
+  if (!interactive) {
+    console.log("  Left in place — remove them by hand, or rerun in a terminal, so they don't compete with Keyline.");
+    return;
+  }
+  const answer = ((await prompt("  Remove them? [Y/n]: ")) || "y").toLowerCase();
+  if (!answer.startsWith("y")) return;
+  for (const s of old) rmSync(join(path, s), { recursive: true, force: true });
+  console.log(`  ✓ removed ${old.length}`);
+}
+
+if (!existsSync(join(SOURCE, "SKILL.md"))) die("the package is missing its SKILL.md — reinstall it");
+
+/* ── update ─────────────────────────────────────────────────────────────── */
+
+if (command === "update") {
+  // Every place Keyline is already installed — in this project and on this machine.
+  const scopes = dir ? [{ path: dir, label: shown(dir) }] : [...destinations(TOOL_IDS, false), ...destinations(TOOL_IDS, true)];
+  const found = scopes.filter((d) => installedAt(d.path));
+  if (found.length === 0) {
+    console.log("Keyline isn't installed here or for this user — run `npx trykeyline install`.");
+    process.exit(0);
+  }
+  for (const d of found) {
+    copyTo(d.path);
+    console.log(`✓ ${d.label} → ${shown(join(d.path, NAME))}`);
+  }
+  console.log(`\nKeyline ${version}, ${found.length} ${found.length === 1 ? "copy" : "copies"} updated.`);
+  process.exit(0);
+}
+
+/* ── install ────────────────────────────────────────────────────────────── */
+
+const dests = dir ? [{ path: dir, label: shown(dir) }] : destinations(tools.length ? tools : await askTools(), user);
+let installed = 0;
+
+for (const d of dests) {
+  console.log(`${d.label} → ${shown(join(d.path, NAME))}`);
+  if (installedAt(d.path) && !force) {
+    console.log("  · already installed — `npx trykeyline update` refreshes it, --force overwrites it");
+  } else {
+    copyTo(d.path);
+    console.log(`  ✓ keyline ${version}`);
+    installed++;
+  }
+  await retire(d.path);
+  console.log();
+}
+
+if (installed > 0) {
+  console.log("Next, in your agent:");
+  console.log("  /keyline init       scan this project and write DESIGN.md");
+  console.log("  /keyline critique   then a designer's read of any screen");
+}

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "trykeyline",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Interface design laws for coding agents: one skill that reads your codebase, writes a DESIGN.md in your own token names, then critiques, audits and fixes type, colour, layout, depth, motion and product patterns through it.",
+  "keywords": [
+    "design",
+    "design-system",
+    "ui",
+    "typography",
+    "accessibility",
+    "agent-skills",
+    "claude-code",
+    "codex",
+    "cursor",
+    "skills"
+  ],
+  "homepage": "https://github.com/Mihirmodi27/keyline#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mihirmodi27/keyline.git"
+  },
+  "license": "MIT",
+  "author": "Mihir Modi (https://modimihir.com)",
+  "type": "module",
+  "bin": {
+    "keyline": "bin/keyline.mjs",
+    "trykeyline": "bin/keyline.mjs"
+  },
+  "files": [
+    "bin",
+    "plugins",
+    ".claude-plugin"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test \"test/**/*.test.mjs\""
+  }
+}

package/plugins/keyline/.claude-plugin/plugin.json

@@ -0,0 +1,14 @@
+{
+  "name": "keyline",
+  "displayName": "Keyline",
+  "version": "0.1.0",
+  "description": "Interface design laws for coding agents. /keyline init reads your codebase and writes a DESIGN.md in your own token names; critique, audit, type, color, layout, depth, motion, patterns and polish work through it, with dials set by a preset (editorial, product, expressive or glass).",
+  "author": {
+    "name": "Mihir Modi",
+    "url": "https://modimihir.com"
+  },
+  "homepage": "https://github.com/Mihirmodi27/keyline#readme",
+  "repository": "https://github.com/Mihirmodi27/keyline",
+  "license": "MIT",
+  "keywords": ["design-system", "design-tokens", "typography", "motion", "colour", "layout", "accessibility"]
+}

package/plugins/keyline/skills/keyline/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: keyline
+description: "Design, review and fix interfaces with one set of laws applied in the project's own tokens, names and character. Commands: init (scan the codebase and write DESIGN.md), sync, critique, audit, type, color, layout, depth, motion, patterns, polish. Use when the user wants to set up or document a design system, review or audit a UI, or improve typography, type scale, font weights, colour, contrast, theming, dark mode, spacing, padding, alignment, layout, hierarchy, radii, z-index, cards, shadows, elevation, glass or translucent surfaces, animation, transitions, hover and focus states, reduced motion, UI copy, labels, buttons, forms, dialogs, empty states, dashboards, tables, agent and AI chat interfaces — on websites, landing pages, apps and components. Also for screens that feel generic, boxy, cluttered, flat, noisy, inconsistent or template-made, and for building new UI that should look considered from the first commit. Not for backend-only work."
+---
+
+# Keyline
+
+Keyline gives an agent the judgement of a careful interface designer, as laws it can apply and check. **The laws are the same for every project; the values never are.** A setup pass reads the codebase once and writes `DESIGN.md`, which maps the project's own token names onto Keyline's roles and picks a preset for its reader. Every other command works through that file, in the project's names.
+
+Paths in these files are relative to this skill's folder. In shell commands it is written `<keyline>` — substitute the folder this file is in.
+
+## Running it
+
+`/keyline <command> [target]` — the target is a route, file, directory or component; without one, the command takes the whole project, or the screen the conversation is about.
+
+| Command | Does | Changes code |
+|---|---|---|
+| `init` | Scans the codebase, maps its tokens onto roles, picks a preset, writes `DESIGN.md` with the open issues it found | No |
+| `sync` | Reconciles `DESIGN.md` with code that has moved since: drift, new tokens, issues fixed or new | No |
+| `critique` | A designer's read of one screen: what the reader feels first, what's working, the few changes that matter most | No |
+| `audit` | Every law checked with evidence, per domain, scored; findings go to `DESIGN.md` | No |
+| `type` | Type scale, weights, leading, tracking, emphasis, numerals, fonts | Yes |
+| `color` | Tokens by intent, text tiers by measured contrast, status colours, themes | Yes |
+| `layout` | Measure, spacing that groups, radii, line weights, z-index, breakpoints, empty states | Yes |
+| `depth` | Elevation levels, shadows, edges, scrims, translucent surfaces and their fallbacks | Yes |
+| `motion` | Durations, curves, springs, open and close, reduced motion, scroll, hover intent | Yes |
+| `patterns` | Behaviour and words: labels, buttons, destructive actions, forms, agent UIs, dashboards | Yes |
+| `polish` | All six domains in order, one reviewable pass each | Yes |
+
+**No command named?** Pick the one the request is about, say which, and go: "set up", "document", "extract" → `init`; "review", "what's wrong", "feedback" → `critique`; "check everything", "lint", "score" → `audit`; "font", "headings", "typography" → `type`; "colour", "contrast", "dark mode" → `color`; "spacing", "padding", "alignment", "cramped" → `layout`; "shadow", "card", "glass", "modal" → `depth`; "animate", "transition", "feels janky" → `motion`; "copy", "labels", "form", "dialog" → `patterns`; "make it better", "clean this up", "finish" → `polish`. Building something new runs the relevant domains' **Building it for a project** sections, in polish order. `colour`, `typography`, `spacing`, `animate` and `copy` work as aliases.
+
+## Before any command
+
+1. **Read `DESIGN.md`** at the project root. `## Profile` gives the preset and any areas on another preset; each domain has its own section; `## Decisions` overrides the preset's defaults and must be respected; `## Open issues` is what's already known.
+2. **No `DESIGN.md`:** for `init`, that's the job. For anything else, run `init`'s scan and mapping for the domains this command touches, do the task, then recommend a full `/keyline init`. Don't refuse.
+3. **Load the command's file**, `commands/<command>.md`. It says which guides to read; read them, don't work from memory of them.
+4. **Preset `glass`:** the exact system from modimihir.com. Read `glass/<domain>/guide.md` beside each domain guide; its values and `assets/` are the recipes.
+
+## What every command holds to
+
+- **The project's names, always.** Reason in roles (`text.secondary`, `duration.small`), write code in whatever the project calls them. Never rename a project's tokens; never add a second token system beside the first.
+- **Measure, don't estimate.** Mechanical laws are checked by `<keyline>/scripts/check.mjs`; contrast comes from `<keyline>/scripts/contrast.mjs`; inventories from `<keyline>/scripts/scan.mjs`; counts from the code. A finding carries its evidence: a ratio, a count, a `file:line`.
+- **Laws hold under every preset; dials move between them.** A change that would break a law, or move a dial off the preset, is said out loud and asked about first. When the user agrees, it goes under `## Decisions` with its date and reason.
+- **Keep what the design already chose.** An existing interface keeps its brand colour and gradients wherever they do a job, and its corners stay at least as round. Only a law removes something, and the report names that law: a pass that leaves the screen greyer or boxier than it found it has to say why.
+- **Findings are not fixes.** `init`, `sync`, `critique` and `audit` change no code. The refining commands change only what their domain owns, and name the owning domain for anything else they notice.
+- **Write back.** A decision that changes the system — a new role, a moved dial, a law knowingly broken — goes into `DESIGN.md`, so the next session starts from it. Fixed issues come off `## Open issues`.
+- **Look at the result.** When the project can be rendered, render it after a change and look at both themes, a narrow width, and reduced motion where they apply. Code that reads right can still look wrong.
+
+## Where things are
+
+| Folder | Holds |
+|---|---|
+| `commands/` | One file per command: what to read, the steps, what to report |
+| `system/` | Setup: the canonical `roles.md`, the four `presets.md`, the `design-md.md` format, `detection.md` for each stack |
+| `domains/<domain>/` | Each domain's `guide.md` — laws, dials per preset, building, auditing, checklist — and its deeper references |
+| `glass/<domain>/` | The `glass` preset: modimihir.com's exact values, with drop-in tokens and components in `assets/` |
+| `scripts/` | `check.mjs` (the detector: 24 mechanical laws, `--json`, exit codes for CI), `scan.mjs` (token and value inventory) and `contrast.mjs` (measured contrast, translucency composited). Node 18+, no dependencies |

package/plugins/keyline/skills/keyline/commands/audit.md

@@ -0,0 +1,25 @@
+# `/keyline audit`
+
+Every law, checked with evidence, per domain — the full inspection `critique` is the summary of. Findings go into `DESIGN.md` so later sessions start from them.
+
+**Read:** `DESIGN.md`, then the `## Auditing existing code` and `## Checklist` sections of every `domains/<domain>/guide.md` (all six unless the user narrows it). Under preset `glass`, also each `glass/<domain>/guide.md` checklist.
+
+**Steps:**
+
+1. **Detector:** `node <keyline>/scripts/check.mjs --root <project root> --json --ignore <prose and example dirs>`. Every finding it returns is evidence already — file, line, law — so start each domain from its findings and spend your reading on what it can't see: hierarchy, grouping, whether a box should exist. Treat a finding as a lead, not a verdict; one you judge wrong goes in the report as such, and gets a `keyline-ignore` comment only if the user agrees.
+2. **Inventory:** `node <keyline>/scripts/scan.mjs . --ignore <prose and example dirs>`.
+3. **Contrast:** every text tier, the focus ring (`--min 3`) and status colours, per theme, with `<keyline>/scripts/contrast.mjs`.
+4. **Per domain, in polish order** — type, colour, layout, depth, motion, patterns — run that guide's audit: its searches, then its evidence per law. Render where the guide asks you to look (widths, themes, reduced motion, keyboard).
+5. **Score each domain** from what you found, the detector's findings and yours together:
+
+| Score | Means |
+|---|---|
+| 4 | Every law holds; nothing to report |
+| 3 | Small strays — a handful of one-off values, nothing a reader would notice |
+| 2 | A law broken in a way a reader feels — a hierarchy inversion, a failed contrast tier, a box around everything |
+| 1 | Several laws broken across templates; the domain isn't working as a system |
+| 0 | No system: values typed inline, nothing on a ladder |
+
+**Report:** a table of the six domains with score and finding count, then findings grouped by domain, worst first, one line each with evidence — `file:line`, a ratio, a count — and the law, with its UX-law name where one explains it (the table in `commands/critique.md`). Close with the order to fix in: usually the lowest score first, unless a law in another domain blocks it.
+
+**Write back:** every finding under `## Open issues` in `DESIGN.md`, replacing entries now fixed. **Changes no code.**

package/plugins/keyline/skills/keyline/commands/color.md

@@ -0,0 +1,7 @@
+# `/keyline color`
+
+**Guide:** `domains/color/guide.md` · **`DESIGN.md` section:** `## Colour` · **Procedure:** `commands/refine.md` · **Alias:** `colour`
+
+Makes colour mean something: tokens named for the job they do rather than their lightness, text tiers chosen by measured contrast and kept strictly descending, a focus colour that's never lost, status colours as foreground and background pairs, colour spent on what needs a person rather than on decoration, and themes that switch without a flash.
+
+Typical finds: one grey doing duty as both a border and a caption; a tier that passes 4.5:1 but is indistinguishable from its neighbour; a second accent hue; success green on steps the reader has simply passed (outside an expressive brand's counted exceptions); a gradient that wasn't re-picked for dark. Every ratio comes from `<keyline>/scripts/contrast.mjs`. Deeper references: `deriving-a-ramp.md`, `status-and-exceptions.md`, `theming-mechanics.md`.