@codepress/design-kit 0.2.1 → 0.3.0

package/README.md

@@ -19,6 +19,86 @@ 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 it up with your agent
+
+The quickest way in is to let your coding agent do the whole setup. Paste this
+into Claude Code, Codex, Cursor or any agent that can run commands in your
+repository:
+
+```text
+Set up a design kit in this repository. Run
+`npx --yes @codepress/design-kit setup-guide` and follow what it prints.
+Open one pull request and don't merge it.
+```
+
+`setup-guide` prints the setup skill that ships in this package, so the agent
+needs nothing installed beforehand. Following it, the agent:
+
+1. Runs `init`, which detects your stack and writes the config, the daily
+   workflow and the agent skill (see [Set up in your repository](#set-up-in-your-repository)).
+2. Fills in the pages to capture: the command that starts your app, and three
+   to eight main screens, each with a selector that shows when it has loaded.
+3. Decides between Storybook stories and real pages. With Storybook, it
+   captures every story. Without it, it asks you whether to add Storybook,
+   capture your real pages, or both. When nobody answers, it captures pages and
+   writes stories for the components several screens share.
+4. Wires sign-in, when your pages need one, through a seeded test user and the
+   repository secrets `DESIGN_KIT_USERNAME` and `DESIGN_KIT_PASSWORD`. It never
+   writes a credential; the pull request says which secrets to add.
+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? Ask for it on its own, before or after the
+kit:
+
+```text
+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.
+```
+
+`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
+the way you would ask a designer:
+
+```text
+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.** 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 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.
+
 ## Set up in your repository
 
 `design-kit init` sets a kit up as one reviewable change. Run it in the
@@ -113,7 +193,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.
@@ -172,15 +252,29 @@ design-kit capture pages   [--config f] [--out dir] [--base-url url] [--only nam
 design-kit kit info|find|show|compose ...   [--kit dir]
 design-kit validate        [--config f]
 design-kit setup-guide
+design-kit storybook-guide
 ```
 
 `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,
 build the kit once and report what it captured. An agent without the skill
-installed can run `npx --yes @codepress/design-kit@0.1.3 setup-guide` and
+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.1",
+  "version": "0.3.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

@@ -66,7 +66,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

@@ -53,10 +53,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 +65,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.

package/skills/storybook-setup/SKILL.md

@@ -0,0 +1,389 @@
+---
+name: storybook-setup
+description: "Add Storybook to a repository, or extend the one it has, with a stories file for every existing component and a tokens story, as one reviewable pull request: survey the components and tokens, install a pinned Storybook that matches the repo's React, Next and TypeScript, fix the usual first-build failures, write stories for every variant and state, typecheck, build, and check the stories capture in a design kit. Use when asked to set up Storybook, add Storybook, add stories for our components, backfill missing stories, or build a component catalog."
+---
+
+# Set up Storybook with stories for your components
+
+Your job is **one reviewable pull request** that gives this repository a
+working Storybook with a stories file for every component it already has,
+plus a tokens story, so people can browse the library and a design kit
+(`@codepress/design-kit`) can capture it. You never merge it.
+
+Run the steps in order. The survey comes first because the most common
+failure is a Storybook that ignores what the repository already has: the wrong
+folders, no styles, a second Storybook next to the first.
+
+Supported first: **React with Vite or Next.js.** On another renderer (Vue,
+Svelte, Angular, web components) you may still install Storybook and write
+stories under the same rules, but say plainly in the pull request that this
+guide has not been tried on that stack.
+
+## 1. Survey the repository
+
+A bounded read, so you extend what exists instead of competing with it:
+
+- **Stack and versions.** Read `react`, `react-dom`, `next`, `typescript`,
+  `vite` and the Node version (`engines`, `.nvmrc`, `.node-version`; when
+  none is recorded, the version its CI workflows use) from `package.json` and
+  the lockfile. In a monorepo, find the package that holds
+  the components; Storybook goes there.
+- **Package manager.** Use the one the repository uses: the `packageManager`
+  field, or the lockfile (`pnpm-lock.yaml` pnpm, `yarn.lock` yarn,
+  `bun.lock`/`bun.lockb` bun, `package-lock.json` npm). Never add a second
+  lockfile.
+- **The component library: every folder, not just `ui/`.** Components live in
+  `components/`, `ui/`, `features/*/components/`, `app/**/_components/`,
+  `src/shared/`, workspace packages and more. List every file that exports a
+  component that renders something, and note the conventions: file naming,
+  default or named exports, how props are typed.
+- **The token layer.** CSS custom properties (`:root { --… }`), a Tailwind
+  theme (`tailwind.config.*`, or `@theme` in CSS for Tailwind 4), a theme
+  object for a CSS-in-JS `ThemeProvider`, or a design-tokens file.
+- **The global stylesheet and providers.** What the app's entry imports
+  (`main.tsx`, `app/layout.tsx`, `pages/_app.tsx`): global CSS, fonts, and
+  providers components need to render (theme, router, i18n, data clients).
+- **An existing Storybook.** `.storybook/`, `*.stories.*` files, `storybook`
+  or `@storybook/*` dependencies, a `storybook` script. **If Storybook already
+  exists, extend it: never run `storybook init` again** and never upgrade it
+  in this pull request (one older than Storybook 7 cannot be captured into a
+  design kit; say so). Match its story format exactly (CSF version, typing,
+  decorators, titles), keep its stories, and add stories only where they are
+  missing. A component with a stories file that lacks states gets those
+  states added to that file, never a second file.
+- **A design kit.** A `design-kit.config.json` means stories will be captured
+  into a kit; step 6 checks they are.
+
+Write the survey as one short paragraph (it goes in the pull request) before
+you change anything.
+
+## 2. Install Storybook (only when there is none)
+
+**Pick the version.** Use **Storybook 9** (`storybook@9`): it is the newest
+major that `design-kit capture stories` is checked against, and it supports
+Next.js 14.1 through 16. Never use `storybook@latest`. Use **Storybook 8**
+(`storybook@8`) instead when the app is below Storybook 9's floors: Node 20,
+Vite 5, Next.js 14.1 or TypeScript 4.9. Check a framework's peer ranges with
+`npm view @storybook/<framework>@9 peerDependencies`.
+
+**Pick the builder deliberately, and record the choice for the pull request.**
+
+- Vite app: `@storybook/react-vite`.
+- Next.js app: `@storybook/nextjs` (webpack) is the default and handles
+  `next/font`, `next/image`, `next/navigation` and the app's PostCSS and
+  Tailwind setup. `@storybook/nextjs-vite` is faster and fits when the app
+  has no custom `webpack()` in `next.config.*` that its components depend on
+  (SVGR, raw loaders, aliases). When unsure, take `@storybook/nextjs`.
+
+**Run init with the repository's package manager**, in the package that holds
+the components:
+
+```bash
+pnpm dlx storybook@9 init --yes --no-dev --disable-telemetry --features docs
+# npm: npx --yes storybook@9 init ...   yarn: yarn dlx storybook@9 init ...
+# bun: bunx storybook@9 init ...
+# add --type nextjs, or --builder vite, when init detects the wrong one
+```
+
+`--features docs` keeps init from adding its test-runner setup; step 3
+removes docs (and the onboarding addon init adds anyway) unless the person
+asked for docs pages. Ignore init's banner telling you to cancel and use
+`@latest`: the pin is deliberate.
+
+**Then check what init changed: `git diff package.json`.**
+
+- Only Storybook packages may be added (`storybook`, `@storybook/*`, and
+  `eslint-plugin-storybook` when the repository uses ESLint). All of
+  them must be on the **same exact version**; write it without a `^` or `~`
+  range.
+- `react`, `react-dom`, `next`, `typescript`, `vite` and every other existing
+  dependency must be unchanged. **Never downgrade or upgrade the app** to fit
+  Storybook; choose the Storybook version that fits the app.
+- A `storybook` and a `build-storybook` script are fine, and so are the
+  `storybook-static` and `*storybook.log` lines init adds to `.gitignore`.
+
+## 3. Configure it
+
+Keep the configuration small and make it render the components as the app
+does. When Storybook already existed, change its configuration only where the
+stories need it to render and build (styles, providers, env placeholders,
+loaders, `staticDirs`), and keep its addons as they are.
+
+- **Addons.** Keep only what init added for the framework itself. Remove the
+  onboarding addon (`@storybook/addon-onboarding`) and its package, and
+  delete init's example stories folder (`stories/` or `src/stories/`, with
+  its Button, Header and Page examples). Remove `@storybook/addon-docs` (from
+  `addons` and `package.json`), any `tags: ["autodocs"]` and the `*.mdx`
+  glob unless the person asked for docs pages. Add no other addons. Set
+  `core: { disableTelemetry: true }` in `main.*` so builds stay quiet (for
+  builds you run against an existing Storybook, set
+  `STORYBOOK_DISABLE_TELEMETRY=1` instead).
+- **Story globs.** Point `stories` in `.storybook/main.*` at the real
+  component folders from the survey, for example
+  `["../src/**/*.stories.@(ts|tsx)"]`, or one entry per folder or package.
+- **Styles and tokens.** Import the global stylesheet or token layer in
+  `.storybook/preview.*` (`import "../src/styles/globals.css";`). With
+  Tailwind 3, make sure its `content` globs cover the stories files too. If
+  the app sets fonts or a theme class in its layout, reproduce that with a
+  decorator in `preview.*` (rename init's `preview.ts` to `preview.tsx` for
+  JSX). Wrap stories in the providers components need, the same way the app
+  does. **An unstyled Storybook is worse than none**: check one built story
+  actually looks like the app.
+- **Landing page.** Land the sidebar on a real story, not a docs page. The
+  tokens story from step 4 works well: in `preview.*`, set
+  `parameters.options.storySort` to `{ order: ["Foundations", "*"] }`.
+
+**Fix the first build's failures yourself.** These four hit almost every
+fresh Storybook; fix them rather than report them:
+
+1. **Peer-dependency conflicts.** Put every Storybook package on one exact
+   version, and pick the Storybook major whose peer ranges include the app's
+   React, Next and TypeScript (step 2). If init's own install fails, re-run
+   it with `--skip-install` and install with the repository's package manager.
+   Drop an addon that conflicts rather than force it. Never use `--force`,
+   and never change the app's versions. If a conflict is only in a transitive
+   Storybook dependency, an `overrides` (npm), `resolutions` (yarn) or
+   `pnpm.overrides` entry for that one package is acceptable; say so in the
+   pull request.
+2. **Modules that throw at import on a missing environment variable**, for
+   example a config module that throws when `NEXT_PUBLIC_API_URL` or
+   `VITE_API_URL` is unset. Give Storybook placeholder values. **Never edit
+   the app's own validation.** Bundlers inline these variables at build time,
+   so pass them through Storybook's `env` option in `.storybook/main.*`, which
+   reaches `process.env` and `import.meta.env` in both the webpack and Vite
+   builders. Setting `process.env` at the top of `main.*` does not: the
+   webpack builder replaces `process.env` in the bundle.
+
+   ```ts
+   // Storybook only: placeholders so modules that validate env at import
+   // time load. Never real values.
+   env: (config = {}) => ({
+     ...config,
+     NEXT_PUBLIC_API_URL: config.NEXT_PUBLIC_API_URL ?? "https://api.example.invalid",
+   }),
+   ```
+
+   Never commit a real key, and never copy the app's `.env` files.
+
+3. **`next/font`, `next/image` and SVGR imports.** Keep a Next.js framework
+   (`@storybook/nextjs` or `@storybook/nextjs-vite`), which handles
+   `next/font` and `next/image`. Components that use `next/navigation` need
+   `parameters: { nextjs: { appDirectory: true } }` in `preview.*`. A font
+   the app's layout applies (`className={inter.variable}` on `<html>`) needs
+   the same class in a `preview.*` decorator. With `next/font/google` the
+   font files load from Google when a story is viewed, so a captured kit
+   falls back to the system font; say so in the pull request
+   (`next/font/local` fonts are served by Storybook and captured). Storybook
+   does not run the app's custom `webpack()` from `next.config.*`, so an SVG
+   imported as a component (`import Logo from "./logo.svg"`) needs the loader
+   added in `webpackFinal`, the app's own `@svgr/webpack`:
+
+   ```ts
+   webpackFinal: async (config) => {
+     const rules = config.module?.rules ?? [];
+     for (const rule of rules)
+       if (rule && typeof rule === "object" && rule.test instanceof RegExp && rule.test.test(".svg"))
+         rule.exclude = /\.svg$/i;
+     rules.push({ test: /\.svg$/i, use: ["@svgr/webpack"] });
+     return config;
+   },
+   ```
+
+   With a Vite builder, the app's `vite.config.*` plugins (such as
+   `vite-plugin-svgr`) are merged in; add the plugin or alias in `viteFinal`
+   only when the app configures it somewhere Storybook does not read.
+
+4. **`public/` assets.** Images and fonts the components load by absolute
+   path (`/logo.svg`) 404 until `.storybook/main.*` has
+   `staticDirs: ["../public"]` (the path to the app's public folder).
+
+## 4. Write the stories
+
+**One stories file per component, next to the component**, named the way
+the repository names files (`Button.tsx` and `Button.stories.tsx`). Use CSF 3
+in the repository's typing style, for example:
+
+```tsx
+import type { Meta, StoryObj } from "@storybook/react-vite"; // or @storybook/nextjs, @storybook/nextjs-vite; @storybook/react on Storybook 8
+import { Button } from "./Button";
+
+const meta = {
+  component: Button,
+  args: { children: "Save" },
+} satisfies Meta<typeof Button>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Primary: Story = {};
+export const Secondary: Story = { args: { variant: "secondary" } };
+```
+
+Each file covers, where it applies:
+
+- **the default**, and **every variant and every size** the props allow;
+- **hover, focus and disabled** for anything interactive. Disabled is a prop.
+  Focus is a `play` function that focuses the element
+  (`play: async ({ canvasElement }) => canvasElement.querySelector("button")?.focus()`).
+  Hover that the component drives itself (a tooltip, a menu) is a `play`
+  function too. A pure CSS `:hover` cannot be shown without a pseudo-state
+  addon, so say so in the coverage note instead of adding one;
+- **empty, loading and error** states for anything that shows data or
+  results;
+- **long text or overflow** for anything that holds text: a long label, a
+  long unbroken word or address, many items.
+
+Name state stories so they do not shadow globals: `ErrorState` with
+`name: "Error"`, never `export const Error`. A captured kit is static HTML, so
+focus rings and other live states show in Storybook but not in the kit.
+
+Use made-up fixture data (`example.com` addresses, invented names), never
+real customer data. Write stories through the component's props; do not
+refactor the app to make a state reachable. A state no prop can reach is
+skipped for cause and listed.
+
+**Add a tokens (foundations) story**, for example
+`src/foundations/Tokens.stories.tsx` with the title `Foundations/Tokens`.
+It renders the design language from the token layer the survey found: the
+palette as labelled swatches (`background: var(--color-primary)`, or Tailwind
+classes), the type scale (each size with its name), and the spacing ramp
+(bars of each width). Radii and shadows can go in too. List the token names
+from the token source, so a new token is one line.
+
+**"Every component" means the whole catalog**: the shared primitives and
+the composites and feature components (lists, panels, cards, headers,
+forms). Skip a component **only for cause**: it cannot render apart from
+live data (it fetches on its own and has no way to pass data in), it is
+deprecated, or it is an internal detail of another component that is
+already covered. Route files (`page.tsx`, `layout.tsx`) and the app root are
+screens, not catalog components: give one a story when it renders from props
+alone, and otherwise list it as skipped. List every skip, with its reason, in
+the pull request. A large backfill may be split into several pull requests by
+component family; say which family each covers and what is left. Silently
+leaving components out is not allowed.
+
+While you read the screens, note **inline UI that should become shared
+components**: the same markup repeated across pages. Name each one under
+"Recommended next" in the pull request. Do not extract it in this pull
+request.
+
+## 5. Typecheck, then build
+
+1. **Typecheck first.** It is cheaper than a build, and it catches story type
+   errors that `storybook build` lets through. Run the repository's own
+   typecheck (`pnpm typecheck`, `pnpm exec tsc --noEmit`, `tsc -b`). Check
+   that its `include` covers the stories files and `.storybook/`. TypeScript
+   skips dot-folders in wildcards, so name the files: add
+   `".storybook/*.ts", ".storybook/*.tsx"` to the `include` the typecheck
+   uses. Fix every error.
+2. **Build.** Run `storybook build` with the repository's package manager
+   (`pnpm exec storybook build --quiet`, `npx storybook build --quiet`). Fix
+   every error and warning that points at a story or the config. Then check
+   `storybook-static/index.json`: its story entries should match what you
+   wrote, and none of init's examples should be left.
+3. Run the repository's lint and its other pull request checks that the
+   change touches (ESLint on the stories, a format check), and fix what this
+   change broke.
+
+## 6. Check the design kit captures it
+
+`design-kit capture stories` renders every story in a headless browser, so it
+also proves each story renders without throwing. Write the kit to a scratch
+folder **outside the repository**, never into it.
+
+- **With a `design-kit.config.json`:** give it a `stories` section if it has
+  none:
+
+  ```json
+  "stories": {
+    "root": ".",
+    "buildCommand": "pnpm exec storybook build --quiet -o storybook-static",
+    "staticDir": "storybook-static",
+    "gaps": { "componentGlob": "src/**/[A-Z]*.{tsx,jsx}" }
+  }
+  ```
+
+  (`root` is the folder holding `.storybook/`, relative to the config; use
+  the repository's package manager in `buildCommand`.) If the repository's
+  `.github/workflows/design-kit.yml` and `.claude/skills/design-kit/SKILL.md`
+  were written before Storybook existed, they skip stories too. To update
+  them, copy the repository (without `node_modules`) to a scratch folder,
+  run `npx --yes @codepress/design-kit init --force` there, and port only
+  the Storybook parts of those two files back: the "Build Storybook and
+  capture stories" step and the stories capture line. Then run, from the
+  folder that holds `design-kit.config.json`:
+
+  ```bash
+  npx --yes @codepress/design-kit capture stories --out "$TMPDIR/design-kit-check"
+  ```
+
+- **Without one:** check anyway with a scratch config outside the repository:
+
+  ```bash
+  cat > "$TMPDIR/design-kit-check.json" <<EOF
+  {"version": 1, "stories": {"root": "$PWD", "storybookDir": "$PWD/storybook-static",
+   "gaps": {"componentGlob": "src/**/[A-Z]*.{tsx,jsx}"}}}
+  EOF
+  npx --yes @codepress/design-kit capture stories --config "$TMPDIR/design-kit-check.json" --out "$TMPDIR/design-kit-check"
+  ```
+
+  Capture needs Playwright and Chromium. When the repository has neither,
+  run `npx --yes -p @playwright/test playwright install chromium`, then
+  `npx --yes -p @codepress/design-kit -p @playwright/test design-kit capture stories ...`;
+  install nothing into the repository for it.
+
+Capture what you just built: the `buildCommand` rebuilds Storybook, and with
+a `storybookDir` rebuild first, because a stale build hides missing stories.
+Read what it printed (`stories N, ... failed M`) and
+`$TMPDIR/design-kit-check/gaps.json`:
+
+- a **failed story** (it threw, or never rendered) is a bug in the story or
+  the config: fix it and capture again;
+- a **`no story`** row names a component file with no stories file: write
+  one, or make sure it is in your skip list with its reason. Its path is
+  relative to the config file's folder.
+
+Aim for zero failures and every `no story` row explained. The files in
+`html/` are bare markup without CSS; to look at one story styled, find its id
+and compose it into a page, then open that page in a browser:
+
+```bash
+KIT="$TMPDIR/design-kit-check"
+node "$KIT/kit.mjs" --kit "$KIT" find <component name>   # ids like story:<storybook-id>@1280
+node "$KIT/kit.mjs" --kit "$KIT" compose --frame <id> --out "$TMPDIR/story.html"
+```
+
+Check it looks like the app, and take a screenshot for the pull request.
+
+## 7. Open the pull request
+
+One pull request; never merge it. When the survey and the checks found
+nothing missing (Storybook builds, every component has its stories, the
+capture has no failures and no unexplained `no story` rows), open no pull
+request: report that proof instead. Otherwise the description says:
+
+- **The survey**: where the components and tokens live, and whether
+  Storybook existed (extended, not re-initialised).
+- **Versions and builder**: the Storybook version and why (9, or 8 because of
+  which floor), the framework package and why, and that React, Next and
+  TypeScript are unchanged.
+- **First-build fixes**: each one you made (env placeholders, loaders,
+  `staticDirs`, overrides) and why.
+- **Coverage**: the components covered, counted per folder ("14 of 15 in
+  `src/components`"), with the states each covers, and the tokens story.
+- **Skipped**: every component or state left out, each with its reason.
+- **Proof**: the typecheck and `storybook build` results, the capture's
+  story count, failures and `gaps.json` rows, and the screenshot.
+- **Recommended next**: inline UI that should become shared components, and,
+  when the repository has no design kit yet, that
+  `npx --yes @codepress/design-kit setup-guide` sets one up.
+- **Not tried**: anything this guide does not cover on this stack, said
+  plainly.
+
+Never commit `storybook-static/`, a captured kit, or a real secret.
+
+## Keeping stories current
+
+After this pull request, when you add a component or change what one
+renders, add or update its story in the same pull request, covering the
+states in step 4, so the next design kit captures it. Say in the pull request
+which stories you added or changed.

package/src/capture-stories.mjs

@@ -1,5 +1,5 @@
 /**
- * `design-kit capture stories`: every story of a Storybook 7/8 static build
+ * `design-kit capture stories`: every story of a Storybook 7, 8 or 9 static build
  * rendered to static HTML, the CSS the preview loaded, the fonts, an index
  * and kit.mjs.
  *

package/src/cli.mjs

@@ -17,12 +17,18 @@ const SETUP_GUIDE = new URL(
   import.meta.url,
 );
 
+/** The `storybook-setup` skill, printed by `design-kit storybook-guide`. */
+const STORYBOOK_GUIDE = new URL(
+  "../skills/storybook-setup/SKILL.md",
+  import.meta.url,
+);
+
 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
+  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>]
   capture pages     capture the configured pages of a running app
@@ -35,6 +41,9 @@ const USAGE = `usage: design-kit <command> [options]
       [--config <file>]
   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
+                    every existing component, as one reviewable pull request
+                    (an agent skill)
 
 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
@@ -183,6 +192,11 @@ export async function main(argv = process.argv.slice(2), env = process.env) {
       process.stdout.write(readFileSync(SETUP_GUIDE, "utf8"));
       return 0;
     }
+    if (command === "storybook-guide") {
+      parse(argv.slice(1), {});
+      process.stdout.write(readFileSync(STORYBOOK_GUIDE, "utf8"));
+      return 0;
+    }
     if (command === "validate") {
       const options = parse(argv.slice(1), { config: "value" });
       const config = loadConfig(options.config);

package/src/init.mjs

@@ -916,11 +916,11 @@ function todo(found) {
   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.",
+      "No Storybook: the config captures pages only. Decide whether to add Storybook with stories for the components the main screens use (`npx --yes @codepress/design-kit storybook-guide` prints a guide for that), capture real pages, or both.",
     );
-  else if (sb.major && (sb.major < 7 || sb.major > 8))
+  else if (sb.major && (sb.major < 7 || sb.major > 9))
     items.push(
-      `Storybook ${sb.version}: captures are supported for Storybook 7 and 8 static builds; check that \`capture stories\` works, or use page capture.`,
+      `Storybook ${sb.version}: captures are supported for Storybook 7, 8 and 9 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.`,

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

@@ -16,6 +16,12 @@ 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.
 
+When this repository has Storybook and you add a component or change what
+one renders, add or update its story in the same pull request, covering its
+default, every variant and size, and the empty, loading, error and long-text
+states that apply, so the next kit captures it. A component without a story
+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