@appsforgood/next-supabase-kit 0.4.3 → 0.4.4

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.4.4
+
+- Uplift `frontend-design` and the Design agent from a 2026-09-12 GitHub scan (structure only): name `build` / `review` / `detect`, pick a surface profile, read `DESIGN.md` tokens, tag findings as code-certain or inferred. Do not install a design MCP or canvas CLI. Kit charcoal tokens stay off downstream apps.
+- Add Design `setup` for new repos: scan, then ask what the user needs (who it is for, what they must get done, what this pass should produce). Recommend from the answers, then write style-guide and principles files they asked for. `init` still does not install `DESIGN.md`. Setup may skip screenshots when nothing can render; Design keeps `requiredTools`.
+- Rewrite `ROADMAP.md` Phase 10 as the working queue: playbook parity for `accessibility-wcag` / `testing-qa` / `ship`, optional-skill uplifts, paste-ready handoff. Default `init` stays a relay, not an orchestrator.
+- Uplift `accessibility-wcag` to the playbook bar: WCAG 2.1 AA mapped onto App Router forms and dialogs, keyboard-only pass in the running UI, Reject “contrast looks fine in the screenshot.” Planner, QA, and Design name the skill. Structure from a 2026-09-12 scan; no third-party skill bodies, no required axe.
+- Uplift `testing-qa` to the playbook bar: unit / regression / smoke, list commands actually run, Reject `toBeVisible` as visual proof, RLS tests fail when another user can read the row. Does not replace `browser-qa` or `supabase-auth-rls`.
+
 ## 0.4.3
 
 - `doctor` fails if a default agent drops packaged `requiredTools` (QA/Design can no longer drop screenshot tools and still pass).

package/USER_GUIDE.html

@@ -509,6 +509,14 @@
                 <button class="copy" type="button" data-copy-from="plan-prompt">Copy Planner prompt</button>
               </div>
             </article>
+            <article class="ticket">
+              <header><span>New repo — paste this to Design so it asks what you need</span></header>
+              <pre id="design-setup-prompt">
+Act as design. This is a new repo. Scan what is already here, then ask me what we need to set up: who it is for, what they must get done, and what you should produce. Recommend from my answers. Write the style guide and principles with me before any CSS.</pre>
+              <div class="copy-row">
+                <button class="copy" type="button" data-copy-from="design-setup-prompt">Copy Design setup prompt</button>
+              </div>
+            </article>
           </div>
           <p>
             You should get a named owner (<code>app-engineer</code>, <code>security</code>, <code>design</code>, <code>qa</code>, or <code>copy</code>) and, if
@@ -544,6 +552,10 @@
               <td>It looks wrong</td>
               <td>Design</td>
             </tr>
+            <tr>
+              <td>Style guide / first UI / no DESIGN.md</td>
+              <td>Design (<code>setup</code>)</td>
+            </tr>
             <tr>
               <td>Is this done?</td>
               <td>QA</td>
@@ -586,11 +598,11 @@
             </tr>
             <tr>
               <td><code>frontend-design</code></td>
-              <td>Layout, simple palette, anti-generic UI</td>
+              <td>Setup, build, review, or detect UI. Tokens first. Anti-generic</td>
             </tr>
             <tr>
               <td><code>accessibility-wcag</code></td>
-              <td>Keyboard, contrast, labels</td>
+              <td>Keyboard pass in the running browser. Contrast, labels. Not a screenshot guess</td>
             </tr>
             <tr>
               <td><code>browser-qa</code></td>
@@ -598,7 +610,7 @@
             </tr>
             <tr>
               <td><code>testing-qa</code></td>
-              <td>Unit / regression / smoke only</td>
+              <td>Unit / regression / smoke. List commands run. Not screenshots</td>
             </tr>
             <tr>
               <td><code>product-copy</code></td>
@@ -615,8 +627,9 @@
           </tbody>
         </table>
         <p>
-          QA of a screen always uses <code>browser-qa</code>, not <code>testing-qa</code> alone. Each agent file names the skills it must run, then points at
-          <code>catalog.json</code> for the rest.
+          QA of a screen always uses <code>browser-qa</code>, not <code>testing-qa</code> alone. User-facing screens also run
+          <code>accessibility-wcag</code> (keyboard in the browser, not a contrast guess from the screenshot). Each agent file names the skills it must run,
+          then points at <code>catalog.json</code> for the rest.
         </p>
       </section>
 
@@ -680,17 +693,45 @@ Act as the QA agent. Use the browser-qa skill. Do not review code alone. Open th
           <li>Planner — paste the prompt on ticket 03.</li>
           <li>App engineer — <code>Implement the plan. Smoke the changed route in the browser before you hand off.</code></li>
           <li>Security if data, auth, or secrets changed.</li>
-          <li>Design if the UI changed — <code>Review the running UI from screenshots first. Desktop and mobile. Reject generic AI-looking layout.</code></li>
-          <li>QA — paste the good prompt below.</li>
+          <li>
+            Design if the UI changed —
+            <code
+              >Act as design. Name the mode (setup, build, review, or detect). Review the running UI from screenshots first. Desktop and mobile. Reject generic
+              AI-looking layout.</code
+            >
+            If <code>DESIGN.md</code> is missing, run setup first.
+          </li>
+          <li>QA — paste the good prompt below. For screens, also run <code>accessibility-wcag</code>.</li>
         </ol>
-        <p>Done when QA attaches both frames plus a verdict.</p>
+        <p>Done when QA attaches both frames plus a verdict, and the changed flow passed a keyboard-only check.</p>
         <h3>Auth / RLS</h3>
         <p>
           Planner → App engineer → Security → QA. QA must open login, logout, and denied in the browser. Screenshots still required when the finding is
           user-visible.
         </p>
+        <h3>New repo design setup</h3>
+        <p>After <code>init</code>, before the first product CSS, paste to Design:</p>
+        <pre id="design-setup-flow">
+Act as design. This is a new repo. Scan what is already here, then ask me what we need to set up: who it is for, what they must get done, and what you should produce. Recommend from my answers. Write the style guide and principles with me before any CSS.</pre>
+        <div class="copy-row">
+          <button class="copy" type="button" data-copy-from="design-setup-flow">Copy Design setup prompt</button>
+        </div>
+        <p>
+          Design scans the stack, then asks what you need. Recommendations come from those answers. It writes a short product <code>DESIGN.md</code> and
+          frontend <code>STYLE_GUIDE.md</code> rules only after that. It does not paste this kit’s charcoal desk onto the app. Screenshots wait until there is a
+          screen to capture.
+        </p>
         <h3>UI polish</h3>
-        <p>Design + <code>frontend-design</code> + <code>browser-qa</code>. Desktop and mobile. One happy-path shot is a fail.</p>
+        <p>
+          Design + <code>frontend-design</code> + <code>accessibility-wcag</code> + <code>browser-qa</code>. Name setup, build, review, or detect. Desktop and
+          mobile once a screen exists. One happy-path shot is a fail. A contrast guess from the screenshot is a fail.
+        </p>
+        <h3>Accessibility pass</h3>
+        <p>On any user-facing screen, paste to Design or QA:</p>
+        <pre id="a11y-prompt">Run accessibility-wcag. Open the changed flow. Keyboard-only pass. Do not accept contrast from the screenshot alone.</pre>
+        <div class="copy-row">
+          <button class="copy" type="button" data-copy-from="a11y-prompt">Copy accessibility prompt</button>
+        </div>
         <h3>Copy pass</h3>
         <p>Copy reviews the <em>rendered</em> words in screenshots, not strings in TSX. Run <code>product-copy</code>, then <code>deslop</code> last.</p>
       </section>
@@ -716,8 +757,9 @@ Do not review code alone. Open the app, capture desktop and mobile screenshots,
           <li>Open the changed route with the real auth, role, and data.</li>
           <li>Capture desktop (~1280) and mobile (~390) into <code>qa-evidence/&lt;yyyy-mm-dd&gt;-&lt;slug&gt;/</code>.</li>
           <li><strong>Read the images.</strong> List blockers from what is on screen.</li>
-          <li>Run applicable tests. <code>toBeVisible</code> is not a screenshot.</li>
-          <li>Write <code>notes.md</code> with route, viewports, auth state, verdict.</li>
+          <li>Keyboard-only the changed flow (<code>accessibility-wcag</code>). Do not accept contrast from the screenshot alone.</li>
+          <li>Run applicable tests (<code>testing-qa</code>). List the commands. <code>toBeVisible</code> is not a screenshot.</li>
+          <li>Write <code>notes.md</code> with route, viewports, auth state, keyboard result, commands run, verdict.</li>
         </ol>
         <p>Cursor: built-in browser first. Claude, Codex, Copilot, Antigravity: host browser if present, otherwise:</p>
         <pre id="pw-cmd">

package/USER_GUIDE.md

@@ -23,6 +23,12 @@ Plan this change. Name the owning agent, extra reviewers, and which screenshots
 
 You should get a named owner (`app-engineer`, `security`, `design`, `qa`, or `copy`) and, if the work is user-visible, a desktop + mobile screenshot list.
 
+If this repo has no product `DESIGN.md` yet, also paste to Design:
+
+```text
+Act as design. This is a new repo. Scan what is already here, then ask me what we need to set up: who it is for, what they must get done, and what you should produce. Recommend from my answers. Write the style guide and principles with me before any CSS.
+```
+
 ## How to invoke in each IDE
 
 ### Cursor
@@ -73,6 +79,7 @@ Files: `.antigravity/agent-kit/commands/*.toml`, `.antigravity/runtime-skills/*/
 | Implementation | App engineer |
 | Auth / RLS / secrets | Security |
 | It looks wrong | Design |
+| Style guide / first UI / no DESIGN.md | Design (`setup`) |
 | Is this done? | QA |
 | Landing / CTA words | Copy |
 
@@ -87,15 +94,15 @@ Do not ask one chat to be all six. Planner names the next specialist. It does no
 | `supabase-auth-rls` | Auth, RLS, service role, Storage |
 | `postgres-migrations` | Schema, constraints, RLS in the same change |
 | `owasp-security-review` | Mutations, uploads, SSRF, secrets |
-| `frontend-design` | Layout, simple palette, anti-generic UI |
-| `accessibility-wcag` | Keyboard, contrast, labels |
+| `frontend-design` | Setup, build, review, or detect UI. Tokens first. Anti-generic |
+| `accessibility-wcag` | Keyboard pass in the running browser. Contrast, labels. Not a screenshot guess |
 | `browser-qa` | Any screen. Required for QA of UI |
-| `testing-qa` | Unit / regression / smoke only |
+| `testing-qa` | Unit / regression / smoke. List commands run. Not screenshots |
 | `product-copy` | Headlines and CTAs |
 | `deslop` | Last copy pass. Copy always runs this |
 | `ship` | Release, env, rollback |
 
-QA of a screen always uses `browser-qa`, not `testing-qa` alone. Each agent file names the skills it must run, then points at `catalog.json` for the rest.
+QA of a screen always uses `browser-qa`, not `testing-qa` alone. User-facing screens also run `accessibility-wcag` (keyboard in the browser, not a contrast guess from the screenshot). Each agent file names the skills it must run, then points at `catalog.json` for the rest.
 
 ## Standard workflows
 
@@ -104,18 +111,36 @@ QA of a screen always uses `browser-qa`, not `testing-qa` alone. Each agent file
 1. **Planner** — paste: `Plan this change. Name the owning agent, extra reviewers, and which screenshots QA must capture. Do not write code.`
 2. **App engineer** — paste: `Implement the plan. Smoke the changed route in the browser before you hand off.`
 3. **Security** if data/auth/secrets changed.
-4. **Design** if the UI changed — paste: `Review the running UI from screenshots first. Desktop and mobile. Reject generic AI-looking layout.`
-5. **QA** — paste: `Do not review code alone. Open the app, capture desktop and mobile screenshots, read the images, then give accept / accept-with-nits / reject.`
+4. **Design** if the UI changed — paste: `Act as design. Name the mode (setup, build, review, or detect). Review the running UI from screenshots first. Desktop and mobile. Reject generic AI-looking layout.` If `DESIGN.md` is missing, run setup first.
+5. **QA** — paste: `Do not review code alone. Open the app, capture desktop and mobile screenshots, read the images, then give accept / accept-with-nits / reject.` For screens, also run `accessibility-wcag`.
 
-Done when QA attaches `qa-evidence/<date>-<slug>/desktop.png` and `mobile.png` plus a verdict.
+Done when QA attaches `qa-evidence/<date>-<slug>/desktop.png` and `mobile.png` plus a verdict, and the changed flow passed a keyboard-only check.
 
 ### Auth / RLS change
 
 Planner → App engineer → Security → QA. QA must open login/logout/denied in the browser and still run tests. Screenshots required when the finding is user-visible.
 
+### New repo design setup
+
+After `init`, before the first product CSS, paste to Design:
+
+```text
+Act as design. This is a new repo. Scan what is already here, then ask me what we need to set up: who it is for, what they must get done, and what you should produce. Recommend from my answers. Write the style guide and principles with me before any CSS.
+```
+
+Design scans the stack, then asks what you need. Recommendations come from those answers. It writes a short product `DESIGN.md` and frontend `STYLE_GUIDE.md` rules only after that. It does not paste this kit’s charcoal desk onto the app. Screenshots wait until there is a screen to capture.
+
 ### UI polish
 
-Design + `frontend-design` + `browser-qa`. Desktop and mobile required. One happy-path shot is a fail.
+Design + `frontend-design` + `accessibility-wcag` + `browser-qa`. Name setup, build, review, or detect. Desktop and mobile required once a screen exists. One happy-path shot is a fail. A contrast guess from the screenshot is a fail.
+
+### Accessibility pass
+
+On any user-facing screen, paste to Design or QA:
+
+```text
+Run accessibility-wcag. Open the changed flow. Keyboard-only pass. Do not accept contrast from the screenshot alone.
+```
 
 ### Copy pass
 
@@ -141,8 +166,9 @@ Steps the QA agent must follow:
 2. Open the changed route with the real auth/role/data state.
 3. Capture desktop (~1280) and mobile (~390) into `qa-evidence/<yyyy-mm-dd>-<slug>/`.
 4. **Read the images.** List blockers from what is on screen.
-5. Run applicable tests.
-6. Write `notes.md` with route, viewports, auth state, verdict.
+5. Keyboard-only the changed flow (`accessibility-wcag`). Do not accept contrast from the screenshot alone.
+6. Run applicable tests (`testing-qa`). List the commands. `toBeVisible` is not a screenshot.
+7. Write `notes.md` with route, viewports, auth state, keyboard result, commands run, verdict.
 
 Cursor: use the built-in browser first. Claude / Codex / Copilot / Antigravity: use the host browser if present, otherwise Playwright:
 

package/agents/design/agent.md

@@ -1,6 +1,6 @@
 ---
 name: design
-description: Use for UI quality, accessibility, and anti-generic layout. Critique screenshots first, then code.
+description: Use for UI quality, accessibility, and anti-generic layout. Name setup, build, review, or detect. New repos: ask what they need, then principles, before CSS. Critique screenshots first, then code.
 tools: [repo, edit, browser, screenshot, image-review]
 requiredTools: [browser, screenshot, image-review]
 ---
@@ -9,25 +9,33 @@ requiredTools: [browser, screenshot, image-review]
 
 Review and improve user-facing UI. Start from screenshots. Reject a single happy-path shot and reject generic AI-looking layout.
 
+Name the **mode** (`setup`, `build`, `review`, or `detect`) and, except setup, the **surface** (`landing`, `app-chrome`, `inside-design-system`, or `kit-html`) before changing CSS. Detect means audit only — no edits.
+
+**Setup** when `DESIGN.md` is missing or TBD, the user asked to set up design / a style guide / principles, or this is first UI work in a fresh install. Scan the repo, then **ask what they need** — who it is for, what they must get done, what this pass should produce. Follow up if answers are vague. Recommend principles from those answers, then write only the style-guide files they asked for. No CSS until they ask to build. Screenshots are not required if nothing can render yet. Do not drop `requiredTools`.
+
 This kit’s HTML (especially `USER_GUIDE.html`) is an assignment desk, not a SaaS landing page. First screen: named specialists, the fail-closed screenshot rule, and a pasteable prompt. Use `frontend-design` kit tokens: charcoal paper `#10100e`, ink `#eceae4`, safelight `#ff5a2a` only for required QA, Helvetica Neue + mono, 2px radius, no gradients, no card soup. Downstream product screens get their own 4–6 tokens — do not paste the kit desk onto an app.
 
-Public words on a screen hand to Copy. Copy finishes with `deslop`. You restyle leftover visual P0s.
+Read `DESIGN.md` when it exists. Public words on a screen hand to Copy. Copy finishes with `deslop`. You restyle leftover visual P0s. QA owns accept / accept-with-nits / reject.
 
 ## Use when
 
-Screens, components, layout, visual design, responsive behavior, or “it looks wrong.”
+Screens, components, layout, visual design, responsive behavior, “it looks wrong,” or first-run design setup on a new repo.
 
 ## Tools
 
 Allowed: `repo`, `edit`, `browser`, `screenshot`, `image-review`.  
-Required: open the running UI, capture desktop (~1280) and mobile (~390), and write findings from the images.
+Required for `build`, `review`, and `detect`: open the running UI, capture desktop (~1280) and mobile (~390), and write findings from the images. Detect still captures when a server is up; if nothing can render, mark visual findings inferred. Setup may skip capture when nothing can render yet.
 
 ## Skills
 
-`frontend-design`, `accessibility-wcag`, `browser-qa`. Visual P0 list lives in `deslop`; you fix pixels, Copy does not.
+`frontend-design`, `accessibility-wcag`, `browser-qa`. Visual P0 list lives in `deslop`; you fix pixels, Copy does not. Optional `ui-polish` is a later spacing/state pass, not a second design system. On user-visible UI, run `accessibility-wcag` — keyboard in the running browser. `frontend-design` does not replace it.
 
 Available skills: `catalog.json` and the skill table in `USER_GUIDE.md`. Start with the skills named above. Use another listed skill when this job needs it.
 
+## Review output
+
+For `review` and `detect`, return a severity table (P0 / P1 / P2) with where it showed up and whether it is code-certain or inferred. Then, unless detect, fix P0s.
+
 ## Done when
 
-Desktop and mobile screenshots were captured and read. Blockers (overlap, contrast, clipped text, missing tap targets, generic gradient/card soup) are fixed or explicitly accepted. One screenshot is not enough.
+Mode was named. Setup asked what they need and recorded the answers they asked to keep. No unsolicited CSS. For other modes, a surface was named and desktop and mobile screenshots were captured and read. Blockers (overlap, contrast, clipped text, missing tap targets, generic gradient/card soup, left-edge selection rails) are fixed or explicitly accepted. One screenshot is not enough. On screens that can render, `accessibility-wcag` had a keyboard-only pass or remaining gaps are named. Detect ends with the table and no edits.

package/agents/qa/agent.md

@@ -31,7 +31,9 @@ Available skills: `catalog.json` and the skill table in `USER_GUIDE.md`. Start w
 - One desktop screenshot of the happy path.
 - Playwright `toBeVisible` with no image.
 - Skipping mobile, or skipping auth/empty/error when those states exist.
+- “Contrast looks fine in the screenshot” without a keyboard-only pass on the changed flow (`accessibility-wcag`).
+- “Tests pass” with no command list (`testing-qa`).
 
 ## Done when
 
-You opened the running app, captured desktop and mobile screenshots, **read the images**, ran applicable tests, and wrote accept / accept-with-nits / reject with image paths under `qa-evidence/`.
+You opened the running app, captured desktop and mobile screenshots, **read the images**, ran applicable tests **and listed the commands**, and wrote accept / accept-with-nits / reject with image paths under `qa-evidence/`. For screens, `accessibility-wcag` ran: a keyboard-only pass on the changed flow, not a screenshot guess.

package/dist/index.js

@@ -303,7 +303,7 @@ function generateAntigravityCommands(cwd, force, collector) {
     {
       name: "browser-qa",
       description: "Live browser QA with desktop and mobile screenshots.",
-      prompt: "Act as the QA agent. Use the browser-qa skill. Do not review code alone. Open the app, capture desktop and mobile screenshots, read the images, then give accept / accept-with-nits / reject."
+      prompt: "Act as the QA agent. Use the browser-qa skill. Do not review code alone. Open the app, capture desktop and mobile screenshots, read the images, then give accept / accept-with-nits / reject. For screens, also run accessibility-wcag: keyboard-only pass. Do not accept contrast from the screenshot alone."
     },
     {
       name: "security",
@@ -313,7 +313,7 @@ function generateAntigravityCommands(cwd, force, collector) {
     {
       name: "frontend",
       description: "UI review from screenshots first.",
-      prompt: "Act as the design agent. Review the running UI from screenshots first. Desktop and mobile. Reject generic AI-looking layout."
+      prompt: "Act as the design agent. Name the mode (setup, build, review, or detect) and the surface. Use the frontend-design skill. If DESIGN.md is missing or this is a new repo, run setup: scan what is here, then ask what they need (who it is for, what they must get done, what this pass should produce). Recommend from the answers. Write style guide and principles only after that, and before CSS. Otherwise review the running UI from screenshots first. Desktop and mobile. Reject generic AI-looking layout. Detect means audit only \u2014 no edits."
     },
     {
       name: "copy",
@@ -323,7 +323,7 @@ function generateAntigravityCommands(cwd, force, collector) {
     {
       name: "test",
       description: "Run tests, then browser-qa for UI.",
-      prompt: "Act as the QA agent. Run applicable tests, then use browser-qa for any user-visible change."
+      prompt: "Act as the QA agent. Use the testing-qa skill: run applicable tests and list the commands. Then use browser-qa for any user-visible change. For screens, run accessibility-wcag: keyboard-only pass in the running UI. Do not treat toBeVisible as a screenshot."
     },
     {
       name: "ship",
@@ -429,7 +429,7 @@ import { join as join7 } from "path";
 
 // src/config/defaults.ts
 var PACKAGE_NAME = "@appsforgood/next-supabase-kit";
-var PACKAGE_VERSION = "0.4.3";
+var PACKAGE_VERSION = "0.4.4";
 var ROOT_DOCS = ["AGENTS.md", "USER_GUIDE.md", "USER_GUIDE.html"];
 var CURSOR_RULE_FILE = {
   source: "assistant-adapters/cursor-agent-kit.mdc",