@codepress/design-kit 0.1.1 → 0.1.2

package/README.md

@@ -19,6 +19,47 @@ It runs on Node 20 or later. Playwright is a peer dependency, so the capture
 drives the Playwright and Chromium your project already has. The `kit`
 commands need neither.
 
+## Set up in your repository
+
+`design-kit init` sets a kit up as one reviewable change. Run it in the
+repository's root, or in a monorepo with `--root <package>` (the config goes
+there; the workflow, skill and instructions line go at the repository root):
+
+```bash
+npx @codepress/design-kit init --dry-run   # what it found and would write
+npx @codepress/design-kit init
+```
+
+It looks for Storybook (a `storybook` or `@storybook/*` dependency, or a
+`.storybook` folder, in the project or its workspace packages) and its
+version, the framework (Next.js, Vite, Remix, Create React App, Astro or
+other), the package manager and lockfile, the dev or start script and the
+app's local URL, an existing Playwright, and whether the app switches to dark
+with a class or a `data-theme` attribute. Then it writes:
+
+- `design-kit.config.json`: the `stories` section when Storybook is found, a
+  `pages` section with `TODO` selectors to fill in, and the `theme`.
+- `.github/workflows/design-kit.yml`: a daily build (and `workflow_dispatch`)
+  on `ubuntu-latest`. It skips when there are no commits since the newest
+  `design-kit` artifact's commit; otherwise it installs dependencies, this
+  package at a pinned version and Chromium, builds Storybook and captures the
+  stories, captures the pages once no `TODO` is left in the config, and
+  uploads the `design-kit` artifact for 30 days. A run with nothing to
+  capture yet (no stories, pages still `TODO`) ends with a warning and
+  uploads nothing. The page capture gets
+  `DESIGN_KIT_USERNAME` and `DESIGN_KIT_PASSWORD` from repository secrets for
+  a sign-in module (`pages.auth.setup`).
+- `.claude/skills/design-kit/SKILL.md`: how agents fetch the newest kit,
+  compose mockups from it and caption them, and `.agents/skills/design-kit` as
+  a symlink to it (a copy when the repository keeps real folders there).
+- One line in `AGENTS.md`, or `CLAUDE.md` when only that exists (a new
+  `AGENTS.md` when neither does), pointing at the skill.
+
+It prints what it found and what is still to decide: the page selectors, the
+start command, sign-in, a missing Storybook. It never overwrites an existing
+file without `--force` (a repository with a `design-kit.config.json` exits 1,
+"already set up") and never writes a secret.
+
 ## Configuration
 
 The commands read `design-kit.config.json` from the working directory or the
@@ -109,8 +150,9 @@ export returns (`async ({ browser, baseUrl, config }) => state`).
   for apps that render a different frame at phone width; `layoutSlots[<that
 value>]` then replaces `slots`.
 - `forbidStrings`: values that must never reach the kit, such as a test
-  account's token. A page whose output contains one, as written, escaped for
-  HTML or JSON, or (for a token) any long segment of it, is not written.
+  account's token. When any page's output contains one, as written, escaped
+  for HTML or JSON, or (for a token) any long segment of it, the capture
+  fails (exit 1) and writes no page, so a CI job uploads nothing.
 - `fontsPath`, `copyFonts`: the fonts the pages load are copied into the
   kit's `fonts/` folder (`copyFonts: false` keeps them out); `fontsPath` says
   which URL path holds them when not every font file is one.
@@ -122,6 +164,7 @@ value>]` then replaces `slots`.
 ## Commands
 
 ```bash
+design-kit init            [--root dir] [--dry-run] [--force]
 design-kit capture stories [--config f] [--out dir] [--storybook-dir dir]
                            [--only id,... | --only-file f] [--base previous-kit]
 design-kit capture pages   [--config f] [--out dir] [--base-url url] [--only name,...]
@@ -136,7 +179,8 @@ byte. The two captures share one kit folder and keep each other's files: run
 both with the same `--out`.
 
 Exit codes: 0 done, 1 a capture could not run (no Storybook build, the app
-did not start), 2 a config or usage error. A story or page that fails is a
+did not start, a forbidden string) or `init` found the repository already set
+up, 2 a config or usage error. A story or page that fails is a
 `gaps.json` row and does not fail the run.
 
 Operational knobs: `DESIGN_KIT_CONCURRENCY` (browser pages at once, default

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codepress/design-kit",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Capture your Storybook and real app pages as a static design kit, and compose self-contained mockups from it",
   "type": "module",
   "bin": {

package/src/capture-pages.mjs

@@ -376,8 +376,16 @@ function themeClassesOf(theme) {
  * browser}: set `interrupted` to stop between pages; `browser` is set once
  * launched so a signal handler can close it).
  *
- * Returns 0, or 130 when interrupted (nothing is written then).
+ * Returns 0, or 130 when interrupted (nothing is written then). Throws,
+ * writing nothing, when any page's markup carries a forbidStrings value.
  */
+/** A page's markup carries a forbidStrings value. */
+class ForbiddenStringError extends Error {
+  constructor() {
+    super("the page's markup carries a forbidStrings value");
+  }
+}
+
 export async function capturePages(config, options = {}) {
   const settings = config.pages;
   if (!settings) {
@@ -442,6 +450,7 @@ export async function capturePages(config, options = {}) {
     );
   const timings = {};
   const gaps = [];
+  const leaks = [];
   const rows = [];
   const files = new Map();
   const fontUrls = new Map();
@@ -547,10 +556,7 @@ export async function capturePages(config, options = {}) {
             ].join("\n"),
             needles,
           );
-          if (found)
-            throw new Error(
-              "the page's markup carries a forbidStrings value; not written",
-            );
+          if (found) throw new ForbiddenStringError();
 
           // CSS assets on the app origin (other than fonts) are inlined.
           const inlined = new Map();
@@ -610,6 +616,11 @@ export async function capturePages(config, options = {}) {
             `captured ${id} (${capture.layout}, slots ${capture.slots.join(",")}, ${Math.round(Buffer.byteLength(html) / 1024)} KB, ${((performance.now() - pageStart) / 1000).toFixed(1)}s)`,
           );
         } catch (error) {
+          if (error instanceof ForbiddenStringError) {
+            leaks.push(id);
+            log(`${id}: ${error.message}`);
+            continue;
+          }
           const reason = String(error?.message ?? error)
             .split("\n")
             .slice(0, 3)
@@ -630,6 +641,12 @@ export async function capturePages(config, options = {}) {
       fs.rmSync(shotsDir, { recursive: true, force: true });
   }
 
+  // A leaked value fails the whole capture: no page of this run is written,
+  // so a CI job stops before it uploads anything.
+  if (leaks.length)
+    throw new Error(
+      `${leaks.join(", ")} carried a forbidStrings value; nothing was written`,
+    );
   writePagesKit(out, {
     rows,
     files,

package/src/cli.mjs

@@ -13,6 +13,9 @@ const VERSION = JSON.parse(
 
 const USAGE = `usage: design-kit <command> [options]
 
+  init              set a kit up in this repository: the config, a daily
+                    GitHub Actions build, and a skill for its agents
+      [--root <dir>] [--dry-run] [--force]
   capture stories   capture every story of a Storybook 7/8 static build
       [--config <file>] [--out <dir>] [--storybook-dir <dir>]
       [--only <id,...> | --only-file <file>] [--base <previous kit>]
@@ -27,7 +30,8 @@ const USAGE = `usage: design-kit <command> [options]
 
 The config is the nearest design-kit.config.json at or above the working
 directory unless --config names one. Exit codes: 0 done, 1 a capture could
-not run, 2 a config or usage error.`;
+not run (or init found the repository already set up), 2 a config or usage
+error.`;
 
 function parse(argv, spec) {
   const options = {};
@@ -153,6 +157,19 @@ export async function main(argv = process.argv.slice(2), env = process.env) {
       return 0;
     }
     if (command === "kit") return await kitCommand(argv.slice(1), env);
+    if (command === "init") {
+      const options = parse(argv.slice(1), {
+        root: "value",
+        "dry-run": "flag",
+        force: "flag",
+      });
+      const { init } = await import("./init.mjs");
+      return init({
+        root: options.root ?? ".",
+        dryRun: Boolean(options["dry-run"]),
+        force: Boolean(options.force),
+      });
+    }
     if (command === "validate") {
       const options = parse(argv.slice(1), { config: "value" });
       const config = loadConfig(options.config);

package/src/init.mjs

@@ -0,0 +1,1017 @@
+/**
+ * `design-kit init`: sets a design kit up in a repository. It looks at the
+ * project (Storybook, framework, package manager, dev script, Playwright,
+ * theme) and writes design-kit.config.json, a daily GitHub Actions workflow
+ * that uploads the kit, a design-kit skill for the repository's agents and
+ * one line in AGENTS.md or CLAUDE.md. It never overwrites a file without
+ * --force and never writes a secret.
+ */
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  symlinkSync,
+  writeFileSync,
+  cpSync,
+} from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+
+import { CONFIG_NAME } from "./config.mjs";
+
+const PACKAGE = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+);
+const SKILL_TEMPLATE = new URL(
+  "./templates/design-kit-skill.md",
+  import.meta.url,
+);
+
+export const WORKFLOW_PATH = ".github/workflows/design-kit.yml";
+export const SKILL_DIR = ".claude/skills/design-kit";
+export const AGENTS_SKILL_DIR = ".agents/skills/design-kit";
+const TODO = "TODO";
+
+const IGNORED_DIRS = new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  "out",
+  ".next",
+  ".nuxt",
+  ".svelte-kit",
+  ".astro",
+  ".turbo",
+  ".cache",
+  "coverage",
+  "storybook-static",
+  "design-kit",
+  "vendor",
+]);
+const SCAN_LIMIT = 4000;
+const SCAN_BYTES = 256 * 1024;
+
+/** A problem `init` refuses to work past (exit 1). */
+export class InitError extends Error {}
+
+// ── reading the project ─────────────────────────────────────────────────────
+
+function readJson(file) {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function readText(file) {
+  try {
+    return readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+function isDir(path) {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function deps(pkg) {
+  return {
+    ...pkg?.peerDependencies,
+    ...pkg?.optionalDependencies,
+    ...pkg?.dependencies,
+    ...pkg?.devDependencies,
+  };
+}
+
+/** The folder holding `.git` at or above `from`, else `from` itself. */
+export function findRepoRoot(from) {
+  let dir = resolve(from);
+  for (;;) {
+    if (existsSync(join(dir, ".git"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return resolve(from);
+    dir = parent;
+  }
+}
+
+/** `dir`, then each folder above it up to and including `top`. */
+function upTo(dir, top) {
+  const dirs = [];
+  let current = resolve(dir);
+  for (;;) {
+    dirs.push(current);
+    if (current === top) break;
+    const parent = dirname(current);
+    if (parent === current || !`${current}${sep}`.startsWith(`${top}${sep}`))
+      break;
+    current = parent;
+  }
+  return dirs;
+}
+
+/** Workspace package folders declared by pnpm-workspace.yaml or package.json. */
+function workspacePackages(dir) {
+  const patterns = [];
+  const pnpm = readText(join(dir, "pnpm-workspace.yaml"));
+  if (pnpm) {
+    let inPackages = false;
+    for (const line of pnpm.split("\n")) {
+      if (/^packages:\s*$/.test(line)) inPackages = true;
+      else if (/^\S/.test(line)) inPackages = false;
+      else if (inPackages) {
+        const match = line.match(/^\s*-\s*["']?([^"'#]+?)["']?\s*(#.*)?$/);
+        if (match) patterns.push(match[1].trim());
+      }
+    }
+  }
+  const pkg = readJson(join(dir, "package.json"));
+  const declared = Array.isArray(pkg?.workspaces)
+    ? pkg.workspaces
+    : (pkg?.workspaces?.packages ?? []);
+  patterns.push(...declared);
+
+  const found = [];
+  for (const pattern of patterns) {
+    if (pattern.startsWith("!")) continue;
+    const parts = pattern.replace(/\/+$/, "").split("/");
+    let dirs = [dir];
+    for (const part of parts) {
+      const next = [];
+      for (const base of dirs) {
+        if (part === "*" || part === "**") {
+          for (const entry of safeReaddir(base))
+            if (entry.isDirectory() && !IGNORED_DIRS.has(entry.name))
+              next.push(join(base, entry.name));
+        } else if (isDir(join(base, part))) next.push(join(base, part));
+      }
+      dirs = next;
+    }
+    for (const candidate of dirs)
+      if (
+        existsSync(join(candidate, "package.json")) &&
+        !found.includes(candidate)
+      )
+        found.push(candidate);
+  }
+  return found.sort();
+}
+
+function safeReaddir(dir) {
+  try {
+    return readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}
+
+function installedVersion(name, from, top) {
+  for (const dir of upTo(from, top)) {
+    const pkg = readJson(join(dir, "node_modules", name, "package.json"));
+    if (pkg?.version) return pkg.version;
+  }
+  return null;
+}
+
+function majorOf(version) {
+  const match = String(version ?? "").match(/(\d+)/);
+  return match ? Number(match[1]) : null;
+}
+
+function storybookIn(dir, repoRoot) {
+  const pkg = readJson(join(dir, "package.json"));
+  const all = deps(pkg);
+  const names = Object.keys(all).filter(
+    (name) => name === "storybook" || name.startsWith("@storybook/"),
+  );
+  const hasConfig = isDir(join(dir, ".storybook"));
+  if (!names.length && !hasConfig) return null;
+  const versionName = names.includes("storybook")
+    ? "storybook"
+    : (names.find((name) =>
+        /^@storybook\/(react|vue3|svelte|angular|web-components|html|preact|nextjs|react-vite)/.test(
+          name,
+        ),
+      ) ?? names[0]);
+  const version =
+    (versionName && installedVersion(versionName, dir, repoRoot)) ??
+    (versionName ? all[versionName] : null);
+  return {
+    dir,
+    hasConfig,
+    version: version ?? null,
+    major: majorOf(version),
+  };
+}
+
+const FRAMEWORKS = [
+  { name: "Next.js", deps: ["next"], port: 3000, configs: ["next.config"] },
+  {
+    name: "Remix",
+    deps: ["@remix-run/dev", "@remix-run/react"],
+    port: 3000,
+    configs: ["vite.config", "remix.config"],
+  },
+  { name: "Astro", deps: ["astro"], port: 4321, configs: ["astro.config"] },
+  {
+    name: "Create React App",
+    deps: ["react-scripts"],
+    port: 3000,
+    configs: [],
+  },
+  { name: "Vite", deps: ["vite"], port: 5173, configs: ["vite.config"] },
+];
+
+function frameworkIn(dir) {
+  const all = deps(readJson(join(dir, "package.json")));
+  return FRAMEWORKS.find((framework) =>
+    framework.deps.some((name) => name in all),
+  );
+}
+
+function scriptsIn(dir) {
+  return readJson(join(dir, "package.json"))?.scripts ?? {};
+}
+
+function devScriptName(scripts) {
+  return ["dev", "start", "serve", "preview"].find((name) =>
+    Boolean(scripts[name]),
+  );
+}
+
+const LOCKFILES = [
+  ["pnpm-lock.yaml", "pnpm"],
+  ["yarn.lock", "yarn"],
+  ["bun.lock", "bun"],
+  ["bun.lockb", "bun"],
+  ["package-lock.json", "npm"],
+  ["npm-shrinkwrap.json", "npm"],
+];
+
+function packageManagerOf(project, repoRoot) {
+  let lockfile = null;
+  for (const dir of upTo(project, repoRoot)) {
+    const hit = LOCKFILES.find(([file]) => existsSync(join(dir, file)));
+    if (hit) {
+      lockfile = { file: hit[0], name: hit[1], dir };
+      break;
+    }
+  }
+  let declared = null;
+  for (const dir of upTo(project, repoRoot)) {
+    const field = readJson(join(dir, "package.json"))?.packageManager;
+    if (typeof field === "string") {
+      const match = field.match(/^(npm|pnpm|yarn|bun)@([^+\s]+)/);
+      if (match) {
+        declared = { name: match[1], version: match[2] };
+        break;
+      }
+    }
+  }
+  const name = declared?.name ?? lockfile?.name ?? "npm";
+  const installDir = lockfile?.dir ?? project;
+  let version = declared?.name === name ? declared.version : null;
+  if (!version && name === "pnpm" && lockfile) {
+    const lock = readText(join(lockfile.dir, lockfile.file)) ?? "";
+    const lockVersion = majorOf(
+      lock.match(/lockfileVersion:\s*'?([\d.]+)/)?.[1],
+    );
+    version = lockVersion >= 9 ? "10" : lockVersion === 6 ? "8" : null;
+  }
+  const berry =
+    name === "yarn" &&
+    (existsSync(join(installDir, ".yarnrc.yml")) || majorOf(version) >= 2);
+  return {
+    name,
+    version,
+    declared: Boolean(declared),
+    lockfile: lockfile?.file ?? null,
+    installDir,
+    berry,
+  };
+}
+
+function playwrightOf(project, repoRoot) {
+  for (const dir of upTo(project, repoRoot)) {
+    const all = deps(readJson(join(dir, "package.json")));
+    for (const name of ["@playwright/test", "playwright"])
+      if (all[name])
+        return {
+          name,
+          version: installedVersion(name, dir, repoRoot) ?? all[name],
+          dir,
+        };
+    const config = safeReaddir(dir).find((entry) =>
+      /^playwright\.config\.(m?[jt]s|cjs)$/.test(entry.name),
+    );
+    if (config) return { name: "@playwright/test", version: null, dir };
+  }
+  return null;
+}
+
+/** The app's local URL: a Playwright baseURL, a configured port, or the framework's default. */
+function appUrlOf(project, appDir, framework, repoRoot) {
+  for (const dir of [...new Set([project, appDir, repoRoot])]) {
+    for (const entry of safeReaddir(dir)) {
+      if (!/^playwright\.config\.(m?[jt]s|cjs)$/.test(entry.name)) continue;
+      const text = readText(join(dir, entry.name)) ?? "";
+      const match = text.match(/baseURL:\s*["'`](https?:\/\/[^"'`\s/]+)/);
+      if (match)
+        return {
+          url: `${match[1]}/`,
+          source: relative(repoRoot, join(dir, entry.name)),
+        };
+    }
+  }
+  for (const name of framework?.configs ?? []) {
+    for (const entry of safeReaddir(appDir)) {
+      if (!entry.name.startsWith(`${name}.`)) continue;
+      const text = readText(join(appDir, entry.name)) ?? "";
+      const match = text.match(/\bport:\s*(\d{2,5})\b/);
+      if (match)
+        return {
+          url: `http://localhost:${match[1]}/`,
+          source: relative(repoRoot, join(appDir, entry.name)),
+        };
+    }
+  }
+  return {
+    url: `http://localhost:${framework?.port ?? 3000}/`,
+    source: framework ? `${framework.name}'s default port` : "a guess",
+  };
+}
+
+/** Class or data-theme: whichever the project's styles and scripts use more. */
+function themeOf(dirs) {
+  const score = { class: 0, attribute: 0 };
+  let attributeName = "data-theme";
+  let darkValue = null;
+  let lightValue = null;
+  let scanned = 0;
+  const visit = (dir) => {
+    for (const entry of safeReaddir(dir)) {
+      if (scanned >= SCAN_LIMIT) return;
+      const path = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (!IGNORED_DIRS.has(entry.name) && !entry.name.startsWith("."))
+          visit(path);
+        else if (entry.name === ".storybook") visit(path);
+        continue;
+      }
+      if (
+        !/\.(css|scss|sass|less|[cm]?[jt]sx?|html|vue|svelte|astro)$/.test(
+          entry.name,
+        )
+      )
+        continue;
+      scanned += 1;
+      let text;
+      try {
+        if (statSync(path).size > SCAN_BYTES) continue;
+        text = readFileSync(path, "utf8");
+      } catch {
+        continue;
+      }
+      const attr = text.match(
+        /\[(data-(?:theme|mode|color-scheme))=["']?(dark)["']?\]|(data-(?:theme|mode|color-scheme))=["'](dark)["']|setAttribute\(\s*["'](data-(?:theme|mode|color-scheme))["']|attribute=["'](data-[a-z-]+)["']/,
+      );
+      if (attr) {
+        score.attribute += 2;
+        attributeName =
+          attr[1] ?? attr[3] ?? attr[5] ?? attr[6] ?? attributeName;
+        if (attr[2] || attr[4]) darkValue = "dark";
+        const light = text.match(
+          new RegExp(
+            `\\[${attributeName}=["']?(light)["']?\\]|${attributeName}=["'](light)["']`,
+          ),
+        );
+        if (light) lightValue = "light";
+      }
+      if (
+        /darkMode:\s*\[?\s*["'](class|selector)["']/.test(text) ||
+        /@custom-variant\s+dark\s+\(&:where\(\.dark/.test(text) ||
+        /classList\.(add|toggle|remove)\(\s*["']dark["']/.test(text) ||
+        /attribute=["']class["']/.test(text) ||
+        /(^|[\s,}])\.dark\s*[{,:.\s]/m.test(text)
+      )
+        score.class += 1;
+    }
+  };
+  for (const dir of dirs) visit(dir);
+  if (score.attribute > score.class)
+    return {
+      attribute: attributeName,
+      dark: darkValue ?? "dark",
+      ...(lightValue ? { light: lightValue } : {}),
+      evidence: `${attributeName} attribute`,
+    };
+  return {
+    attribute: "class",
+    dark: "dark",
+    evidence: score.class ? "a dark class" : null,
+  };
+}
+
+/**
+ * Everything `init` decides from: the project folder (`root`, where the
+ * config goes) and the repository around it.
+ */
+export function detectProject(root) {
+  const project = resolve(root);
+  if (!isDir(project)) throw new InitError(`${project}: no such folder`);
+  const repoRoot = findRepoRoot(project);
+  const workspaces = workspacePackages(project);
+  const packages = [project, ...workspaces];
+
+  const storybooks = packages
+    .map((dir) => storybookIn(dir, repoRoot))
+    .filter(Boolean);
+  const storybook = storybooks[0] ?? null;
+
+  // The app: the project itself when it is one, else the first workspace
+  // package with a framework and a dev script that is not only a Storybook.
+  let app = null;
+  for (const dir of packages) {
+    const framework = frameworkIn(dir);
+    const script = devScriptName(scriptsIn(dir));
+    const onlyStorybook =
+      storybookIn(dir, repoRoot) &&
+      (!script || /storybook/.test(scriptsIn(dir)[script]));
+    if (framework && script && !onlyStorybook) {
+      app = { dir, framework, script };
+      break;
+    }
+  }
+  const framework = app?.framework ?? frameworkIn(project) ?? null;
+  const appDir = app?.dir ?? project;
+
+  const pm = packageManagerOf(project, repoRoot);
+  const rootScript = devScriptName(scriptsIn(project));
+  let dev = null;
+  if (rootScript && !/storybook/.test(scriptsIn(project)[rootScript]))
+    dev = {
+      dir: project,
+      script: rootScript,
+      command: runScript(pm, rootScript),
+    };
+  else if (app)
+    dev = {
+      dir: app.dir,
+      script: app.script,
+      command: runWorkspaceScript(
+        pm,
+        readJson(join(app.dir, "package.json"))?.name,
+        app.script,
+        relative(project, app.dir),
+      ),
+    };
+
+  return {
+    project,
+    repoRoot,
+    workspaces,
+    storybook,
+    otherStorybooks: storybooks.slice(1).map((sb) => sb.dir),
+    framework: framework ? { name: framework.name, dir: appDir } : null,
+    packageManager: pm,
+    dev,
+    appUrl: appUrlOf(project, appDir, framework, repoRoot),
+    playwright: playwrightOf(project, repoRoot),
+    theme: themeOf(packages),
+    nodeVersion: nodeVersionOf(project, repoRoot),
+  };
+}
+
+function nodeVersionOf(project, repoRoot) {
+  for (const dir of upTo(project, repoRoot)) {
+    for (const file of [".nvmrc", ".node-version"])
+      if (existsSync(join(dir, file)))
+        return { file: relative(repoRoot, join(dir, file)) || file };
+  }
+  for (const dir of upTo(project, repoRoot)) {
+    const engines = readJson(join(dir, "package.json"))?.engines?.node;
+    const major = majorOf(engines);
+    if (major) return { version: String(Math.max(major, 20)) };
+  }
+  return { version: "22" };
+}
+
+// ── package manager commands ────────────────────────────────────────────────
+
+function runScript(pm, script) {
+  return pm.name === "npm" ? `npm run ${script}` : `${pm.name} run ${script}`;
+}
+
+function runWorkspaceScript(pm, name, script, dir) {
+  if (!name) return `cd ${dir} && ${runScript(pm, script)}`;
+  if (pm.name === "pnpm") return `pnpm --filter ${name} run ${script}`;
+  if (pm.name === "yarn") return `yarn workspace ${name} run ${script}`;
+  if (pm.name === "bun") return `bun run --filter ${name} ${script}`;
+  return `npm run ${script} --workspace ${name}`;
+}
+
+function execBin(pm) {
+  if (pm.name === "pnpm") return "pnpm exec";
+  if (pm.name === "yarn") return pm.berry ? "yarn exec" : "npx";
+  if (pm.name === "bun") return "bunx";
+  return "npx";
+}
+
+function installCommand(pm) {
+  if (!pm.lockfile)
+    return pm.name === "npm" ? "npm install" : `${pm.name} install`;
+  if (pm.name === "pnpm") return "pnpm install --frozen-lockfile";
+  if (pm.name === "yarn")
+    return pm.berry
+      ? "yarn install --immutable"
+      : "yarn install --frozen-lockfile";
+  if (pm.name === "bun") return "bun install --frozen-lockfile";
+  return "npm ci";
+}
+
+// ── what init writes ────────────────────────────────────────────────────────
+
+/** The Playwright this package is tested with, pinned in what init writes. */
+function playwrightPin() {
+  return PACKAGE.devDependencies?.["@playwright/test"] ?? "1.58.2";
+}
+
+function posix(path) {
+  return path.split(sep).join("/");
+}
+
+/** design-kit.config.json, as an object. */
+export function buildConfig(found) {
+  const config = {
+    $schema: `https://unpkg.com/${PACKAGE.name}@${PACKAGE.version}/schema/design-kit.config.schema.json`,
+    version: 1,
+    out: "design-kit",
+    theme: {
+      attribute: found.theme.attribute,
+      dark: found.theme.dark,
+      ...(found.theme.light ? { light: found.theme.light } : {}),
+    },
+  };
+  if (found.storybook) {
+    const root = posix(relative(found.project, found.storybook.dir)) || ".";
+    config.stories = {
+      root,
+      buildCommand: `${execBin(found.packageManager)} storybook build --quiet -o storybook-static`,
+      staticDir: "storybook-static",
+      ...(isDir(join(found.storybook.dir, "src"))
+        ? { gaps: { componentGlob: "src/**/[A-Z]*.{tsx,jsx,vue,svelte}" } }
+        : {}),
+    };
+  }
+  config.pages = {
+    startCommand:
+      found.dev?.command ?? `${TODO}: the command that starts the app`,
+    waitUrl: found.appUrl.url,
+    pages: [
+      {
+        name: "home",
+        title: "Home",
+        path: "/",
+        ready: `${TODO}: a selector that shows once the page has its content, such as "main h1"`,
+        slots: {
+          main: [
+            `${TODO}: the selector of the page's main content region, such as "main"`,
+          ],
+        },
+      },
+    ],
+  };
+  return config;
+}
+
+/** .github/workflows/design-kit.yml, as text. */
+export function buildWorkflow(found) {
+  const pm = found.packageManager;
+  const rel = (path) => posix(relative(found.repoRoot, path)) || ".";
+  const projectDir = rel(found.project);
+  const at = (path) => (projectDir === "." ? path : `${projectDir}/${path}`);
+  const installDir = rel(pm.installDir);
+  const node = found.nodeVersion.file
+    ? `node-version-file: ${found.nodeVersion.file}`
+    : `node-version: "${found.nodeVersion.version}"`;
+  const cache =
+    pm.lockfile && pm.name !== "bun" ? `\n          cache: ${pm.name}` : "";
+  const cachePath =
+    cache && installDir !== "."
+      ? `\n          cache-dependency-path: ${installDir}/${pm.lockfile}`
+      : "";
+
+  const setup = [];
+  if (pm.name === "pnpm")
+    setup.push(
+      pm.declared || !pm.version
+        ? "      - uses: pnpm/action-setup@v6"
+        : `      - uses: pnpm/action-setup@v6\n        with:\n          version: ${pm.version}`,
+    );
+  if (pm.name === "yarn" && pm.berry)
+    setup.push("      - run: corepack enable");
+  if (pm.name === "bun") setup.push("      - uses: oven-sh/setup-bun@v2");
+  setup.push(
+    `      - uses: actions/setup-node@v5\n        with:\n          ${node}${cache}${cachePath}`,
+  );
+
+  const storiesStep = found.storybook
+    ? `
+      - name: Build Storybook and capture stories
+        working-directory: \${{ runner.temp }}/design-kit-cli
+        run: design-kit capture stories --config "$CONFIG"
+`
+    : "";
+
+  return `name: Design kit
+
+# Captures this repository's design kit once a day: ${found.storybook ? "every Storybook story and " : ""}the
+# pages listed in ${at(CONFIG_NAME)}, as static HTML with the CSS and fonts
+# they load. It uploads the result as the \`design-kit\` artifact (kept 30
+# days), which agents download to draw mockups from the app's real markup.
+# A day with no new commits since the newest kit builds nothing.
+#
+# Written by \`design-kit init\` (${PACKAGE.name}). Edit it freely.
+
+on:
+  schedule:
+    - cron: "23 5 * * *"
+  workflow_dispatch:
+    inputs:
+      force:
+        description: Build even when the newest kit is from this commit
+        type: boolean
+        default: false
+      package:
+        description: "The ${PACKAGE.name} to install, as an npm package spec (default: the pinned version below)"
+        type: string
+        default: ""
+
+permissions:
+  contents: read
+
+concurrency:
+  group: design-kit-\${{ github.ref }}
+  cancel-in-progress: false
+
+env:
+  DESIGN_KIT_PACKAGE: "${PACKAGE.name}@${PACKAGE.version}"
+  PLAYWRIGHT_PACKAGE: "@playwright/test@${playwrightPin()}"
+  CONFIG: \${{ github.workspace }}/${at(CONFIG_NAME)}
+
+jobs:
+  check:
+    name: Any commits since the newest kit?
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      actions: read
+    outputs:
+      build: \${{ steps.last.outputs.build }}
+    steps:
+      - id: last
+        env:
+          GH_TOKEN: \${{ github.token }}
+          FORCE: \${{ inputs.force || 'false' }}
+        run: |
+          last=$(gh api "repos/$GITHUB_REPOSITORY/actions/artifacts?name=design-kit&per_page=100" \\
+            --jq "[.artifacts[] | select((.expired | not) and .workflow_run.head_branch == \\"$GITHUB_REF_NAME\\")] | sort_by(.created_at) | last | .workflow_run.head_sha // \\"\\"") || last=""
+          if [ "$FORCE" != "true" ] && [ -n "$last" ] && [ "$last" = "$GITHUB_SHA" ]; then
+            echo "The newest design kit is from $GITHUB_SHA and there are no commits since: nothing to build." | tee -a "$GITHUB_STEP_SUMMARY"
+            echo "build=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "build=true" >> "$GITHUB_OUTPUT"
+          fi
+
+  build:
+    name: Build the design kit
+    needs: check
+    if: needs.check.outputs.build == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+
+${setup.join("\n\n")}
+
+      - name: Install dependencies${installDir === "." ? "" : `\n        working-directory: ${installDir}`}
+        run: ${installCommand(pm)}
+
+      # The capture runs from this folder so it drives the pinned Playwright
+      # and the Chromium installed for it, whatever the project depends on.
+      - name: Install design-kit and Chromium
+        working-directory: \${{ runner.temp }}
+        env:
+          PACKAGE: \${{ inputs.package || env.DESIGN_KIT_PACKAGE }}
+        run: |
+          mkdir -p design-kit-cli && cd design-kit-cli
+          npm init -y > /dev/null
+          npm install --no-audit --no-fund "$PACKAGE" "$PLAYWRIGHT_PACKAGE"
+          npx playwright install --with-deps chromium
+          echo "$PWD/node_modules/.bin" >> "$GITHUB_PATH"
+${storiesStep}
+      # Signing in: when the pages need a signed-in user, name a sign-in
+      # module in pages.auth.setup and have it read these secrets (add them
+      # under Settings > Secrets and variables > Actions). Never commit a
+      # credential. Until the TODO page settings are filled in, pages are
+      # skipped with a warning.
+      - name: Capture pages
+        working-directory: \${{ runner.temp }}/design-kit-cli
+        env:
+          DESIGN_KIT_USERNAME: \${{ secrets.DESIGN_KIT_USERNAME }}
+          DESIGN_KIT_PASSWORD: \${{ secrets.DESIGN_KIT_PASSWORD }}
+        run: |
+          if grep -q '"${TODO}' "$CONFIG"; then
+            echo "::warning title=Design kit::${at(CONFIG_NAME)} still has ${TODO} page settings, so no pages were captured. Fill them in, or remove the pages section."
+          else
+            design-kit capture pages --config "$CONFIG"
+          fi
+
+      # Nothing captured yet (no stories, and the pages still have ${TODO}s):
+      # the run ends here with a warning instead of failing to upload.
+      - name: Nothing to capture yet
+        if: hashFiles('${at("design-kit")}/manifest.json') == ''
+        run: |
+          echo "::warning title=Design kit::Nothing to capture yet, so no kit was uploaded: ${at(CONFIG_NAME)} has no stories and its pages still have ${TODO} settings. Fill in the pages (or add Storybook) and run this workflow again."
+
+      - if: hashFiles('${at("design-kit")}/manifest.json') != ''
+        uses: actions/upload-artifact@v5
+        with:
+          name: design-kit
+          path: ${at("design-kit")}
+          retention-days: 30
+          if-no-files-found: error
+`;
+}
+
+/** .claude/skills/design-kit/SKILL.md, as text. */
+export function buildSkill(found) {
+  const pm = found.packageManager;
+  const projectDir = posix(relative(found.repoRoot, found.project)) || ".";
+  const watched = found.storybook
+    ? [...new Set([found.storybook.dir, found.framework?.dir ?? found.project])]
+    : [found.framework?.dir ?? found.project];
+  const watchedPaths =
+    watched
+      .map((dir) => posix(relative(found.repoRoot, dir)) || ".")
+      .join(" ") || ".";
+  const cli = `npx --yes -p ${PACKAGE.name}@${PACKAGE.version} -p @playwright/test@${playwrightPin()} design-kit`;
+  const values = {
+    CLI: cli,
+    CONFIG: projectDir === "." ? CONFIG_NAME : `${projectDir}/${CONFIG_NAME}`,
+    PROJECT_DIR: projectDir,
+    WATCHED_PATHS: watchedPaths,
+    STORIES_LINE: found.storybook
+      ? `$DK capture stories --config "$CONFIG" --out "$KIT"   # builds Storybook first`
+      : `# (no Storybook: this kit has pages only)`,
+    PACKAGE: PACKAGE.name,
+    INSTALL: installCommand(pm),
+    // The capture drives the project's own Playwright when it has one.
+    PLAYWRIGHT_INSTALL: found.playwright
+      ? `${execBin(pm)} playwright install chromium`
+      : `npx --yes -p @playwright/test@${playwrightPin()} playwright install chromium`,
+  };
+  const template = readFileSync(SKILL_TEMPLATE, "utf8");
+  return template.replace(/\{\{([A-Z_]+)\}\}/g, (match, key) =>
+    key in values ? values[key] : match,
+  );
+}
+
+const AGENTS_LINE =
+  "- **Mockups and UI designs:** use the `design-kit` skill (`.claude/skills/design-kit/SKILL.md`). It composes mockups from this app's real pages and components, which `.github/workflows/design-kit.yml` captures every day.";
+
+function agentsSkillMode(repoRoot) {
+  const dir = join(repoRoot, ".agents", "skills");
+  const entries = safeReaddir(dir);
+  if (entries.some((entry) => entry.isSymbolicLink())) return "symlink";
+  if (entries.some((entry) => entry.isDirectory())) return "copy";
+  return "symlink";
+}
+
+function instructionsFile(repoRoot) {
+  for (const name of ["AGENTS.md", "CLAUDE.md"])
+    if (existsSync(join(repoRoot, name))) return name;
+  return "AGENTS.md";
+}
+
+/**
+ * The plan: every file init writes, with its content, and the notes for the
+ * summary. Nothing is written here.
+ */
+export function planInit(found) {
+  const at = (path) => join(found.repoRoot, path);
+  const skill = buildSkill(found);
+  const instructions = instructionsFile(found.repoRoot);
+  const instructionsText = readText(at(instructions));
+  const writes = [
+    {
+      path: join(found.project, CONFIG_NAME),
+      kind: "file",
+      content: `${JSON.stringify(buildConfig(found), null, 2)}\n`,
+    },
+    { path: at(WORKFLOW_PATH), kind: "file", content: buildWorkflow(found) },
+    { path: at(`${SKILL_DIR}/SKILL.md`), kind: "file", content: skill },
+    agentsSkillMode(found.repoRoot) === "symlink"
+      ? {
+          path: at(AGENTS_SKILL_DIR),
+          kind: "symlink",
+          target: posix(relative(dirname(at(AGENTS_SKILL_DIR)), at(SKILL_DIR))),
+        }
+      : { path: at(AGENTS_SKILL_DIR), kind: "copy", from: at(SKILL_DIR) },
+  ];
+  if (instructionsText?.includes("skills/design-kit"))
+    writes.push({ path: at(instructions), kind: "unchanged" });
+  else
+    writes.push({
+      path: at(instructions),
+      kind: instructionsText === null ? "file" : "append",
+      content:
+        instructionsText === null
+          ? `# Agent instructions\n\n${AGENTS_LINE}\n`
+          : `${instructionsText.endsWith("\n") ? "" : "\n"}\n${AGENTS_LINE}\n`,
+    });
+  return { writes };
+}
+
+function exists(path) {
+  try {
+    lstatSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function apply(write) {
+  mkdirSync(dirname(write.path), { recursive: true });
+  if (write.kind === "file") writeFileSync(write.path, write.content);
+  else if (write.kind === "append")
+    writeFileSync(write.path, write.content, { flag: "a" });
+  else if (write.kind === "symlink") {
+    rmSync(write.path, { recursive: true, force: true });
+    symlinkSync(write.target, write.path, "dir");
+  } else if (write.kind === "copy") {
+    rmSync(write.path, { recursive: true, force: true });
+    cpSync(write.from, write.path, { recursive: true });
+  }
+}
+
+// ── the summary ─────────────────────────────────────────────────────────────
+
+function describe(found) {
+  const rel = (path) => posix(relative(found.repoRoot, path)) || ".";
+  const pm = found.packageManager;
+  const sb = found.storybook;
+  return [
+    [
+      "Storybook",
+      sb
+        ? `${sb.version ?? "version unknown"} in ${rel(sb.dir)}${sb.hasConfig ? " (.storybook)" : " (no .storybook folder)"}${found.otherStorybooks.length ? `; also in ${found.otherStorybooks.map(rel).join(", ")}` : ""}`
+        : "none",
+    ],
+    [
+      "Framework",
+      found.framework
+        ? `${found.framework.name} in ${rel(found.framework.dir)}`
+        : "not recognized (other)",
+    ],
+    [
+      "Packages",
+      `${pm.name}${pm.version ? ` ${pm.version}` : ""}${pm.lockfile ? ` (${rel(join(pm.installDir, pm.lockfile))})` : " (no lockfile)"}`,
+    ],
+    [
+      "Dev script",
+      found.dev
+        ? `${found.dev.command} -> ${found.appUrl.url} (from ${found.appUrl.source})`
+        : "none found",
+    ],
+    [
+      "Playwright",
+      found.playwright
+        ? `${found.playwright.name}${found.playwright.version ? ` ${found.playwright.version}` : ""}`
+        : "none (the workflow installs its own)",
+    ],
+    [
+      "Theme",
+      found.theme.evidence
+        ? `${found.theme.attribute === "class" ? `class "${found.theme.dark}"` : `${found.theme.attribute}="${found.theme.dark}"`} (from ${found.theme.evidence})`
+        : `class "dark" (a guess: no dark theme found)`,
+    ],
+  ];
+}
+
+function todo(found) {
+  const items = [];
+  const sb = found.storybook;
+  if (!sb)
+    items.push(
+      "No Storybook: the config captures pages only. Decide whether to add Storybook with stories for the components the main screens use, capture real pages, or both.",
+    );
+  else if (sb.major && (sb.major < 7 || sb.major > 8))
+    items.push(
+      `Storybook ${sb.version}: captures are supported for Storybook 7 and 8 static builds; check that \`capture stories\` works, or use page capture.`,
+    );
+  items.push(
+    `Pages: replace the ${TODO} selectors in ${CONFIG_NAME} (pages[].ready and slots.main), add the app's main screens, and check startCommand and waitUrl. Until then the workflow skips page capture.`,
+  );
+  if (!found.dev)
+    items.push(
+      "No dev or start script found: set pages.startCommand to the command that serves the app.",
+    );
+  items.push(
+    "Sign-in: if the pages need a signed-in user, use a seeded test user or the app's mock mode, and a sign-in module (pages.auth.setup) that reads repository secrets in CI. Never commit a credential.",
+  );
+  if (!found.theme.evidence)
+    items.push(
+      "Theme: no dark theme was found; check the theme section, or remove it if the app has no dark mode.",
+    );
+  items.push(
+    "Build the kit once locally (see the design-kit skill) and say in the pull request what it captured and what it missed.",
+  );
+  return items;
+}
+
+function summary(found, plan, { dryRun }) {
+  const rel = (path) => posix(relative(found.repoRoot, path)) || ".";
+  const lines = [
+    `design-kit init${dryRun ? " --dry-run" : ""}: ${found.project}`,
+    "",
+    "Found",
+  ];
+  const rows = describe(found);
+  const width = Math.max(...rows.map(([label]) => label.length));
+  for (const [label, value] of rows)
+    lines.push(`  ${label.padEnd(width)}  ${value}`);
+  lines.push("", dryRun ? "Would write" : "Wrote");
+  for (const write of plan.writes) {
+    const note =
+      write.kind === "symlink"
+        ? ` -> ${write.target}`
+        : write.kind === "copy"
+          ? ` (a copy of ${rel(write.from)})`
+          : write.kind === "append"
+            ? " (one line added)"
+            : write.kind === "unchanged"
+              ? " (unchanged: it already points at the skill)"
+              : "";
+    lines.push(`  ${rel(write.path)}${note}`);
+  }
+  lines.push("", "Still to decide");
+  for (const item of todo(found)) lines.push(`  - ${item}`);
+  return lines.join("\n");
+}
+
+// ── the command ─────────────────────────────────────────────────────────────
+
+/**
+ * Runs init. Options: `root` (the project folder, default the working
+ * directory), `dryRun`, `force`, `log`. Returns the exit code: 0 done, 1
+ * already set up or another file in the way.
+ */
+export function init({
+  root = ".",
+  dryRun = false,
+  force = false,
+  log = console.log,
+} = {}) {
+  const found = detectProject(root);
+  const plan = planInit(found);
+  if (!force) {
+    const config = join(found.project, CONFIG_NAME);
+    if (exists(config))
+      throw new InitError(
+        `already set up: ${config} exists. Nothing was written; pass --force to replace the files init writes.`,
+      );
+    const inTheWay = plan.writes
+      .filter(
+        (write) =>
+          write.kind === "file" ||
+          write.kind === "symlink" ||
+          write.kind === "copy",
+      )
+      .filter((write) => exists(write.path))
+      .map((write) => posix(relative(found.repoRoot, write.path)));
+    if (inTheWay.length)
+      throw new InitError(
+        `${inTheWay.join(", ")} already exist${inTheWay.length === 1 ? "s" : ""}. Nothing was written; pass --force to replace ${inTheWay.length === 1 ? "it" : "them"}.`,
+      );
+  }
+  if (!dryRun) {
+    // The skill folder is written before the copy or link that points at it.
+    for (const write of plan.writes)
+      if (write.kind !== "unchanged") apply(write);
+  }
+  log(summary(found, plan, { dryRun }));
+  return 0;
+}

package/src/templates/design-kit-skill.md

@@ -0,0 +1,156 @@
+---
+name: design-kit
+description: "Draw mockups of this app's screens from its design kit: real pages and Storybook stories captured every day as static HTML, composed into self-contained pages with only the new parts hand-drawn. Use for any mockup, design or screen page of this app. Covers fetching the newest kit with gh, kit find/show/compose, <kit-snippet> and data-kit-new, staleness, captions saying what is real and what is new, and what to do when no kit can be fetched."
+---
+
+# Design kit
+
+Mockups of this app's screens start from its **design kit**: real pages of
+the app and its Storybook stories, rendered to static HTML with the app's own
+CSS and fonts, plus `kit.mjs`, a dependency-free tool that finds pieces and
+composes self-contained pages. Draw only what is new; the frame and every
+existing component come from the kit, so the mockup looks like the app it will
+ship in.
+
+The kit is configured in `{{CONFIG}}` and built by the `Design kit` workflow
+(`.github/workflows/design-kit.yml`). The format and every command are in the
+`{{PACKAGE}}` README.
+
+## 1. Fetch the newest kit
+
+The workflow runs once a day and on demand (`workflow_dispatch`), and uploads
+the `design-kit` artifact (kept 30 days). A day with no new commits skips and
+uploads nothing, yet still succeeds, so look up the newest artifact rather than
+the newest run, then download it once per kit commit:
+
+```bash
+REPO=$(gh repo view --json nameWithOwner --jq .nameWithOwner)
+BRANCH=$(gh repo view --json defaultBranchRef --jq .defaultBranchRef.name)
+read -r RUN SHA < <(gh api "repos/$REPO/actions/artifacts?name=design-kit&per_page=100" \
+  --jq "[.artifacts[] | select((.expired | not) and .workflow_run.head_branch == \"$BRANCH\")]
+        | sort_by(.created_at) | last // empty | \"\(.workflow_run.id) \(.workflow_run.head_sha)\"")
+echo "run=$RUN sha=$SHA"   # empty → go to "When there is no kit"
+KIT="${TMPDIR:-/tmp}/design-kit-$SHA"
+if [ -n "$RUN" ] && [ ! -f "$KIT/manifest.json" ]; then
+  rm -rf "$KIT.partial" &&
+    gh run download "$RUN" --repo "$REPO" -n design-kit -D "$KIT.partial" &&
+    mv "$KIT.partial" "$KIT"
+fi
+node "$KIT/kit.mjs" info   # manifest: sha, built_at, counts, sources
+```
+
+Reuse `$KIT` while the newest kit's SHA is unchanged. Keep the kit and your
+working files in a scratch folder, never in the repository.
+
+## 2. Check staleness
+
+The kit is a snapshot of `manifest.sha`, up to a day behind. Check whether UI
+code changed since:
+
+```bash
+KIT_SHA=$(node -p 'require(process.argv[1]).sha' "$KIT/manifest.json")
+git fetch -q origin "$BRANCH" && git log --oneline "$KIT_SHA..origin/$BRANCH" -- {{WATCHED_PATHS}}
+```
+
+When the list is not empty, say so on the mockup: "Kit from `<sha7>`; N UI
+commits since, so parts of the frame may be out of date". When one of those
+commits touches a component the mockup shows, read it and say what the mockup
+is missing.
+
+## 3. Find what is real
+
+```bash
+node "$KIT/kit.mjs" find button          # ≤ 30 lines: id, kind, width, bytes, title
+node "$KIT/kit.mjs" show route:home@1280 # path, size and an outline with slots
+```
+
+- **Frames** are whole screens: `route:<page>@<width>` rows, real pages of the
+  app at 1280 and 390 wide, with replaceable regions marked `data-kit-slot`
+  (`main` on every page). New content goes only into a slot, and only `route:`
+  frames have slots. A story frame is still useful unchanged, as the "today"
+  view or as real context beside a mockup.
+- **Snippets** are stories: `story:<storybook-id>@<width>`, one per component
+  state. Search by component and state (`find empty`, `find dialog`).
+- `show` prints a short outline. Use `show --full` only on a small snippet
+  whose structure you need, never on a frame.
+- Anything not in the kit has no story or its capture failed (`gaps.json` in
+  the kit lists the failures). Draw it as new and say it is approximated.
+
+## 4. Write only the new content
+
+Write one HTML fragment per slot you change, in your scratch folder:
+
+```html
+<!-- $WORK/after-main.html → fills the frame's `main` slot -->
+<div class="page">
+  <kit-snippet id="story:components-card--default@1280"></kit-snippet>
+  <section data-kit-new class="card">…only what the change adds…</section>
+</div>
+```
+
+- `<kit-snippet id="…">` places a real component; `compose` expands it with
+  the captured markup.
+- Mark every hand-drawn element with `data-kit-new` (the outermost new element
+  is enough).
+- Style new parts with the app's own classes and CSS variables. The kit's CSS
+  holds only the rules the app actually loads, so check a class exists with
+  `grep -c '\.<class>' "$KIT"/css/*.css`, or use an inline `style` with the
+  app's variables.
+- To show several states of the new part, stack them inside the fragment, each
+  with a short label.
+
+## 5. Compose
+
+```bash
+node "$KIT/kit.mjs" compose --frame route:home@1280 \
+  --slot main="$WORK/after-main.html" --out "$WORK/after-desktop.html"
+node "$KIT/kit.mjs" compose --frame route:home@1280 --out "$WORK/today.html"
+```
+
+The result is one self-contained page: CSS and fonts inlined, scripts and
+remote URLs removed, and `data-kit-sha` and `data-kit-id` on `<html>`. Add
+`--theme dark` for the dark theme and `--show-new` for a dashed outline on
+every `data-kit-new` element. An unknown frame, slot or snippet id exits 2 and
+names near matches.
+
+Never paste snippet or frame markup through your own output, and do not read a
+composed page back: it carries the whole CSS and fonts. Open it in a browser,
+screenshot it, and share the screenshot or the file.
+
+## 6. Caption: what is real, what is new
+
+Under every mockup, say which parts are real and which are new, and where you
+approximated:
+
+> Real: the Home page (`route:home@1280`) and the card
+> (`story:components-card--default@1280`), from kit `3f2a9c1` built
+> 2026-11-03. New (dashed): the Pinned section. Approximated: the pin menu has
+> no story yet.
+
+Add the staleness line from step 2 when it applies. For other widths, compose
+the capture on the same side of the breakpoint and say that layout decided in
+script stays as captured.
+
+## When there is no kit
+
+1. **Build it locally** from an up-to-date checkout with dependencies
+   installed (`{{INSTALL}}`):
+
+   ```bash
+   DK="{{CLI}}"
+   CONFIG="$PWD/{{CONFIG}}"
+   KIT="${TMPDIR:-/tmp}/design-kit-local-$(git rev-parse --short HEAD)"
+   {{PLAYWRIGHT_INSTALL}}
+   {{STORIES_LINE}}
+   $DK capture pages --config "$CONFIG" --out "$KIT"     # starts the app itself
+   ```
+
+   Then follow steps 3–6 with this `$KIT` and caption it as "local build at
+   `<sha7>`". A page capture that fails leaves a kit of stories only: compose
+   story frames unchanged for real context, draw the new screen by hand and
+   say so.
+
+2. **No kit at all**: approximate from the app's styles and components, and say
+   on every mockup "Approximated: the design kit was unavailable (<reason>)".
+
+Either way the work goes ahead; the caption says what you could not use.