@codepress/design-kit 0.2.2 → 0.4.0

package/README.md

@@ -48,15 +48,21 @@ needs nothing installed beforehand. Following it, the agent:
 5. Builds the kit once, checks what it captured, and opens the pull request
    with the counts, any gaps and a screenshot of one composed screen.
 
-No Storybook yet and you want one? Add a line to the prompt:
+No Storybook yet and you want one? Ask for it on its own, before or after the
+kit:
 
 ```text
-We don't have Storybook. Add it, with stories for our shared components
-covering their default, empty, loading, error and long-text states.
+Set up Storybook in this repository, with stories for our components. Run
+`npx --yes @codepress/design-kit storybook-guide` and follow what it prints.
+Open one pull request and don't merge it.
 ```
 
-New stories are written for React. On another stack the agent captures your
-real pages and says so in the pull request.
+`storybook-guide` prints a second skill. The agent installs Storybook 9 (8 for
+older apps) without changing your React, Next.js or TypeScript versions,
+writes a stories file next to each component covering every variant and the
+empty, loading, error and long-text states, adds a tokens story, and lists
+anything it skipped, with the reason. React with Vite or Next.js is supported
+first; on another stack the agent says plainly what it did not try.
 
 Once the pull request merges, the daily workflow uploads the kit, and the
 `design-kit` skill it installed tells your agents to use it. Ask for a mockup
@@ -69,6 +75,77 @@ Mock up a Billing tab on our settings page, using the design kit.
 The agent fetches the newest kit, composes the screen from your real frame and
 components, and draws only what is new.
 
+## Keeping the kit in sync
+
+Nothing needs re-running after setup.
+
+- **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
+  `gaps.componentGlob` set, every component without one is listed in the
+  kit's `gaps.json`. The `design-kit` skill and `storybook-guide` ask agents
+  to add or update a component's story in the same pull request as the
+  component.
+- **Agents always use the newest kit.** The installed `design-kit` skill
+  fetches the newest kit each time. When UI commits have landed since that
+  kit was built, the mockup's caption says so.
+- **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 (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
 
 `design-kit init` sets a kit up as one reviewable change. Run it in the
@@ -87,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
@@ -163,7 +244,7 @@ needs no config.
 
 ### `stories`
 
-Captures every story of a Storybook 7 or 8 static build (any renderer). The
+Captures every story of a Storybook 7, 8 or 9 static build (any renderer). The
 build comes from `--storybook-dir`, `storybookDir`, or `buildCommand`, which
 writes `staticDir`; without `staticDir`, `{out}` in the command names a
 temporary folder that is removed afterwards.
@@ -214,16 +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,
@@ -231,6 +330,19 @@ build the kit once and report what it captured. An agent without the skill
 installed can run `npx --yes @codepress/design-kit setup-guide` and
 follow what it prints.
 
+`storybook-guide` prints the agent skill for a repository with no Storybook,
+or one with components that have no stories, as one reviewable pull request.
+The agent surveys the components and tokens, installs Storybook 9 (8 for
+older apps) pinned to the repository's React, Next.js and TypeScript, and fixes
+the usual first-build failures: peer-dependency conflicts, modules that throw
+on a missing environment variable, `next/font`, `next/image` and SVG imports,
+and `public/` assets. It writes one stories file per component, covering
+every variant and the empty, loading, error and long-text states, adds a
+tokens story, and lists anything it skipped, with the reason. It typechecks,
+builds Storybook and checks that `capture stories` captures it. An existing
+Storybook is extended, never re-initialised. React with Vite or Next.js is
+supported first. Run `npx --yes @codepress/design-kit storybook-guide`.
+
 `--only` re-captures just those stories (Storybook ids, with or without the
 `story:` prefix and width) and copies every other row from `--base`, byte for
 byte. The two captures share one kit folder and keep each other's files: run

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codepress/design-kit",
-  "version": "0.2.2",
+  "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" }
@@ -66,7 +76,7 @@
     "stories": {
       "type": "object",
       "additionalProperties": false,
-      "description": "`design-kit capture stories`: every story of a Storybook 7 or 8 static build.",
+      "description": "`design-kit capture stories`: every story of a Storybook 7, 8 or 9 static build.",
       "properties": {
         "root": {
           "type": "string",

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.
@@ -53,10 +56,11 @@ locally (step 3); a kit with pages has frames that new content can go into.
 **No Storybook.** Propose one of these to the person, through the Orchestrator
 when you work for one, in a short message with your recommendation:
 
-- (a) **add Storybook** with stories for the components the main screens use,
-  covering their default, empty, loading, error and long-content states. For
-  React with Vite or Next.js, `npx storybook@8 init` sets it up; write the
-  stories next to the components;
+- (a) **add Storybook** with stories for the components, covering their
+  default, empty, loading, error and long-content states: follow
+  `npx --yes @codepress/design-kit storybook-guide`, which installs a pinned
+  Storybook, writes a stories file next to each component, and adds the
+  `stories` section to the config `init` wrote;
 - (b) **capture real pages** from the dev server (step 3);
 - (c) **both**.
 
@@ -64,7 +68,7 @@ When nobody answers, do (b), plus (a) for components that are clearly reusable
 (buttons, inputs, cards, dialogs, tables that several screens share). Say in the
 pull request which you did and why.
 
-**Supported first:** Storybook 7 and 8 static builds of any renderer, page
+**Supported first:** Storybook 7, 8 and 9 static builds of any renderer, page
 capture of any URL, and new stories for React only. For another stack (Vue,
 Svelte, Angular, an older Storybook), capture pages and say honestly in the
 pull request that new stories were not written, and why.