@codepress/design-kit 0.1.1 → 0.1.3

package/README.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codepress/design-kit",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Capture your Storybook and real app pages as a static design kit, and compose self-contained mockups from it",
   "type": "module",
   "bin": {
@@ -24,6 +24,7 @@
     "bin/",
     "src/",
     "schema/",
+    "skills/",
     "README.md",
     "LICENSE"
   ],

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

@@ -0,0 +1,136 @@
+---
+name: design-kit-setup
+description: "Set a design kit up in a repository that has none, as one reviewable pull request: run `npx @codepress/design-kit init`, fill in the pages it captures, decide with the person whether to add Storybook stories or capture real pages, wire sign-in through repository secrets, build the kit once locally, and report what it captured. Use when asked to set up a design kit, add design-kit to a repository, or make mockups use the app's real components."
+---
+
+# Set up a design kit
+
+A design kit is the app's real markup for mockups: every Storybook story and
+the app's main pages, captured as static HTML with their CSS and fonts by
+`@codepress/design-kit`. Agents compose mockups from it, so the frame and the
+existing components are real and only the new parts are drawn by hand.
+
+Your job is **one reviewable pull request** that sets a kit up: a config, a
+daily GitHub Actions build that uploads the kit, and a `design-kit` skill (plus
+one line in `AGENTS.md` or `CLAUDE.md`) so the repository's agents use it. You
+never merge it.
+
+## 1. Run `init`
+
+From the repository root (or with `--root <subpackage>` when the app lives in
+one package of a monorepo):
+
+```bash
+npx --yes @codepress/design-kit init --dry-run   # what it found and would write
+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;
+- `.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.
+
+It never overwrites a file: a repository that already has
+`design-kit.config.json` exits 1 with "already set up". Stop there and tell the
+person a kit is already configured; replace it with `--force` only when they ask.
+
+Read the summary it prints. Its **Still to decide** list is your checklist for
+the rest of this skill.
+
+## 2. Storybook or pages: the judgment calls
+
+**Storybook present.** Keep the `stories` section `init` wrote and capture
+every story. Then add pages when the app has a dev server that can be reached
+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;
+- (b) **capture real pages** from the dev server (step 3);
+- (c) **both**.
+
+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
+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.
+
+## 3. Fill in the pages
+
+Replace the `TODO`s in `pages`:
+
+- `startCommand` and `waitUrl`: the command that serves the app and a URL that
+  answers once it is up. `init` guessed them from the dev script, a Playwright
+  `baseURL` or the framework's default port; check them.
+- `pages[]`: the app's main screens, usually three to eight (home or
+  dashboard, a list, a detail, settings). For each, `name` (lowercase, the
+  kit's `route:<name>` id), `path`, `ready` (a selector that shows once the
+  page has its real content, not a spinner) and `slots.main` (the selector of
+  the main content region that mockups replace, such as `main`). Add other
+  slots, such as `list` for a side list, where a screen has them.
+- `shellReady`: a selector the app's frame shows before any page content,
+  when it has one.
+- `forbidStrings`: values that must never reach the kit, such as a test
+  account's token or real customer data the pages might render. A page whose
+  markup carries one fails the whole capture, and nothing is uploaded.
+
+The workflow skips page capture while any `TODO` is left.
+
+## 4. Signing in
+
+When the pages need a signed-in user:
+
+- Use a **seeded test user** or the app's **mock mode** (a mock API, fixture
+  data, a demo flag), never a real person's account.
+- Sign in with a Playwright `storageState`, produced in CI: write a small
+  module named in `pages.auth.setup` whose default export signs in
+  (`async ({ browser, baseUrl }) => state`) with credentials it reads from the
+  environment. The workflow passes `DESIGN_KIT_USERNAME` and
+  `DESIGN_KIT_PASSWORD` from repository secrets to the page capture.
+- **Never commit a credential**, a token or a saved storage state. Say in the
+  pull request exactly which secrets the person must add (Settings → Secrets
+  and variables → Actions) and what they are for.
+
+## 5. Build once locally
+
+Before opening the pull request, build the kit once with the commands in the
+new `.claude/skills/design-kit/SKILL.md` ("When there is no kit"), into a
+scratch folder outside the repository, and check it:
+
+```bash
+node "$KIT/kit.mjs" info                 # counts: stories, pages, failures
+cat "$KIT/gaps.json"                     # what failed, and why
+node "$KIT/kit.mjs" compose --frame route:<page>@1280 --out "$TMPDIR/frame.html"
+```
+
+Open one composed frame in a browser and take a screenshot. Fix what you can
+(a wrong `ready` selector, a page that needs data) and run it again. Never
+commit the kit itself.
+
+## 6. Open the pull request
+
+The description says:
+
+- what `init` found (Storybook and version, framework, package manager);
+- what the kit captured: the number of stories and pages, and every gap with
+  its reason;
+- the screenshot of one composed frame;
+- the secrets to add, if any, and the choice made in step 2;
+- anything unsupported on this stack, said plainly.
+
+After it merges, the workflow's first scheduled or manual run uploads the
+kit, and the repository's agents start composing mockups from it.

package/src/capture-pages.mjs

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

package/src/cli.mjs

@@ -11,8 +11,17 @@ const VERSION = JSON.parse(
   readFileSync(new URL("../package.json", import.meta.url), "utf8"),
 ).version;
 
+/** The `design-kit-setup` skill, printed by `design-kit setup-guide`. */
+const SETUP_GUIDE = new URL(
+  "../skills/design-kit-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
       [--config <file>] [--out <dir>] [--storybook-dir <dir>]
       [--only <id,...> | --only-file <file>] [--base <previous kit>]
@@ -24,10 +33,13 @@ 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>]
+  setup-guide       print the guide for setting a kit up in a repository 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
-not run, 2 a config or usage error.`;
+not run (or init found the repository already set up), 2 a config or usage
+error.`;
 
 function parse(argv, spec) {
   const options = {};
@@ -153,6 +165,24 @@ export async function main(argv = process.argv.slice(2), env = process.env) {
       return 0;
     }
     if (command === "kit") return await kitCommand(argv.slice(1), env);
+    if (command === "init") {
+      const options = parse(argv.slice(1), {
+        root: "value",
+        "dry-run": "flag",
+        force: "flag",
+      });
+      const { init } = await import("./init.mjs");
+      return init({
+        root: options.root ?? ".",
+        dryRun: Boolean(options["dry-run"]),
+        force: Boolean(options.force),
+      });
+    }
+    if (command === "setup-guide") {
+      parse(argv.slice(1), {});
+      process.stdout.write(readFileSync(SETUP_GUIDE, "utf8"));
+      return 0;
+    }
     if (command === "validate") {
       const options = parse(argv.slice(1), { config: "value" });
       const config = loadConfig(options.config);