@boopkit/cap-web 0.5.6 → 0.5.8

package/README.md

@@ -17,6 +17,7 @@ Copied into your project on install:
 - `src/controllers/pages.ts` — example page controllers (`home`, `about`)
 - `src/routes/pages.ts` — Express router mounting the example pages
 - `reference/web-ui.ref.md` — reference doc describing the UI conventions
+- `scripts/ux-eval-capture.ts` — Playwright page capture the UX workflows use for screenshots, run as `npm run ux:capture`
 
 ### Scripts added to `package.json`
 
@@ -24,6 +25,7 @@ Copied into your project on install:
 |--------|---------|
 | `tailwind:build` | `npx @tailwindcss/cli -i styles/styles.css -o public/css/style.css --minify` |
 | `tailwind:watch` | `npx @tailwindcss/cli -i styles/styles.css -o public/css/style.css --watch` |
+| `ux:capture` | `tsx scripts/ux-eval-capture.ts` — `npm run ux:capture -- <path> <label>` writes `tmp/ux-eval/<label>.png` |
 
 ### Server hooks
 
@@ -53,6 +55,8 @@ Order numbers are the `preRoutes` phase ordering; other capabilities slot themse
 
 Run `npm run tailwind:build` once after install to compile `styles/styles.css` into `public/css/style.css`. `boop status` reminds you of this.
 
+Before the first UX capture, run `npx playwright install chromium` once to fetch the browser binary.
+
 ## Requirements
 
 **Other capabilities:** none — `cap-web` is self-contained.
@@ -62,6 +66,7 @@ Run `npm run tailwind:build` once after install to compile `styles/styles.css` i
 - `express-handlebars` — view engine binding
 - `tailwindcss` — utility-first CSS framework
 - `@tailwindcss/cli` (devDependency) — CSS compilation
+- `playwright` and `tsx` (devDependencies) — the UX capture script
 
 **Peer dependencies** (already provided by the `web-app` kernel):
 
@@ -69,7 +74,7 @@ Run `npm run tailwind:build` once after install to compile `styles/styles.css` i
 - `express-handlebars >=7.0.0`
 - `handlebars >=4.0.0`
 
-**Environment variables:** none required. `NODE_ENV=production` enables a 1-day cache on static assets; otherwise caching is disabled.
+**Environment variables:** none required. `NODE_ENV=production` enables a 1-day cache on static assets; otherwise caching is disabled. The UX capture script reads three optional settings: `BASE_URL` (the origin to capture, default `http://localhost:3000`), and `UX_EVAL_AUTH_COOKIE_NAME` with `UX_EVAL_AUTH_COOKIE_VALUE` (an auth cookie for authenticated pages).
 
 ## Usage
 

package/capability.json

@@ -10,7 +10,9 @@
   ],
   "devDependencies": [
     "@tailwindcss/cli@^4",
-    "@types/express-handlebars@^6"
+    "@types/express-handlebars@^6",
+    "playwright@^1.60.0",
+    "tsx@^4.0.0"
   ],
   "files": [
     "views/",
@@ -19,10 +21,16 @@
     "src/controllers/pages.ts",
     "src/routes/pages.ts",
     "tailwind.config.ts",
-    "reference/web-ui.ref.md"
+    "reference/web-ui.ref.md",
+    "scripts/ux-eval-capture.ts"
   ],
   "skills": [
-    "boop-web-web-ui-design"
+    "boop-web-web-ui-design",
+    "boop-web-css",
+    "boop-web-testing",
+    "boop-web-website-dev-workflow",
+    "boop-web-design-handoff-workflow",
+    "boop-web-design-handoff-bundle"
   ],
   "scripts": {
     "tailwind:build": {
@@ -32,12 +40,25 @@
     "tailwind:watch": {
       "cmd": "npx @tailwindcss/cli -i styles/styles.css -o public/css/style.css --watch",
       "description": "Watch for changes and rebuild Tailwind CSS"
+    },
+    "ux:capture": {
+      "cmd": "tsx scripts/ux-eval-capture.ts",
+      "description": "Screenshot a page for the UX workflows: npm run ux:capture -- <path> <label> writes tmp/ux-eval/<label>.png"
     }
   },
+  "env": [
+    { "name": "BASE_URL", "description": "Base origin the UX capture script renders against" },
+    { "name": "UX_EVAL_AUTH_COOKIE_NAME", "description": "Name of an auth cookie to inject for authenticated UX captures (cap-users uses 'auth_id')" },
+    { "name": "UX_EVAL_AUTH_COOKIE_VALUE", "description": "Value (session token) for the auth cookie used in UX captures" }
+  ],
   "postInstall": {
     "steps": [
-      "Build CSS for the first time: npm run tailwind:build"
-    ]
+      "Build CSS for the first time: npm run tailwind:build",
+      "Install the Playwright browser binary once, for the UX capture script: npx playwright install chromium",
+      "Capture a page: npm run ux:capture -- <path> <label> (writes tmp/ux-eval/<label>.png; needs the dev server running)",
+      "For authenticated pages, set UX_EVAL_AUTH_COOKIE_NAME + UX_EVAL_AUTH_COOKIE_VALUE, or wire the cap-users opt-in block documented in the script header"
+    ],
+    "verify": "npm run ux:capture -- / baseline"
   },
   "hooks": [
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boopkit/cap-web",
-  "version": "0.5.6",
+  "version": "0.5.8",
   "description": "Express view engine configuration, Handlebars helpers, and static asset middleware",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/scaffold/reference/web-ui.ref.md

@@ -2,7 +2,7 @@
 
 How this project renders pages: Handlebars templates, Tailwind CSS, static assets, and the request pipeline.
 
-**Related skills**: [design.web-ui-design.skill.md](../skills/design.web-ui-design.skill.md)
+**Related skills**: [boop-web-web-ui-design](../skills/boop-web-web-ui-design/SKILL.md) for pages, templates and markup; [boop-web-css](../skills/boop-web-css/SKILL.md) for class names and stylesheet rules
 
 ---
 
@@ -29,18 +29,31 @@ Handlebars via `express-handlebars`. Templates in `views/`, layouts in `views/la
 
 ### Helpers
 
-~130 helpers registered from `handlebars-helpers` (comparison, string, math, array). Custom helpers from `@boopkit/cap-web`:
+About 130 helpers are registered from [`handlebars-helpers`](https://github.com/helpers/handlebars-helpers).
+The most useful:
+
+| Kind | Helpers |
+|------|---------|
+| Comparison | `gt`, `lt`, `gte`, `lte`, `eq`, `is`, `not`, `compare` |
+| Logical | `and`, `or`, `not` |
+| String | `capitalize`, `trim`, `replace`, `startsWith`, `contains` |
+| Array | `first`, `last`, `sort`, `forEach`, `join` |
+| Math | `add`, `subtract`, `multiply`, `divide`, `ceil`, `floor`, `round` |
+
+Custom helpers from `@boopkit/cap-web`:
 
 | Helper | Purpose |
 |--------|---------|
-| `json` | JSON stringify with formatting |
-| `truncate` | Truncate string with ellipsis |
-| `urlencode` | Percent-encode a value for a query parameter: `href="/signup?next={{urlencode next}}"`. Handlebars escapes for HTML, not for a URL, so a value interpolated straight into a query string is truncated at its first `&`. |
-| `fmt_dollars` | Currency formatting |
-| `fmt_percent` | Percentage formatting |
-| `fmt_date` | Human-readable date (e.g., "March 28, 2026") |
-| `markdown` | Render markdown to HTML |
-| `icon` | Inline SVG from heroicons: `{{icon "user" "24/outline"}}` with optional `class=` |
+| `fmt_dollars` | Currency: `{{fmt_dollars 1234}}` → `$1,234`. An optional `sigfigs` rounds for data visualisation: `{{fmt_dollars 12345 sigfigs=4}}` → `$12,350`. |
+| `fmt_percent` | Percentage: `{{fmt_percent 45}}` → `45%` |
+| `fmt_date` | Human-readable date: `{{fmt_date createdAt}}` → `March 28, 2026` |
+| `markdown` | Render markdown to HTML: `{{markdown text}}` or `{{#markdown}}...{{/markdown}}` |
+| `icon` | Inline SVG from heroicons: `{{icon "user" "24/outline"}}`, with an optional class: `{{icon "check" "24/solid" class="icon done"}}`. Styles are `24/outline`, `24/solid`, `20/solid` and `16/solid`. Icons are read from `node_modules/heroicons/` and cached. |
+| `json` | JSON stringify with formatting: `{{json obj}}` |
+| `truncate` | Truncate a string with an ellipsis: `{{truncate text 100}}` |
+| `urlencode` | Percent-encode a value for a query parameter: `href="/signup?next={{urlencode next}}"`. Handlebars escapes an interpolated value for HTML, not for a URL, so `?next={{next}}` renders a return path of `/a&b=c` as `next=/a&b=c` and the browser reads `next=/a`. Use it for every value that lands in a query string. It encodes rather than validates, so whatever checks the value keeps doing that job. |
+| `upper` / `lower` | Case conversion |
+| `eq` | Strict equality (also available from `handlebars-helpers`) |
 
 ---
 
@@ -62,6 +75,12 @@ npm run tailwind:watch   # Development (watch mode)
 
 Use semantic class names in templates, define them in `styles/styles.css` with `@apply` for Tailwind utilities. Avoid inline Tailwind classes in templates except for one-off spacing.
 
+Class names nest.
+A block has one class, its children are nested inside it in the stylesheet with short names (`.quote-card .price`), and a variant or state is a second class on the element (`class="quote-card booked"`), selected with `&.booked`.
+BEM's `__element` and `--modifier` separators are not used, nor are flat prefixed names such as `.quote-card-price`.
+Colors, sizes and spacing come from the theme tokens in `@boopkit/cap-web/styles/theme.css`, through `var()` or `@apply`.
+The rules, with an example, are in the [boop-web-css](../skills/boop-web-css/SKILL.md) skill.
+
 ---
 
 ## Static Assets

package/scaffold/scripts/ux-eval-capture.ts

@@ -0,0 +1,103 @@
+/**
+ * UX evaluation capture — single-page screenshot for the UX workflows.
+ *
+ * Renders one URL in headless Chromium and writes a labeled full-page PNG to
+ * the capture-output directory. Used by the boop-ux-eval-and-refine-workflow
+ * and boop-ux-app-ui-dev-workflow skills to produce before/after screenshots.
+ *
+ * Usage (cap-web supplies it as the `ux:capture` npm script):
+ *   npm run ux:capture -- <path> <label>
+ * Examples:
+ *   npm run ux:capture -- /items baseline
+ *   npm run ux:capture -- /items after-change
+ *
+ * Environment:
+ *   BASE_URL                  base origin to capture against (default http://localhost:3000)
+ *   UX_EVAL_OUTPUT_DIR        output directory (default tmp/ux-eval)
+ *   UX_EVAL_AUTH_COOKIE_NAME  optional — name of an auth cookie to inject
+ *   UX_EVAL_AUTH_COOKIE_VALUE optional — value of that cookie (a valid session token)
+ *
+ * Public pages need no auth. For authenticated pages, supply a session cookie
+ * via the two UX_EVAL_AUTH_COOKIE_* env vars, or wire the cap-users opt-in
+ * block below to mint one automatically.
+ *
+ * One-time setup: `npx playwright install chromium` (downloads the browser).
+ */
+
+import 'dotenv/config';
+import { chromium } from 'playwright';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const BASE_URL = process.env.BASE_URL || 'http://localhost:3000';
+const OUTPUT_DIR = path.resolve(
+  process.cwd(),
+  process.env.UX_EVAL_OUTPUT_DIR || path.join('tmp', 'ux-eval'),
+);
+
+const targetPath = process.argv[2] || '/';
+const label = process.argv[3] || 'capture';
+
+/**
+ * Resolve the auth cookie to inject, if any.
+ *
+ * Default: read a cookie name/value from the environment (works for any auth
+ * scheme — paste a valid session token into UX_EVAL_AUTH_COOKIE_VALUE).
+ *
+ * --- cap-users opt-in -------------------------------------------------------
+ * If this project uses @boopkit/cap-users, you can mint a session token here
+ * instead of pasting one, by replacing the body of this function with:
+ *
+ *   import UserService from '../src/services/users.service';
+ *   import { connectDatabase } from '@boopkit/cap-database';
+ *   import db from '../src/db';
+ *   await connectDatabase(db);
+ *   const { identityService, authService } = UserService;
+ *   const email = process.env.DEMO_EMAIL;
+ *   const identity = await identityService.findByDomainAndKey('email', email);
+ *   if (!identity) throw new Error(`No user for ${email}`);
+ *   const token = await authService.generateSessionToken(identity.userId);
+ *   await authService.setAuthorization(identity.userId, token, 'session', 'authenticated');
+ *   return { name: 'auth_id', value: token };   // 'auth_id' is cap-users' cookie name
+ *
+ * (remember to `await db.$disconnect()` in main() if you open a DB connection).
+ * ---------------------------------------------------------------------------
+ */
+async function resolveAuthCookie(): Promise<{ name: string; value: string } | null> {
+  const name = process.env.UX_EVAL_AUTH_COOKIE_NAME;
+  const value = process.env.UX_EVAL_AUTH_COOKIE_VALUE;
+  if (name && value) return { name, value };
+  return null;
+}
+
+async function main() {
+  fs.mkdirSync(OUTPUT_DIR, { recursive: true });
+
+  const browser = await chromium.launch({ headless: true });
+  const context = await browser.newContext({ viewport: { width: 1280, height: 900 } });
+
+  const cookie = await resolveAuthCookie();
+  if (cookie) {
+    await context.addCookies([
+      { name: cookie.name, value: cookie.value, domain: new URL(BASE_URL).hostname, path: '/' },
+    ]);
+  }
+
+  const page = await context.newPage();
+  const url = `${BASE_URL}${targetPath}`;
+  const response = await page.goto(url, { waitUntil: 'networkidle', timeout: 15_000 });
+  if (!response || response.status() >= 400) {
+    throw new Error(`HTTP ${response?.status() ?? 'no response'} for ${url}`);
+  }
+
+  const outFile = path.join(OUTPUT_DIR, `${label}.png`);
+  await page.screenshot({ path: outFile, fullPage: true });
+  console.log(`[ux-eval] Saved ${outFile}`);
+
+  await browser.close();
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

package/skills/boop-web-css/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: boop-web-css
+description: "When you need to write or change CSS — adding or renaming a class, writing a selector or a stylesheet rule, or editing a class attribute in a template — name classes for what their elements are for, nest each block's children and variants inside it, and never use BEM's __element or --modifier separators."
+metadata:
+  category: web
+---
+> **Read `PROJECT.md`, beside this file, first.**
+> It records how this project applies the guidance below, and where it deliberately differs.
+> Where the two conflict, `PROJECT.md` wins.
+> Record project-specific rules there, never in this file.
+
+# Writing CSS
+
+## Goal
+
+**A stylesheet's nesting is its structure, so a class name never repeats it.**
+
+A block gets one class that names what it is.
+Its children are nested inside it in the stylesheet and take short names for what they are.
+A variant or a state is a second class on the same element, selected with `&.name`.
+The stylesheet then reads as the shape of the page, and a template's class attributes stay short.
+
+This skill applies every time you touch a class, not only when you design a page.
+It is separate from `boop-web-web-ui-design` for that reason: a one-line change to a class attribute is CSS work, and it is where the naming goes wrong.
+
+## Name classes for what an element is for
+
+A class name says what the element is for, not how it looks.
+`.page-title`, `.price` and `.booked` survive a redesign; `.big-bold`, `.text-green` and `.mt-4` do not, and they tell a reader nothing about the page.
+
+Use lowercase words joined by hyphens.
+Keep Tailwind utility classes out of templates, except for a one-off spacing tweak; apply them inside a semantic class with `@apply` instead.
+
+## The nested shape
+
+```css
+/** === Quote card === **/
+.quote-card {
+    border-color: var(--color-on-surface-muted);
+    border-radius: var(--radius-lg);
+    @apply border p-4;
+
+    .vendor {
+        @apply font-medium;
+    }
+
+    .price {
+        color: var(--color-brand-700);
+        @apply font-semibold;
+    }
+
+    &.booked {
+        border-color: var(--color-brand-500);
+    }
+}
+```
+
+```handlebars
+<article class="quote-card{{#if booked}} booked{{/if}}">
+    <h3 class="vendor">{{vendorName}}</h3>
+    <span class="price">{{fmt_dollars total}}</span>
+</article>
+```
+
+- The block, `.quote-card`, is the only class that has to be unique across the stylesheets.
+- Each child takes a short name for what it is: `.price`, not `.quote-card-price`.
+- A variant or a state is a second class on the block or child element (`class="quote-card booked"`, `class="filter-tab active"`), styled with `&.booked` inside the block.
+- Group a page's styles under the page's class, and mark each major section with a comment such as `/** === Settings page === **/`.
+- Nest only as deep as the markup needs. Each level raises the selector's specificity, and a rule three levels down is hard to override.
+
+## No BEM
+
+Never write BEM's `__element` or `--modifier` separators, in a stylesheet or in a template.
+`.quote-card__price` and `.quote-card--booked` are not allowed, and neither are flat prefixed names such as `.quote-card-price`, which are one step from BEM.
+
+Nesting already ties a child to its block.
+Repeating the block's name in every child's class attribute adds nothing, and a flat list of `.quote-card__vendor`, `.quote-card__price` and `.quote-card--booked` hides the hierarchy that the stylesheet should show.
+
+## When a short name matches more than you meant
+
+A nested selector such as `.quote-card .price` matches every element with the class `price` anywhere inside the block.
+That includes an element inside another component nested in the block, such as a line-item list that has its own `.price`.
+A short name also picks up any rule that styles that name on its own, at the top level of any stylesheet.
+
+Before you add a short child name, check both:
+
+1. Search the stylesheets for a top-level rule of that name.
+2. Look at what components the block's template renders inside it.
+
+If either applies, use a child combinator (`> .price`) so the rule reaches only the block's own children, or pick a more specific name for what the element is (`.total` instead of `.price`).
+
+## When the stylesheet around you uses old names
+
+A stylesheet you are editing may still hold BEM or prefixed names.
+Write your new classes in the nested shape anyway, rather than copying the names around them.
+The convention to match is this skill's, not the file's.
+
+Do not rename the existing classes as part of an unrelated change, because their templates change with them.
+If the old names are worth replacing, file an issue for it.
+
+## Colors, sizes and spacing come from the theme
+
+Take every color, radius, font and spacing value from the theme's tokens, through `var()` (`var(--color-brand-600)`, `var(--radius-lg)`) or through `@apply` of a Tailwind utility the theme backs.
+Do not write a literal value such as `#10b981` or `13px` in a rule.
+A literal does not change when the project's theme does, so the page drifts from the rest of the site.
+
+If no token fits, add one to the project's `@theme` block and use it.
+The web capability's default tokens are in `@boopkit/cap-web/styles/theme.css`, and [`reference/boop-guide.ref.md`](../../reference/boop-guide.ref.md) describes how a project overrides them.
+
+## Reuse a class by job
+
+Reuse a class when an element does the same job as the elements the class already styles.
+Elements that do the same job should look the same everywhere, so one class serves them all, and a later change reaches every one.
+
+Matching declarations are not a reason to share a class.
+Two classes for different jobs stay separate even when their rules are identical today, because they will change for different reasons.
+
+Never create a class named for its layout or its look, such as `.stack-sm` or `.card-shadow`.
+It is a utility class under another name.
+
+Before adding a class:
+
+1. Look for an existing class that already does the job, starting with the shared classes the web capability ships (`.btn-primary`, `.btn-secondary` and the others in its `base.css`).
+2. If one fits, use it. Do not create a near-duplicate with a slightly different name.
+3. If one is close but not right, decide whether the job is really the same. If it is, change that class; if it is not, write a new simple class. Two simple classes are better than one class with variants for every case.
+
+## Related
+
+- [`boop-web-web-ui-design`](../boop-web-web-ui-design/SKILL.md) — when the change is a new page, partial or component, for the markup patterns and the visual check before done.

package/skills/boop-web-design-handoff-bundle/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: boop-web-design-handoff-bundle
+description: "When the operator points at a design canvas (an artifact of artboards) and asks for it to be bundled, turned into a handoff, or made ready for the coding agent, turn it into a design handoff bundle under specs/design-handoffs/: a README, drop-in templates and CSS in the project's conventions, the decisions, and an eval checklist. The producing side of boop-web-design-handoff-workflow; the system wins over the prototype, and every departure is written down."
+metadata:
+  category: workflow
+---
+> **Read `PROJECT.md`, beside this file, first.**
+> It records how this project applies the guidance below, and where it deliberately differs.
+> Where the two conflict, `PROJECT.md` wins.
+> Record project-specific rules there, never in this file.
+
+# Design canvas → design handoff bundle
+
+## Goal
+
+**A bundle is a translation of the design into the project's system, not a copy of the prototype.**
+
+A canvas is drawn with the designer's own sizes, colours and one-off markup.
+The bundle restates it in the project's tokens, shared classes and partials, and records every place it departs from the drawing, so the coding agent builds the design without re-deciding it.
+The output is a folder under `specs/design-handoffs/<name>/` that [`boop-web-design-handoff-workflow`](../boop-web-design-handoff-workflow/SKILL.md) consumes.
+This skill produces the bundle; that one verifies and builds it.
+
+Never commit; the operator commits the bundle.
+
+## 1. Find and read the canvas, all of it
+
+- Find the canvas with the Artifact tool.
+  A canvas shared from another organization does not appear in `list`, even under "shared", so ask for its link straight away.
+- **List the canvas's files (`scope: "files"`) every time before bundling.**
+  Boards get added while you work.
+  Read `project/canvas.json` for the board titles, then read every `project/*.dc.html`; do not trust a board count from an earlier read.
+- People edit the canvas live.
+  Re-read the boards right before writing the bundle, and diff them against your earlier copy to pick up the edits.
+
+## 2. Check the canvas's design system against the project
+
+The canvas's design system is under `project/ds/<namespace>/tokens.json`.
+Compare its `meta.source` and its values with the project's theme: the `@theme` block in `styles/styles.css`, `@boopkit/cap-web/styles/theme.css`, and Tailwind's own `theme.css`.
+If the tokens were generated from this project and the values match, say so in the decisions file: there is nothing to reconcile, and the build uses the tokens by name.
+If they differ, list every difference and ask the operator which wins before writing any CSS.
+
+## 3. Read the project's conventions before mapping anything
+
+- [`boop-web-css`](../boop-web-css/SKILL.md) for class names and nesting, and [`boop-web-web-ui-design`](../boop-web-web-ui-design/SKILL.md) for templates and partials. The bundle's CSS and templates follow them; do not restate them in the bundle.
+- The project's web-UI and brand reference pages, including any rules on copy and on claims about the product.
+- The shared stylesheets and `views/partials/`, for the classes and partials a section can be built from.
+- The routes, controllers and forms the pages touch.
+- `git log` on `views/` and `styles/`, and `specs/history/`: handoffs get built and archived quickly, so the code the bundle replaces may have changed today.
+
+## 4. Map every section
+
+For each section of each board, decide which existing class or partial it is, or which new class it needs.
+A pattern used on more than one page goes into a shared additions file; a pattern used on one page goes into that page's stylesheet.
+Markup used on more than one page becomes a partial with documented parameters.
+
+**The system wins over the prototype.** Record each departure in `00-decisions.md`:
+
+- Type sizes, radii and spacing are the theme's tokens, not the prototype's own values.
+- Each inline colour maps to a token; keep a table of prototype value, where it is used, and what the build uses. Never introduce a new colour.
+- A fixed width or height a designer set on a heading to stop a line wrapping is not shipped. Widen the heading's container instead, so it still wraps on a phone.
+- A picture of the product is a real screenshot, not drawn markup, because a mockup can look right and not match what the product does. Specify the capture instead of building it: seeded demo data in a throwaway database, never the shared development one, then `npm run ux:capture` against the bundle's dev server, with the `<img>` width and height left for the coding agent to fill.
+
+## 5. Copy
+
+- Copy is the board's, word for word, with the project's copy rules applied.
+- Remove canvas debris, such as placeholder text, absolutely positioned leftovers and forced line breaks. Fix obvious missing punctuation, and list every fix.
+- Flag, do not silently change, anything that breaks the copy rules, such as a claim beyond what the product does. The operator decides; once they have, record the result as kept on purpose in both `00-decisions.md` and the template's comment, so a later review does not "fix" it.
+
+## 6. Write the bundle
+
+At `specs/design-handoffs/<name>/`:
+
+| File | Contents |
+|---|---|
+| `README.md` | The authoritative spec the workflow reads first: what is being built and which views and rules it replaces, a read-in-this-order table, the **Data to surface** list (view-model fields the controller does not pass yet), what was dropped and why, follow-ons out of scope, and the canvas link. |
+| `00-decisions.md` | The design-system check, the departures table, the copy fixes, a dated list of what was settled with the operator, and open questions. The bundle is not finished while any question is open. |
+| `<slug>.hbs` + `<slug>.css` per page | A drop-in template, with every new field guarded so it renders against today's view-model, and its CSS, whose header comment names the rules it supersedes. A short `NN-page-<slug>.md` beside them gives each section's layout and how it reflows. |
+| `shared-additions.css`, `partials/` | Shared classes and new partials, with where each goes and which pages use it. For a change to an existing partial, show only what changes. |
+| `NN-eval.md` | A pass/fail checklist at desktop, tablet and phone widths, which the workflow's visual check runs against. |
+| `prototypes/` | Each board exported, with cross-board links renamed to the exported filenames. |
+
+Add a routes document only when pages, redirects or forms are new or retired; shape any form endpoint like the project's existing ones.
+Each template opens with a comment naming the bundle and board, what the page is for, what the controller passes, and where its CSS lives.
+Each section gets a short comment saying why it is built the way it is.
+
+## 7. Check before handing over
+
+Run a script over the bundle and fix everything it finds:
+
+- Every `var(--…)` in the new CSS exists in the project's stylesheets, including cap-web's and Tailwind's theme files.
+- Every class in the new templates is defined in the project's CSS or the bundle's.
+- Every visible string on each board appears in its template; expect only shared navigation, footers and the strings you fixed to differ.
+
+## 8. Working with the operator
+
+Ask decisions as short, separate questions.
+Record each answer with its date in `00-decisions.md`, and update every file it touches: templates, routes document and checklist.
+Finish with where the bundle is, that nothing is committed, and what the coding agent still has to produce, such as the screenshots.
+
+## Related
+
+- [`boop-web-design-handoff-workflow`](../boop-web-design-handoff-workflow/SKILL.md) — when the bundle is done and the operator hands it to a coding agent; its README claims are verified there before anything is built.

package/skills/boop-web-design-handoff-workflow/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: boop-web-design-handoff-workflow
+description: "When the operator hands off a design package (a README plus a drop-in view template and CSS) for a redesigned surface, follow this process: read the README, VERIFY its claims against the real code, surface any buried decision to the operator, file an issue, run it as a sub-agent (branch for UAT or merge-on-clean-visual-check), then close out with knowledge integration and archival. The README is confident; confidence is not correctness — verify before you run."
+metadata:
+  category: workflow
+---
+> **Read `PROJECT.md`, beside this file, first.**
+> It records how this project applies the guidance below, and where it deliberately differs.
+> Where the two conflict, `PROJECT.md` wins.
+> Record project-specific rules there, never in this file.
+
+# Design-handoff workflow — turn a design package into shipped, reviewed code.
+
+A design handoff package is a high-leverage input: someone has already done the design work and grounded it against the real view-model, so the implementation is mostly mechanical. The leverage is real, but so is the risk, and the risk lives in one place — **the README's claims about the existing code.** A handoff that says "the service already computes X, just re-expose it" is trivial if true and a hidden architectural decision if false. The whole process turns on verifying those claims before any code is written.
+
+## What a handoff package looks like
+
+A folder under `specs/design-handoffs/<name>/`, which [`boop-web-design-handoff-bundle`](../boop-web-design-handoff-bundle/SKILL.md) writes from a design canvas.
+Three kinds of file carry the build:
+
+- **`README.md`** — the authoritative spec. Names what is being built, which files it replaces, a "Data to surface" list (the view-model fields the redesign needs that the controller does not pass yet), what was deliberately dropped, and any follow-ons that are explicitly out of scope.
+- **A drop-in view template** — replaces an existing view. Every new field is guarded (rendered only when the field is present) with a live fallback, so the template renders *today* against the current view-model and "lights up" as each data field lands. Ship the template first, work the data list independently.
+- **A CSS file** — appended into an existing style block; its header comment names the rules it supersedes.
+
+Beside them, `00-decisions.md` records where the build departs from the prototype and what the operator has already settled, and an eval checklist gives the pass/fail checks for the visual check in step 6.
+A decision recorded there is settled; do not raise it again in step 4.
+
+## The process
+
+### 1. Read the README in full
+
+It is the spec — read it before touching anything. Note the "Data to surface" items (the view-model gaps), what it claims already exists, what it dropped and why, and the named follow-ons.
+
+### 2. Verify the README's claims against the real code (the load-bearing step)
+
+The README makes assertions about the current code: "X already exists," "Y was retired," "field Z is right there on the type," "this renders today with zero controller changes." **Every one of those is a feasibility claim, and each must be checked against the actual code before you judge the package.** This is the step that separates a clean run from a buried decision.
+
+- Confirm each "already exists" / "is right there" claim by reading the named symbol. (In a real run: a handoff claimed a field was "right there" — it was, on the underlying type, just dropped on the way to the view-model; trivial. Another claimed an upstream surface "already computed" a value — it deliberately did *not*, behind a documented boundary; that was a hidden architectural decision, not a re-expose.)
+- Confirm the template's "renders today" claim: the fields it depends on now exist on the view-model (or are provided by the controller), and the genuinely-new fields are guarded with a fallback.
+- Confirm any "retired" / "dropped" claim — a value the README says is gone may still be live and reusable.
+
+When every claim checks out, it is a clean single sub-agent run. When a claim is wrong — especially when "re-expose this" turns out to mean "reverse a deliberate architectural boundary" — there is a design decision hiding inside the package.
+
+### 3. Judge feasibility for a single sub-agent run
+
+Ask: is the work bounded with a clear path, or is there a judgment call hiding — an architectural decision, a premise error in the README, a spec ambiguity, a value that has to be derived rather than re-exposed? If the path is clear, it is one sub-agent run. If a decision is hiding, **do not let a sub-agent silently resolve it** (it will take the easy path — e.g. calling the function that reverses the boundary — because that is what "makes it work").
+
+### 4. Surface the verdict and any decision to the operator
+
+Report: feasible or not, the scope, and the one question that is genuinely theirs — the buried architectural decision, framed at their altitude with a recommendation. Use `boop-product-design-thought-partnership` here. Get the call, then bake the decision into the issue so the sub-agent inherits it rather than re-deriving it. (Example: "derive the value from the shared source, not by duplicating — the README's 're-expose' framing assumed an upstream surface already had it, which it didn't.")
+
+### 5. File a bd issue (goal/approach/context shape)
+
+Per `boop-project-mgmt-beads-planning`.
+Breadcrumb the handoff README as the authoritative spec, and **if the operator settled a decision in step 4, state it in the issue and say it supersedes the README where they differ** — otherwise the sub-agent will follow the README's wrong premise.
+Note the template's graceful-degradation (template + CSS can drop first; view-model edits light it up).
+Name the visual-check as the done-gate.
+Name the skills the sub-agent needs, such as `boop-light-dev-workflow` for the per-issue steps and the project's web design skill, in the skills list that `boop-project-mgmt-beads-planning` sets out under "Breadcrumb the skills that carry the discipline".
+The sub-agent reads the issue, not this workflow, so a skill the issue does not name is one it never opens.
+
+### 6. Run it as a sub-agent
+
+- **Isolated worktree on a non-default port.** The operator's dev server on the main checkout (e.g. `:3000`) is theirs — never touch it. Create a worktree branch off main (e.g. `work/<id>`), run the worktree's dev server on a different port (`:3001`/`:3002`/etc.), copy `.env` in if tests/capture need it (gitignored, don't commit).
+- **Apply template + CSS**, removing the rules the CSS header names as superseded.
+- **Make the view-model edits** per the (corrected) data list.
+- **Trim brittle tests rather than lovingly rework them.** A redesigned surface is in flux; the operator's visual UAT is the safety net. Keep the full suite green; do not invest in expanding coverage on a surface that is still moving.
+- **The visual-check is the gate.** Build the CSS bundle, capture each affected state, and *read* the captures — the render is the proof, not the diff.
+  Capture with `npm run ux:capture -- <path> <label>`, which writes `tmp/ux-eval/<label>.png` at a desktop width of 1280.
+  It has no narrow viewport, so check the mobile layout another way, such as a browser's responsive view at 390.
+
+  - **`BASE_URL`** — the capture defaults to `http://localhost:3000`, the operator's server, not your worktree's. Pass `BASE_URL=http://localhost:<port>` with every capture, or you will screenshot someone else's build and review it as your own.
+  - **Auth** — the capture logs in only with the session cookie in `UX_EVAL_AUTH_COOKIE_NAME` and `UX_EVAL_AUTH_COOKIE_VALUE`. Use one for an account that has the data the surface shows: an empty account renders an empty page, which reads as a broken redesign but is an artefact of who is logged in.
+- **Stop the dev server you started, all of it, not only the process on the port.**
+  A dev script that watches files runs a supervisor above the server, and only the server holds the port: boop's web-app profile runs `nodemon --exec tsx src/server.ts`, so killing the port holder leaves `nodemon` running while the port reads free, and `nodemon` starts the server again on the next file change.
+  Find the supervisor by the worktree's absolute path in its command line, `ps -eo pid=,args= | grep "<absolute-worktree-path>/node_modules/.bin/[n]odemon"`, with the dev script's own watcher in place of `nodemon` if it runs another, and kill that pid; the server under it stops too.
+  Then run that search again and `lsof -ti tcp:<port> -sTCP:LISTEN`, and confirm both print nothing, because a free port does not show that the supervisor is gone.
+  If the dev script runs no supervisor, the process on the port is the whole server, and `lsof -ti tcp:<port> -sTCP:LISTEN | xargs kill` stops it.
+  Never pattern-kill (`pkill -f nodemon`, `pkill -f tsx`, and the like): a pattern reaches every other worktree's server and the operator's own.
+  Never stop a server you did not start, or one a running loop owns.
+- **Disposition:**
+  - **Branch for UAT** when the change is a substantial visual redesign the operator will want to see — leave the branch, the worktree, and the captures; do not merge, do not close.
+  - **Merge on a clean visual-check** when the change is quick, clear, and additive — merge to main only if the capture clearly confirms the result and tests are green; if verification is blocked or ambiguous, fall back to branch-for-UAT rather than merging blind.
+
+### 7. Close out (after the operator's UAT, or on a clean merge)
+
+Often itself a sub-agent. Per `boop-product-design-knowledge-backfill`:
+
+- **Merge** the branch to main; run the full suite green first.
+- **Integrate the knowledge** — update the relevant reference page (e.g. the web-UI reference for a redesigned surface) to describe the new shape, and fix any reference line the redesign made stale. Commit docs direct to main.
+- **Archive the handoff package** (unedited) to `specs/history/<name>-handoff/`.
+- **Clean up** — stop the server and its supervisor as step 6 describes, then close the issue, remove the worktree and delete the branch. Do not push to origin unless asked.
+
+## When to use this vs the other workflows
+
+| Situation | Workflow |
+|---|---|
+| A design handoff package (README + drop-in template + CSS) for a surface | **this** |
+| A design canvas the operator wants made ready for the coding agent | `boop-web-design-handoff-bundle`, then **this** |
+| A goal-framed improvement to an existing surface, no package | `boop-light-dev-workflow` |
+| A backlog cleanup sweep of lingering P1/P2 items | `boop-project-mgmt-issue-sweep-workflow` |
+| A feature with backend work driven by a spec | `boop-feature-dev-workflow` |
+
+## Anti-patterns
+
+- **Running the package without verifying its claims.** The README reads as authoritative; authority is not accuracy. The verify-against-code step (2) is the whole game — skip it and you ship a hidden decision or hit a wall mid-run.
+- **Letting a sub-agent resolve a buried architectural decision.** When "re-expose X" actually means "reverse a documented boundary," a sub-agent will reverse it because that is the path of least resistance. Surface it to the operator instead.
+- **Auto-merging a substantial visual redesign without the operator's eye.** Branch for UAT. Reserve merge-on-clean-visual-check for quick, clear, additive fixes.
+- **Lovingly reworking brittle tests on a surface in flux.** Trim them; the visual UAT is the safety net. Reworking assertions that the redesign is about to invalidate again is wasted effort.
+- **`pkill`.** It can kill the operator's main-checkout server. Precise PID only, and never the main checkout's server.
+- **Following the README's premise after the operator corrected it.** If step 4 settled a decision, the issue must say it supersedes the README, or the sub-agent inherits the wrong framing.
+- **Taking a package's scope at face value against the full mockup.** A handoff package may be a *subset* of the designer's full vision: a package redesigned only the primary list and scoped the header and empty-state out as "unchanged," but the full mockup redesigned them too — the gap only surfaced at the operator's UAT. In step 2/4, confirm the package's scope against the full design mockup; a package that says parts are "unchanged / out of scope" may still leave the surface divergent from what the operator expects. Surface that at UAT.
+
+## Related
+
+- [`boop-web-design-handoff-bundle`](../boop-web-design-handoff-bundle/SKILL.md) — when the operator points at a design canvas rather than a finished package; bundle it first.
+- `boop-product-design-knowledge-backfill` — the archive + reference-integration discipline for the closeout.
+- [`boop-web-web-ui-design`](../boop-web-web-ui-design/SKILL.md) — the visual-check-before-done rule the run leans on.
+- `boop-product-design-thought-partnership` — surfacing the buried decision at the operator's altitude.