@codepress/design-kit 0.3.0 → 0.4.0

package/README.md

@@ -79,11 +79,19 @@ components, and draws only what is new.
 
 Nothing needs re-running after setup.
 
-- **It rebuilds itself.** The workflow `init` wrote
-  (`.github/workflows/design-kit.yml`) builds the kit every day, and on
-  demand from "Run workflow" in the Actions tab or with
-  `gh workflow run design-kit.yml`. A day with no new commits since the last
-  kit is skipped. Each kit is kept for 30 days.
+- **It rebuilds itself, only when the UI changed.** The workflow `init`
+  wrote (`.github/workflows/design-kit.yml`) checks every day, and on demand
+  from "Run workflow" in the Actions tab or with
+  `gh workflow run design-kit.yml`. It builds only when a path in the
+  config's `watch` list changed since the newest kit's commit, and at least
+  every 75 days (`DESIGN_KIT_MAX_AGE_DAYS` in the workflow) so the kit never
+  expires. Any other day it stops after a few seconds, and the run's summary
+  says why it built or skipped. "Run workflow" with `force` builds anyway.
+- **Kits are kept 90 days, and older ones deleted.** 90 days is the most a
+  public repository allows; a private one may raise `retention-days` in the
+  workflow to 400 (raise `DESIGN_KIT_MAX_AGE_DAYS` with it). After each
+  upload the workflow deletes the branch's older kits, so only the newest is
+  stored. A failed delete is a warning, never a failed run.
 - **It captures what exists at that commit.** Every build captures the
   stories and pages that exist at the commit it runs on. It never writes
   stories, so a new component shows up in the kit once it has a story. With
@@ -97,7 +105,46 @@ Nothing needs re-running after setup.
 - **Re-run `init` only to start over** (`--force`). To pick up a new release
   of this package, update the pinned version in the workflow
   (`DESIGN_KIT_PACKAGE`); the "Run workflow" form's `package` input tries
-  another version for one run.
+  another version for one run (and always builds).
+
+### What makes it rebuild: `watch`
+
+`watch` in `design-kit.config.json` lists the folders and files, relative to
+the repository root, whose change rebuilds the kit. `init` writes:
+
+- the Storybook folder and the app's folder (when either is the repository
+  root, its UI folders such as `src`, `app` and `.storybook` and files such
+  as `package.json` and `tailwind.config.ts`, since watching the whole root
+  would rebuild on every commit);
+- the workspace packages they depend on, directly or through each other,
+  since shared UI usually lives there in a monorepo;
+- global styles and tokens at the root (`styles`, `tokens`, `theme`, a
+  Tailwind or PostCSS config);
+- `design-kit.config.json` itself, the lockfile and the workflow.
+
+A pages-only repository (no Storybook) gets the app's folder and its
+workspace dependencies. Edit the list freely: add a folder the UI reads from
+(fixtures, a shared assets package), or drop one that changes often without
+changing what renders. Paths only, no globs. Without `watch`, any commit
+rebuilds. The installed `design-kit` skill reads the same list when it counts
+the UI commits since a kit, so its caption matches what triggers a rebuild.
+
+### Updating a setup made by an older version
+
+An older workflow keeps working as it is. To switch to the one above, run:
+
+```bash
+npx @codepress/design-kit@latest init --workflow-only --force
+```
+
+It rewrites only `.github/workflows/design-kit.yml`, at the new pinned
+version, and leaves the config, the skill and `AGENTS.md` alone. When the
+config has no `watch` list, it prints the one `init` would write; paste it
+into `design-kit.config.json`, or the kit rebuilds after any commit. If you
+edited the old workflow, copy the new `check` and `cleanup` jobs, the `id:
+upload` and `retention-days: 90` on the upload step, the build job's
+`artifact-id` output and `DESIGN_KIT_MAX_AGE_DAYS` into it instead. To
+refresh the skill as well, run `init --force`, which rewrites the config too.
 
 ## Set up in your repository
 
@@ -117,14 +164,18 @@ 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
+- `design-kit.config.json`: the `watch` list, 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 check (and `workflow_dispatch`)
+  on `ubuntu-latest`. A `check` job runs `design-kit ci-check`, which skips
+  when no `watch` path changed since the newest `design-kit` artifact's
+  commit and that kit is under 75 days old; otherwise the build 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 90 days. A
+  `cleanup` job, the only one allowed to delete artifacts, then runs
+  `design-kit ci-cleanup` to delete the branch's older kits. 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
@@ -244,17 +295,34 @@ value>]` then replaces `slots`.
 ## Commands
 
 ```bash
-design-kit init            [--root dir] [--dry-run] [--force]
+design-kit init            [--root dir] [--dry-run] [--force] [--workflow-only]
 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,...]
                            [--ready name=selector] [--screenshots dir] [--timeout ms]
 design-kit kit info|find|show|compose ...   [--kit dir]
 design-kit validate        [--config f]
+design-kit ci-check        [--config f] [--since sha --kit-created iso | --no-kit]
+                           [--force] [--package spec] [--max-age-days n]
+design-kit ci-cleanup      --keep artifact-id
 design-kit setup-guide
 design-kit storybook-guide
 ```
 
+`ci-check` and `ci-cleanup` are the workflow's steps. `ci-check` finds the
+newest unexpired `design-kit` artifact on the branch (through `gh`, from
+`GITHUB_REPOSITORY` and `GITHUB_REF_NAME`, or `--repo` and `--branch`), or
+takes it from `--since` and `--kit-created`. It fetches that commit (shallow,
+no file contents) and compares the git tree or blob id of each `watch` path
+there and at `HEAD`; a missing path is a value of its own, so a deleted path
+counts as changed. It prints `build=true` or `build=false` and the reason
+(`changed: src`, `watched files unchanged since 3f2a9c1`, `refresh before
+expiry: …`, `no kit yet on this branch`, `forced …`, `an explicit package was
+given …`) and writes them to `$GITHUB_OUTPUT` and the step summary. A kit
+that cannot be looked up or fetched builds. `ci-cleanup` deletes the
+branch's kits older than `--keep` and warns about any it could not delete;
+both always exit 0 unless the config is invalid.
+
 `setup-guide` prints the agent skill for setting a kit up in a repository
 that has none, as one reviewable pull request: run `init`, decide between
 Storybook stories and page capture, wire sign-in through repository secrets,

package/package.json

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

package/schema/design-kit.config.schema.json

@@ -21,6 +21,16 @@
       "minLength": 1,
       "description": "Where captures write the kit when --out is not given."
     },
+    "watch": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "pattern": "^(?![/\\\\])(?!.*(^|/)\\.\\.(/|$))(?!.*[*?\\[])",
+        "description": "A folder or file, relative to the repository root (not to this file): no leading slash, no .., no glob."
+      },
+      "description": "The paths whose change rebuilds the kit in CI (`design-kit ci-check`), relative to the repository root. A run where none of them changed since the newest kit's commit builds nothing. Without it, any change in the repository rebuilds. `init` writes the Storybook and app folders, the workspace packages they use, global styles, this file, the lockfile and the workflow."
+    },
     "theme": { "$ref": "#/$defs/theme" },
     "stories": { "$ref": "#/$defs/stories" },
     "pages": { "$ref": "#/$defs/pages" }

package/skills/design-kit-setup/SKILL.md

@@ -28,11 +28,14 @@ npx --yes @codepress/design-kit init
 It detects Storybook and its version, the framework, the package manager, the
 dev script, Playwright and the dark-theme mechanism, then writes:
 
-- `design-kit.config.json`: the stories (when Storybook is found), a `pages`
-  skeleton with `TODO` selectors, and the theme;
-- `.github/workflows/design-kit.yml`: a daily build (and manual dispatch) that
-  skips when nothing was committed since the last kit, and uploads the
-  `design-kit` artifact for 30 days;
+- `design-kit.config.json`: the `watch` list (the UI folders, the workspace
+  packages the app uses, the lockfile and the workflow), the stories (when
+  Storybook is found), a `pages` skeleton with `TODO` selectors, and the
+  theme;
+- `.github/workflows/design-kit.yml`: a daily check (and manual dispatch) that
+  builds only when a `watch` path changed since the last kit or that kit is 75
+  days old, uploads the `design-kit` artifact for 90 days and deletes the
+  older ones. Check the `watch` list covers every folder the UI renders from;
 - `.claude/skills/design-kit/SKILL.md` and `.agents/skills/design-kit`: how
   agents fetch the kit, compose mockups and caption them;
 - one line in `AGENTS.md` (or `CLAUDE.md`) pointing at that skill.

package/src/ci.mjs

@@ -0,0 +1,463 @@
+/**
+ * The CI side of the workflow `design-kit init` writes:
+ *
+ * - `design-kit ci-check` decides whether a run builds the kit. It builds
+ *   only when a path in the config's `watch` list has changed since the
+ *   newest kit's commit (git tree and blob ids, so no file is read), when
+ *   there is no kit, when the newest kit is close to expiring, or when the
+ *   run asked for it (`--force`, `--package`).
+ * - `design-kit ci-cleanup` deletes the older kits on the branch once a new
+ *   one is uploaded. A failed delete is a warning, never a failure.
+ *
+ * Where kits are stored is behind two functions, `findNewestKit` and
+ * `deleteOlderKits` (GitHub Actions artifacts, through `gh`), so another
+ * store changes only those and the workflow's upload step.
+ */
+import { execFileSync } from "node:child_process";
+import { appendFileSync } from "node:fs";
+import { posix } from "node:path";
+
+import { CONFIG_NAME, ConfigError, loadConfig } from "./config.mjs";
+
+export const ARTIFACT = "design-kit";
+/** Rebuild a kit this old even with no UI change, so it never expires. */
+export const DEFAULT_MAX_AGE_DAYS = 75;
+/** What `watch` means when a config has none: the whole repository. */
+export const DEFAULT_WATCH = ["."];
+const DAY_MS = 86_400_000;
+const PAGES = 5;
+
+// ── storage: GitHub Actions artifacts ───────────────────────────────────────
+
+/** Runs `gh` and returns its stdout. */
+export function runGh(args, { env = process.env } = {}) {
+  return execFileSync("gh", args, {
+    encoding: "utf8",
+    env,
+    stdio: ["ignore", "pipe", "pipe"],
+    maxBuffer: 32 * 1024 * 1024,
+  });
+}
+
+/** Every `design-kit` artifact of the repository, newest first. */
+function listKits({ repo, gh }) {
+  const artifacts = [];
+  for (let page = 1; page <= PAGES; page += 1) {
+    const body = JSON.parse(
+      gh([
+        "api",
+        `repos/${repo}/actions/artifacts?name=${ARTIFACT}&per_page=100&page=${page}`,
+      ]),
+    );
+    const batch = body?.artifacts ?? [];
+    artifacts.push(...batch);
+    if (batch.length < 100) break;
+  }
+  return artifacts
+    .filter((artifact) => artifact.name === ARTIFACT)
+    .sort((a, b) => (a.created_at < b.created_at ? 1 : -1));
+}
+
+/**
+ * The newest unexpired kit on `branch`: `{id, sha, createdAt, runId}`, or
+ * null when there is none. Throws when the store cannot be read.
+ */
+export function findNewestKit({ repo, branch, gh = runGh }) {
+  const kit = listKits({ repo, gh }).find(
+    (artifact) =>
+      !artifact.expired && artifact.workflow_run?.head_branch === branch,
+  );
+  if (!kit?.workflow_run?.head_sha) return null;
+  return {
+    id: String(kit.id),
+    sha: kit.workflow_run.head_sha,
+    createdAt: kit.created_at,
+    runId: kit.workflow_run.id ? String(kit.workflow_run.id) : null,
+  };
+}
+
+/**
+ * Deletes the kits on `branch` older than the one `keep` names (an artifact
+ * id). Returns `{deleted: [ids], failed: [{id, error}], keptFound}`; never
+ * throws for a single failed delete. When the kept kit is not in the listing
+ * (not listed yet, or on another branch), nothing is deleted: "older" has
+ * nothing to be measured against.
+ */
+export function deleteOlderKits({ repo, branch, keep, gh = runGh }) {
+  const kits = listKits({ repo, gh }).filter(
+    (artifact) => artifact.workflow_run?.head_branch === branch,
+  );
+  const kept = kits.find((artifact) => String(artifact.id) === String(keep));
+  const deleted = [];
+  const failed = [];
+  if (!kept) return { deleted, failed, keptFound: false };
+  for (const artifact of kits) {
+    if (String(artifact.id) === String(keep)) continue;
+    // Only kits uploaded before the one just kept: a newer one, or one
+    // uploaded in the same instant, is never removed.
+    if (!(Date.parse(artifact.created_at) < Date.parse(kept.created_at)))
+      continue;
+    try {
+      gh([
+        "api",
+        "--method",
+        "DELETE",
+        `repos/${repo}/actions/artifacts/${artifact.id}`,
+      ]);
+      deleted.push(String(artifact.id));
+    } catch (error) {
+      failed.push({ id: String(artifact.id), error: errorText(error) });
+    }
+  }
+  return { deleted, failed, keptFound: Boolean(kept) };
+}
+
+function errorText(error) {
+  const stderr = error?.stderr ? String(error.stderr).trim() : "";
+  return (stderr || error?.message || String(error)).split("\n")[0];
+}
+
+// ── git: ids of the watched paths ───────────────────────────────────────────
+
+function git(cwd, args, env = process.env) {
+  return execFileSync("git", ["-C", cwd, ...args], {
+    encoding: "utf8",
+    env,
+    stdio: ["ignore", "pipe", "pipe"],
+    maxBuffer: 32 * 1024 * 1024,
+  });
+}
+
+/**
+ * A `watch` entry as git names it: forward slashes, `.`/`..` segments and
+ * repeated or trailing slashes resolved, "" for the repository root.
+ */
+export function normalizeWatchPath(path) {
+  const normalized = posix.normalize(String(path).replace(/\\/g, "/"));
+  return normalized.replace(/^\.\/?$/, "").replace(/\/+$/, "");
+}
+
+/**
+ * `{path: id}` for each watched path at `rev`: the git tree id of a folder,
+ * the blob id of a file, or "missing" when the path does not exist there.
+ * Each path is listed on its own (`git ls-tree <rev> -- <path>`), so
+ * overlapping entries such as `src` and `src/theme.css` cannot hide each
+ * other. A path that is absent lists nothing; a tree git cannot read throws,
+ * so the run builds instead of mistaking it for an absent path. Only trees
+ * are read, so it works in a blobless (`--filter=blob:none`) clone.
+ */
+export function watchedIds(repoDir, rev, paths) {
+  const ids = {};
+  for (const path of paths) {
+    const key = normalizeWatchPath(path);
+    if (key === "") {
+      ids[path] = git(repoDir, [
+        "rev-parse",
+        "--verify",
+        `${rev}^{tree}`,
+      ]).trim();
+      continue;
+    }
+    const out = git(repoDir, ["ls-tree", "-z", "--full-tree", rev, "--", key]);
+    let id = "missing";
+    for (const entry of out.split("\0").filter(Boolean)) {
+      const tab = entry.indexOf("\t");
+      if (entry.slice(tab + 1) === key) id = entry.slice(0, tab).split(" ")[2];
+    }
+    ids[path] = id;
+  }
+  return ids;
+}
+
+/** True when `sha` is a commit in this clone. */
+function hasCommit(repoDir, sha) {
+  try {
+    // No lazy fetch from a partial clone's remote: one shallow fetch below
+    // brings the commit and its trees together.
+    git(repoDir, ["cat-file", "-e", `${sha}^{commit}`], {
+      ...process.env,
+      GIT_NO_LAZY_FETCH: "1",
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Makes `sha` available: already here, or a shallow, blobless fetch. */
+export function ensureCommit(repoDir, sha) {
+  if (hasCommit(repoDir, sha)) return;
+  git(repoDir, [
+    "fetch",
+    "--quiet",
+    "--no-tags",
+    "--depth=1",
+    "--filter=blob:none",
+    "origin",
+    sha,
+  ]);
+  if (!hasCommit(repoDir, sha)) throw new Error(`${sha} is not a commit`);
+}
+
+// ── the decision ────────────────────────────────────────────────────────────
+
+const short = (sha) => String(sha).slice(0, 7);
+
+/**
+ * The reasons to build that need no git: `force`, an explicit package, no
+ * kit, or a kit close to expiring. Null when none applies.
+ */
+function buildWithoutComparing({
+  force,
+  packageSpec,
+  kit,
+  lookupError,
+  now,
+  maxAgeDays,
+}) {
+  if (force) return { build: true, reason: "forced (the force input is set)" };
+  if (packageSpec)
+    return {
+      build: true,
+      reason: `an explicit package was given (${packageSpec})`,
+    };
+  if (!kit)
+    return {
+      build: true,
+      reason: lookupError
+        ? `could not look up the newest kit (${lookupError}), so building`
+        : "no kit yet on this branch",
+    };
+  const ageDays = (now - Date.parse(kit.createdAt)) / DAY_MS;
+  if (!(ageDays < maxAgeDays))
+    return {
+      build: true,
+      reason: Number.isFinite(ageDays)
+        ? `refresh before expiry: the newest kit (${short(kit.sha)}) is ${Math.floor(ageDays)} days old, and the limit is ${maxAgeDays}`
+        : `refresh before expiry: the newest kit (${short(kit.sha)}) has no usable date`,
+    };
+  return null;
+}
+
+/**
+ * Whether to build, and why. Pure: every input is already looked up.
+ * `kit` is `{sha, createdAt}` or null; `before` and `after` are
+ * `watchedIds` at the kit's commit and at HEAD, unless `fetchError` says
+ * why they could not be read.
+ */
+export function decide({
+  force = false,
+  packageSpec = "",
+  kit = null,
+  lookupError,
+  now = Date.now(),
+  maxAgeDays = DEFAULT_MAX_AGE_DAYS,
+  fetchError,
+  before = {},
+  after = {},
+}) {
+  const early = buildWithoutComparing({
+    force,
+    packageSpec,
+    kit,
+    lookupError,
+    now,
+    maxAgeDays,
+  });
+  if (early) return early;
+  if (fetchError)
+    return {
+      build: true,
+      reason: `could not read the kit's commit ${short(kit.sha)} (${fetchError}), so building`,
+    };
+  const paths = [...new Set([...Object.keys(before), ...Object.keys(after)])];
+  const changed = paths.filter((path) => before[path] !== after[path]);
+  if (changed.length)
+    return { build: true, reason: `changed: ${changed.join(", ")}` };
+  return {
+    build: false,
+    reason: `watched files unchanged since ${short(kit.sha)}`,
+  };
+}
+
+/**
+ * Looks everything up and decides. `kit` given (`{sha, createdAt}`, or null
+ * for "no kit") skips the store lookup; otherwise `findKit()` is called.
+ * `head` is the commit being built (default HEAD). Returns
+ * `{build, reason, kit}`.
+ */
+export function ciCheck({
+  repoDir,
+  head = "HEAD",
+  watch = DEFAULT_WATCH,
+  force = false,
+  packageSpec = "",
+  kit,
+  findKit,
+  now = Date.now(),
+  maxAgeDays = DEFAULT_MAX_AGE_DAYS,
+}) {
+  const inputs = { force, packageSpec, now, maxAgeDays };
+  let lookupError;
+  if (kit === undefined && !force && !packageSpec) {
+    try {
+      kit = findKit();
+    } catch (error) {
+      kit = null;
+      lookupError = errorText(error);
+    }
+  }
+  kit ??= null;
+  const early = buildWithoutComparing({ ...inputs, kit, lookupError });
+  if (early) return { ...early, kit };
+  let fetchError;
+  let before;
+  let after;
+  try {
+    ensureCommit(repoDir, kit.sha);
+    before = watchedIds(repoDir, kit.sha, watch);
+    after = watchedIds(repoDir, head, watch);
+  } catch (error) {
+    fetchError = errorText(error);
+  }
+  const missing = after
+    ? Object.keys(after).filter((path) => after[path] === "missing")
+    : [];
+  return {
+    ...decide({ ...inputs, kit, before, after, fetchError }),
+    kit,
+    missing,
+  };
+}
+
+// ── the commands ────────────────────────────────────────────────────────────
+
+function maxAgeFrom(value, env) {
+  const raw = value ?? env.DESIGN_KIT_MAX_AGE_DAYS;
+  if (raw === undefined || raw === "") return DEFAULT_MAX_AGE_DAYS;
+  const days = Number(raw);
+  if (!Number.isFinite(days) || days < 0)
+    throw new ConfigError(
+      `--max-age-days (or DESIGN_KIT_MAX_AGE_DAYS) takes a number of days, got ${raw}`,
+    );
+  return days;
+}
+
+function repoAndBranch(options, env) {
+  const repo = options.repo ?? env.GITHUB_REPOSITORY;
+  const branch = options.branch ?? env.GITHUB_REF_NAME;
+  if (!repo || !branch)
+    throw new ConfigError(
+      "--repo <owner/name> and --branch <name> are needed outside GitHub Actions",
+    );
+  return { repo, branch };
+}
+
+function emit(values, env) {
+  // One line per value: a newline (from a dispatch input in the reason)
+  // must not add a second `build=` line to $GITHUB_OUTPUT.
+  const lines = Object.entries(values).map(
+    ([key, value]) => `${key}=${String(value).replace(/[\r\n]+/g, " ")}`,
+  );
+  for (const line of lines) console.log(line);
+  if (env.GITHUB_OUTPUT)
+    appendFileSync(env.GITHUB_OUTPUT, `${lines.join("\n")}\n`);
+}
+
+function summary(text, env) {
+  if (env.GITHUB_STEP_SUMMARY)
+    appendFileSync(env.GITHUB_STEP_SUMMARY, `${text}\n`);
+}
+
+/**
+ * `design-kit ci-check`: prints `build=true|false` and `reason=…` (and
+ * writes them to $GITHUB_OUTPUT and the step summary when set).
+ */
+export function ciCheckCommand(options, { env = process.env, gh, now } = {}) {
+  const config = loadConfig(options.config);
+  const watch = config.raw.watch?.length ? config.raw.watch : DEFAULT_WATCH;
+  if ((options.since === undefined) !== (options["kit-created"] === undefined))
+    throw new ConfigError("--since and --kit-created go together");
+  const kit =
+    options.since !== undefined
+      ? { sha: options.since, createdAt: options["kit-created"] }
+      : options["no-kit"]
+        ? null
+        : undefined;
+  if (kit?.createdAt && Number.isNaN(Date.parse(kit.createdAt)))
+    throw new ConfigError(
+      `--kit-created takes an ISO 8601 date, got ${kit.createdAt}`,
+    );
+  const repoDir = git(config.configDir, [
+    "rev-parse",
+    "--show-toplevel",
+  ]).trim();
+  const result = ciCheck({
+    repoDir,
+    watch,
+    force: Boolean(options.force),
+    packageSpec: options.package ?? "",
+    kit,
+    findKit: () =>
+      findNewestKit({
+        ...repoAndBranch(options, env),
+        gh: gh ?? ((args) => runGh(args, { env })),
+      }),
+    now: now ?? Date.now(),
+    maxAgeDays: maxAgeFrom(options["max-age-days"], env),
+  });
+  if (result.missing?.length)
+    console.log(
+      `::warning title=Design kit::These watch paths do not exist at this commit, so they never trigger a rebuild: ${result.missing.join(", ")}. Fix or remove them in ${CONFIG_NAME}.`,
+    );
+  emit(
+    {
+      build: String(result.build),
+      reason: result.reason,
+      "kit-sha": result.kit?.sha ?? "",
+    },
+    env,
+  );
+  summary(
+    `Design kit: ${result.build ? "building" : "nothing to build"}, ${result.reason}.`,
+    env,
+  );
+  return 0;
+}
+
+/**
+ * `design-kit ci-cleanup --keep <artifact id>`: deletes the branch's older
+ * kits. Always exits 0; each failed delete is a workflow warning.
+ */
+export function ciCleanupCommand(options, { env = process.env, gh } = {}) {
+  if (!options.keep) throw new ConfigError("--keep <artifact id> is required");
+  const { repo, branch } = repoAndBranch(options, env);
+  let result;
+  try {
+    result = deleteOlderKits({
+      repo,
+      branch,
+      keep: options.keep,
+      gh: gh ?? ((args) => runGh(args, { env })),
+    });
+  } catch (error) {
+    console.log(
+      `::warning title=Design kit::Could not list the older kits, so none were deleted: ${errorText(error)}`,
+    );
+    return 0;
+  }
+  if (!result.keptFound) {
+    console.log(
+      `::warning title=Design kit::The kit just uploaded (${options.keep}) is not listed on ${branch} yet, so no older kit was deleted. The next build deletes them.`,
+    );
+    return 0;
+  }
+  for (const { id, error } of result.failed)
+    console.log(
+      `::warning title=Design kit::Could not delete the older kit ${id}: ${error}`,
+    );
+  const text = `Design kit: deleted ${result.deleted.length} older kit${result.deleted.length === 1 ? "" : "s"} on ${branch}${result.failed.length ? `; ${result.failed.length} could not be deleted` : ""}.`;
+  console.log(text);
+  summary(text, env);
+  return 0;
+}

package/src/cli.mjs

@@ -27,7 +27,8 @@ 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]
+      [--root <dir>] [--dry-run] [--force] [--workflow-only]
+                    --workflow-only --force rewrites just the workflow
   capture stories   capture every story of a Storybook 7-9 static build
       [--config <file>] [--out <dir>] [--storybook-dir <dir>]
       [--only <id,...> | --only-file <file>] [--base <previous kit>]
@@ -39,6 +40,15 @@ const USAGE = `usage: design-kit <command> [options]
       [--kit <dir>]   default: DESIGN_KIT_DIR, the config's "out", ./design-kit
   validate          check design-kit.config.json against the v1 schema
       [--config <file>]
+  ci-check          in CI: print build=true|false and the reason. Builds
+                    when a "watch" path changed since the newest kit, there
+                    is no kit, it is DESIGN_KIT_MAX_AGE_DAYS (75) old, or
+                    --force or --package is given
+      [--config <file>] [--since <sha> --kit-created <iso> | --no-kit]
+      [--force] [--package <spec>] [--max-age-days <n>]
+      [--repo <owner/name>] [--branch <name>]
+  ci-cleanup        in CI: delete the branch's kits older than --keep
+      --keep <artifact id> [--repo <owner/name>] [--branch <name>]
   setup-guide       print the guide for setting a kit up in a repository as
                     one reviewable pull request (an agent skill)
   storybook-guide   print the guide for adding Storybook, with stories for
@@ -179,14 +189,40 @@ export async function main(argv = process.argv.slice(2), env = process.env) {
         root: "value",
         "dry-run": "flag",
         force: "flag",
+        "workflow-only": "flag",
       });
       const { init } = await import("./init.mjs");
       return init({
         root: options.root ?? ".",
         dryRun: Boolean(options["dry-run"]),
         force: Boolean(options.force),
+        workflowOnly: Boolean(options["workflow-only"]),
       });
     }
+    if (command === "ci-check") {
+      const options = parse(argv.slice(1), {
+        config: "value",
+        since: "value",
+        "kit-created": "value",
+        "no-kit": "flag",
+        force: "flag",
+        package: "value",
+        "max-age-days": "value",
+        repo: "value",
+        branch: "value",
+      });
+      const { ciCheckCommand } = await import("./ci.mjs");
+      return ciCheckCommand(options, { env });
+    }
+    if (command === "ci-cleanup") {
+      const options = parse(argv.slice(1), {
+        keep: "value",
+        repo: "value",
+        branch: "value",
+      });
+      const { ciCleanupCommand } = await import("./ci.mjs");
+      return ciCleanupCommand(options, { env });
+    }
     if (command === "setup-guide") {
       parse(argv.slice(1), {});
       process.stdout.write(readFileSync(SETUP_GUIDE, "utf8"));

package/src/init.mjs

@@ -2,9 +2,10 @@
  * `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.
+ * that rebuilds the kit when the watched UI files change and uploads it, 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. `--workflow-only` rewrites just the workflow.
  */
 import {
   existsSync,
@@ -20,6 +21,7 @@ import {
 } from "node:fs";
 import { dirname, join, relative, resolve, sep } from "node:path";
 
+import { DEFAULT_MAX_AGE_DAYS } from "./ci.mjs";
 import { CONFIG_NAME } from "./config.mjs";
 
 const PACKAGE = JSON.parse(
@@ -34,6 +36,8 @@ 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";
+/** How long a kit artifact is kept: the most a public repository allows. */
+export const RETENTION_DAYS = 90;
 
 const IGNORED_DIRS = new Set([
   "node_modules",
@@ -549,12 +553,117 @@ function posix(path) {
   return path.split(sep).join("/");
 }
 
+/** Folders at a package root that hold what the UI renders or loads. */
+const ROOT_UI_DIRS = new Set([
+  ".storybook",
+  "app",
+  "assets",
+  "components",
+  "design-tokens",
+  "lib",
+  "pages",
+  "public",
+  "src",
+  "stories",
+  "styles",
+  "theme",
+  "tokens",
+]);
+/** Global styles and tokens that can sit at the repository root. */
+const ROOT_STYLE_DIRS = new Set(["design-tokens", "styles", "theme", "tokens"]);
+const UI_CONFIG_FILE =
+  /^(tailwind|postcss|vite|next|astro|remix|svelte|nuxt|uno|panda)\.config\.[cm]?[jt]s$/;
+
+/**
+ * What to watch for one package folder: the folder itself, or, when the
+ * package is the repository root, its UI folders and config files (watching
+ * the whole root would rebuild on every commit).
+ */
+function packageWatch(dir, repoRoot) {
+  if (dir !== repoRoot) return [posix(relative(repoRoot, dir))];
+  const paths = [];
+  for (const entry of safeReaddir(dir)) {
+    if (entry.isDirectory() && ROOT_UI_DIRS.has(entry.name))
+      paths.push(entry.name);
+    else if (
+      entry.isFile() &&
+      (UI_CONFIG_FILE.test(entry.name) ||
+        entry.name === "package.json" ||
+        entry.name === "index.html")
+    )
+      paths.push(entry.name);
+  }
+  return paths.sort();
+}
+
+/** The workspace packages `dirs` depend on, directly or through each other. */
+function workspaceDependencies(dirs, found) {
+  const all = [
+    ...new Set([...workspacePackages(found.repoRoot), ...found.workspaces]),
+  ];
+  const byName = new Map();
+  for (const dir of all) {
+    const name = readJson(join(dir, "package.json"))?.name;
+    if (name && !byName.has(name)) byName.set(name, dir);
+  }
+  const seen = new Set(dirs);
+  const queue = [...dirs];
+  const dependencies = [];
+  while (queue.length) {
+    const dir = queue.shift();
+    for (const name of Object.keys(deps(readJson(join(dir, "package.json"))))) {
+      const dep = byName.get(name);
+      if (dep && !seen.has(dep)) {
+        seen.add(dep);
+        dependencies.push(dep);
+        queue.push(dep);
+      }
+    }
+  }
+  return dependencies;
+}
+
+/**
+ * The config's `watch` list: the paths, relative to the repository root,
+ * whose change rebuilds the kit. The Storybook and app folders, the
+ * workspace packages they depend on (shared UI usually lives there), global
+ * styles and tokens at the root, the config, the lockfile and the workflow.
+ */
+export function watchDefaults(found) {
+  const rel = (path) => posix(relative(found.repoRoot, path));
+  const roots = [
+    ...(found.storybook ? [found.storybook.dir] : []),
+    found.framework?.dir ?? found.project,
+  ];
+  const packages = [...new Set(roots)];
+  const paths = [];
+  for (const dir of [...packages, ...workspaceDependencies(packages, found)])
+    paths.push(...packageWatch(dir, found.repoRoot));
+  for (const entry of safeReaddir(found.repoRoot))
+    if (
+      (entry.isDirectory() && ROOT_STYLE_DIRS.has(entry.name)) ||
+      (entry.isFile() && UI_CONFIG_FILE.test(entry.name))
+    )
+      paths.push(entry.name);
+  paths.push(rel(join(found.project, CONFIG_NAME)));
+  const pm = found.packageManager;
+  if (pm.lockfile) paths.push(rel(join(pm.installDir, pm.lockfile)));
+  paths.push(WORKFLOW_PATH);
+  const unique = [...new Set(paths.filter(Boolean))];
+  // A path inside another watched folder adds nothing.
+  return unique.filter(
+    (path) =>
+      !unique.some((other) => other !== path && path.startsWith(`${other}/`)),
+  );
+}
+
 /** 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",
+    watch: watchDefaults(found),
     theme: {
       attribute: found.theme.attribute,
       dark: found.theme.dark,
@@ -634,13 +743,18 @@ export function buildWorkflow(found) {
 
   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.
+# Captures this repository's design kit: ${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, which agents
+# download to draw mockups from the app's real markup.
+#
+# It runs daily, but builds only when a path in the config's "watch" list
+# changed since the newest kit's commit, when there is no kit yet, or when
+# the newest kit is DESIGN_KIT_MAX_AGE_DAYS old, so a kit never expires
+# unreplaced. After an upload it deletes the branch's older kits.
 #
-# Written by \`design-kit init\` (${PACKAGE.name}). Edit it freely.
+# Written by \`design-kit init\` (${PACKAGE.name}); \`init --workflow-only
+# --force\` rewrites just this file. Edit it freely.
 
 on:
   schedule:
@@ -648,11 +762,11 @@ on:
   workflow_dispatch:
     inputs:
       force:
-        description: Build even when the newest kit is from this commit
+        description: Build even when no watched file changed since the newest kit
         type: boolean
         default: false
       package:
-        description: "The ${PACKAGE.name} to install, as an npm package spec (default: the pinned version below)"
+        description: "The ${PACKAGE.name} to build with, as an npm package spec (default: the pinned version below). Always builds."
         type: string
         default: ""
 
@@ -667,30 +781,46 @@ env:
   DESIGN_KIT_PACKAGE: "${PACKAGE.name}@${PACKAGE.version}"
   PLAYWRIGHT_PACKAGE: "@playwright/test@${playwrightPin()}"
   CONFIG: \${{ github.workspace }}/${at(CONFIG_NAME)}
+  # Rebuild a kit this many days old even with no UI change. Kits are kept
+  # ${RETENTION_DAYS} days (retention-days below), so this refreshes the kit before it
+  # expires.
+  DESIGN_KIT_MAX_AGE_DAYS: "${DEFAULT_MAX_AGE_DAYS}"
 
 jobs:
   check:
-    name: Any commits since the newest kit?
+    name: Did the watched files change?
     runs-on: ubuntu-latest
-    timeout-minutes: 5
+    timeout-minutes: 10
     permissions:
+      contents: read
       actions: read
     outputs:
-      build: \${{ steps.last.outputs.build }}
+      build: \${{ steps.check.outputs.build }}
     steps:
-      - id: last
+      # Only the config is checked out and no file contents are fetched: the
+      # check compares the git tree and blob ids of the watched paths at the
+      # newest kit's commit and at this one.
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 1
+          filter: blob:none
+          sparse-checkout: ${at(CONFIG_NAME)}
+          sparse-checkout-cone-mode: false
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: "22"
+
+      - id: check
         env:
           GH_TOKEN: \${{ github.token }}
           FORCE: \${{ inputs.force || 'false' }}
+          PACKAGE_INPUT: \${{ inputs.package || '' }}
         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
+          args=()
+          if [ "$FORCE" = "true" ]; then args+=(--force); fi
+          if [ -n "$PACKAGE_INPUT" ]; then args+=(--package "$PACKAGE_INPUT"); fi
+          npx --yes -p "$DESIGN_KIT_PACKAGE" design-kit ci-check --config "$CONFIG" "\${args[@]}"
 
   build:
     name: Build the design kit
@@ -698,6 +828,8 @@ jobs:
     if: needs.check.outputs.build == 'true'
     runs-on: ubuntu-latest
     timeout-minutes: 60
+    outputs:
+      artifact-id: \${{ steps.upload.outputs.artifact-id }}
     steps:
       - uses: actions/checkout@v5
         with:
@@ -745,13 +877,37 @@ ${storiesStep}
         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') != ''
+      - id: upload
+        if: hashFiles('${at("design-kit")}/manifest.json') != ''
         uses: actions/upload-artifact@v5
         with:
           name: design-kit
           path: ${at("design-kit")}
-          retention-days: 30
+          # The most a public repository allows. A private repository may
+          # raise it to 400 (and DESIGN_KIT_MAX_AGE_DAYS with it).
+          retention-days: ${RETENTION_DAYS}
           if-no-files-found: error
+
+  # Deletes this branch's older kits once the new one is uploaded. The only
+  # job that may delete artifacts; a failed delete is a warning.
+  cleanup:
+    name: Delete older kits
+    needs: build
+    if: needs.build.outputs.artifact-id != ''
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      actions: write
+    steps:
+      - uses: actions/setup-node@v5
+        with:
+          node-version: "22"
+
+      - continue-on-error: true
+        env:
+          GH_TOKEN: \${{ github.token }}
+          KEEP: \${{ needs.build.outputs.artifact-id }}
+        run: npx --yes -p "$DESIGN_KIT_PACKAGE" design-kit ci-cleanup --keep "$KEEP"
 `;
 }
 
@@ -759,19 +915,11 @@ ${storiesStep}
 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)`,
@@ -902,6 +1050,7 @@ function describe(found) {
         ? `${found.playwright.name}${found.playwright.version ? ` ${found.playwright.version}` : ""}`
         : "none (the workflow installs its own)",
     ],
+    ["Rebuilds on", watchDefaults(found).join(", ")],
     [
       "Theme",
       found.theme.evidence
@@ -942,10 +1091,10 @@ function todo(found) {
   return items;
 }
 
-function summary(found, plan, { dryRun }) {
+function summary(found, plan, { dryRun, workflowOnly, notes }) {
   const rel = (path) => posix(relative(found.repoRoot, path)) || ".";
   const lines = [
-    `design-kit init${dryRun ? " --dry-run" : ""}: ${found.project}`,
+    `design-kit init${workflowOnly ? " --workflow-only" : ""}${dryRun ? " --dry-run" : ""}: ${found.project}`,
     "",
     "Found",
   ];
@@ -968,24 +1117,58 @@ function summary(found, plan, { dryRun }) {
     lines.push(`  ${rel(write.path)}${note}`);
   }
   lines.push("", "Still to decide");
-  for (const item of todo(found)) lines.push(`  - ${item}`);
+  for (const item of notes ?? todo(found)) lines.push(`  - ${item}`);
   return lines.join("\n");
 }
 
 // ── the command ─────────────────────────────────────────────────────────────
 
+/**
+ * `init --workflow-only`: rewrites .github/workflows/design-kit.yml from
+ * this version and nothing else. The config is left alone; when it has no
+ * `watch` list, the summary prints the one init would write.
+ */
+function initWorkflowOnly(found, { dryRun, force, log }) {
+  const configFile = join(found.project, CONFIG_NAME);
+  if (!exists(configFile))
+    throw new InitError(
+      `${configFile} does not exist, so there is no kit to build yet. Run init without --workflow-only.`,
+    );
+  const path = join(found.repoRoot, WORKFLOW_PATH);
+  if (!force && exists(path))
+    throw new InitError(
+      `${WORKFLOW_PATH} already exists. Nothing was written; pass --force with --workflow-only to replace it.`,
+    );
+  const plan = {
+    writes: [{ path, kind: "file", content: buildWorkflow(found) }],
+  };
+  if (!dryRun) apply(plan.writes[0]);
+  const notes = [];
+  const raw = readJson(configFile);
+  if (!Array.isArray(raw?.watch) || !raw.watch.length)
+    notes.push(
+      `${CONFIG_NAME} has no "watch" list, so the kit rebuilds after any commit. To rebuild only when the UI changes, add:\n    "watch": ${JSON.stringify(watchDefaults(found))}`,
+    );
+  else notes.push(`Nothing: ${CONFIG_NAME} already has a "watch" list.`);
+  log(summary(found, plan, { dryRun, workflowOnly: true, notes }));
+  return 0;
+}
+
 /**
  * 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.
+ * directory), `dryRun`, `force`, `workflowOnly` (write just the workflow, for
+ * a repository set up by an older version), `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,
+  workflowOnly = false,
   log = console.log,
 } = {}) {
   const found = detectProject(root);
+  if (workflowOnly) return initWorkflowOnly(found, { dryRun, force, log });
   const plan = planInit(found);
   if (!force) {
     const config = join(found.project, CONFIG_NAME);

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

@@ -25,9 +25,10 @@ is missing from every kit until it gets one.
 ## 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:
+the `design-kit` artifact (kept 90 days; older kits are deleted). A day when
+none of the config's `watch` paths changed 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)
@@ -51,11 +52,15 @@ 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:
+code changed since, over the same `watch` paths that make the workflow
+rebuild (read from the config, so the two always agree):
 
 ```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}}
+TOP=$(git rev-parse --show-toplevel)
+git fetch -q origin "$BRANCH" &&
+  node -e 'const w = require(process.argv[1]).watch; process.stdout.write((w?.length ? w : ["."]).map((p) => `:(top)${p}`).join("\0"))' "$TOP/{{CONFIG}}" |
+  xargs -0 git log --oneline "$KIT_SHA..origin/$BRANCH" --
 ```
 
 When the list is not empty, say so on the mockup: "Kit from `<sha7>`; N UI