@appsforgood/next-supabase-kit 0.4.3 → 0.4.5

package/examples/next-supabase-installed/.cursor/skills/frontend-design/SKILL.md

@@ -1,21 +1,121 @@
 ---
 name: frontend-design
-description: Use when building or reviewing user-facing UI. Commit one simple palette and type pairing. Reject default AI layouts, timid color spreads, and decoration that is not the task.
+description: Use when setting up design on a new repo, or building, reviewing, or auditing UI. Name the mode (setup, build, review, or detect). Setup asks what the user needs, then recommends principles before CSS.
 ---
 
 # Frontend Design
 
 Build or review a screen as if a stranger must name the product from the first viewport. Simple and specific beats decorated.
 
-Scan 2026-09-06 (structure only, no bodies copied): Anthropic `frontend-design` (updated 2026-06), addyosmani `frontend-ui-engineering`, `educlopez/ui-craft`, `funboy322/avoid-ai-design`, `superdesigndev/superdesign-skill`.
+Scan 2026-09-12 (structure only, no bodies copied): Anthropic `frontend-design` (2026-06), addyosmani `frontend-ui-engineering`, `educlopez/ui-craft`, `funboy322/avoid-ai-design`, `superdesigndev/superdesign-skill`, `google-labs-code/design.md`. Do not install their CLIs, canvases, MCP servers, or slash-command catalogs.
 
 ## Use when
 
-Any user-facing layout, component, HTML page, or “it looks generic.” Required for `USER_GUIDE.html` and for app screens.
+Any user-facing layout, component, HTML page, or “it looks generic.” Required for `USER_GUIDE.html` and for app screens. Also required on a **new repo** or first UI job when `DESIGN.md` is missing or TBD — run `setup` before CSS.
+
+## Mode
+
+Name the mode before CSS. Default is `setup` when `DESIGN.md` is missing or TBD, `review` when the UI already exists, `build` when it does not.
+
+| Mode | Do |
+| --- | --- |
+| `setup` | New repo or missing/TBD `DESIGN.md`. Scan, then ask what they need. Recommend from the answers. Record principles and style-guide rules only after that. No CSS unless they then ask to build. |
+| `build` | Write tokens and one layout idea, then CSS. Screenshot after. |
+| `review` | Screenshot first. Findings table, then fix P0s. |
+| `detect` | Audit only. No edits. Use when asked to scan, flag, or not change code. |
+
+## Surface
+
+Pick one profile and stay at that depth. Setup names a likely surface after the scan; it does not require one before questions.
+
+| Profile | Depth |
+| --- | --- |
+| `landing` / standalone artifact | Full direction. Spend boldness once. |
+| `app-chrome` | Quiet and dense. Loading, empty, error, and success before decoration. |
+| `inside-design-system` | Surgical. Keep tokens and primitives. Swap tells; do not invent a second brand. |
+| `kit-html` | This pack’s charcoal assignment desk. Not a SaaS landing page. |
+
+## Setup (new repo)
+
+Run this when any of these is true: `DESIGN.md` is missing; it is still TBD / `[product]` / “your product”; the user asked to set up design, a style guide, or principles; this is first UI work after `init`.
+
+The job is **asking good questions so you know what they need**. Docs and tokens are the record of that conversation. Do **not** dump a 17-doc council template. Do **not** paste this kit’s charcoal desk onto the product. `init` does not install `DESIGN.md`.
+
+### 1. Scan first — do not re-ask what you can read
+
+Read enough to name:
+
+- Product name and one-line job from README / `package.json`
+- Router: App Router (`app/`) vs Pages (`pages/`)
+- Styling: Tailwind, CSS modules, CSS variables, shadcn/ui, Radix, other component library
+- Fonts: `next/font`, self-hosted, or unset
+- Auth or first useful screens (login, invite, empty app)
+- Existing tokens in `globals.css`, Tailwind theme, or a mature `STYLE_GUIDE.md`
+
+Report the architecture in a short list, then ask. If a real visual system already exists, stay surgical (`inside-design-system`) and offer to record it rather than invent a second brand.
+
+### 2. Ask what they need
+
+Setup is an interview. Use the scan as context, not as a quiz.
+
+**How to ask**
+
+- One message, in their language (the work, the person), not ours (hex, motion budget, “three personality traits”).
+- Skip anything they already answered or the scan already settled.
+- If an answer is vague (“make it modern,” “make it pop”), ask one follow-up: *what should a stranger see, and what would be the wrong product?*
+- Do not ask them to pick a hex, a font, or a motion budget until you know the need.
+- Public words still belong to Copy.
+
+**Need questions** (ask these; drop any they already covered)
+
+1. What are we setting up, and what do you need from this pass — principles, a style guide, a first-screen direction, or all of it?
+2. Who has to succeed, and what are they trying to finish?
+3. On the first useful screen, what must they be able to do?
+4. What is already decided — brand, components, legal, accessibility — and what must it *not* look like?
+5. When this works, what is in front of them? When it fails, what did we get wrong?
+
+Listen. Follow up once if needed. Then recommend.
+
+### 3. Recommend from the answers, then pause
+
+Best practices are tailored, not a canned list. Always include:
+
+- The **need** you heard, in one sentence.
+- **Principles (4–6)** that serve that need. Default bar unless they overrode it: first screen = the work; one field, one ink, one accent, one line; states before decoration; WCAG 2.1 AA contrast (4.5:1 text); match the existing stack; no left-edge selection rails.
+- **Visual direction** only if they asked for one: a token recipe from Color below that fits *this* domain, or a surgical pass if shadcn/existing tokens already exist. Downstream apps never copy kit charcoal `#10100e`. Two one-sentence options and a pick.
+- **Anti-references** in their words, plus any 2026 defaults that would make this the wrong product.
+- What you will write vs what can wait.
+
+Pause for confirm. If the session is non-interactive, or the user said to proceed, **state assumptions** and continue.
+
+### 4. Record what they need — no CSS yet
+
+Write only the files this pass called for. Default, when they want a style guide and principles, is a **short** product `DESIGN.md` (not the 160-line kit template):
+
+```markdown
+# DESIGN.md
+
+## Need
+## Product
+## Who it is for
+## First-screen job
+## Architecture found
+## Principles
+## Tokens
+| Token | Value | Use |
+| --- | --- | --- |
+## Anti-references
+```
+
+`STYLE_GUIDE.md`: if missing, write a short **Frontend (product)** section (tokens live in `DESIGN.md`, states, stack, anti-slop). If a mature guide already exists, **append** that section — do not overwrite.
+
+Then stop. If they asked to build a screen, switch to `build`. Setup does **not** require screenshots when nothing can render yet. Do not drop `requiredTools` on the Design agent.
 
 ## Ground in the subject
 
-Name the product, the user, and this screen’s job before CSS. Tokens come from the domain (materials, time of day, one real object) — not from a theme pack. A toy store and a ledger cannot share a palette.
+Name the product, the user, and this screen’s job before CSS. Read `DESIGN.md` when it exists — tokens there are normative; prose is how to apply them. Tokens come from the domain (materials, time of day, one real object) — not from a theme pack. A toy store and a ledger cannot share a palette.
+
+Match the project’s stack (CSS variables, Tailwind, existing component library). Do not mix a second styling approach.
 
 **This kit’s HTML** (`USER_GUIDE.html`): charcoal assignment desk.
 
@@ -40,7 +140,7 @@ One field, one ink, one accent, one line. That is enough.
 
 1. **Dominant field** (~80%): the page. Flat. Not a gradient, not a mesh.
 2. **Ink** (~15%): body text. Contrast ≥ 4.5:1 (3:1 for large type).
-3. **Accent** (~5%): one action or one required state. Recolor-as-decoration fails.
+3. **Accent** (~5%): one action or one required state. A few placements in the first viewport (primary CTA, one required/fail). Recolor-as-decoration fails.
 4. **Line / well**: borders and code wells, one step off the field.
 
 Recipes (pick one that fits the product, then stop):
@@ -87,23 +187,55 @@ None, or one moment that answers a click. Fade-and-slide on every section is gen
 
 ## Process
 
-1. Name the product, the user, and the job of this screen.
-2. Write the 4–6 tokens and one-sentence layout idea.
-3. Check the plan is not a 2026 default (cream editorial, neon-on-black decoration, SaaS card kit, newsprint desk, last week’s “tasteful” swap). If it is, change one axis: field, accent, or structure.
-4. Build. Spend boldness once. Remove one accessory.
-5. Screenshot desktop (~1280) and mobile (~390). Fix from pixels. Ask: would a stranger believe a person chose this?
+If mode is `setup`, follow **Setup** instead of this list.
+
+1. Name the mode, the surface profile, the product, the user, and the job of this screen.
+2. Read `DESIGN.md` and existing tokens if they exist. If the brief names a look, follow it — including when it asks for a 2026 default.
+3. Write the 4–6 tokens and one-sentence layout idea (build), or skip to screenshots (review/detect).
+4. Check the plan is not a 2026 default (cream editorial, neon-on-black decoration, SaaS card kit, newsprint desk, last week’s “tasteful” swap). If it is and the brief did not ask, change one axis: field, accent, or structure.
+5. Build or rewrite at the profile’s depth. Spend boldness once. Remove one accessory.
+6. Screenshot desktop (~1280) and mobile (~390). Fix from pixels. Ask: would a stranger believe a person chose this?
+7. If you cannot render, mark visual findings **inferred** and say so. Code-level tells (literal `from-indigo-500`, Inter, untouched shadcn zinc) stay **code-certain**.
 
 ## Checks
 
 - A stranger can name the product from the first screen.
-- Loading, empty, error, disabled, success exist where the flow has them.
-- Focus visible, tap targets usable.
+- Loading, empty, error, disabled, success exist where the flow has them. Color is not the only state signal.
+- Focus visible, tap targets usable. Keyboard order matches visual order. Keyboard, labels, and contrast fail-closed live in `accessibility-wcag` — a pretty screenshot is not a keyboard pass.
 - Copy on the screen is real. If words are public-facing, Copy runs `deslop` last.
 
+## Review output
+
+For `review` and `detect`, use a table. Do not approve from a vibe.
+
+| Severity | Finding | Where | Confidence |
+| --- | --- | --- | --- |
+| P0 | Layperson would call it AI-made, or it blocks use | screenshot or file | code-certain / inferred |
+| P1 | A designer would notice | screenshot or file | code-certain / inferred |
+| P2 | Craft gap | screenshot or file | code-certain / inferred |
+
+P0 list lives in `deslop`. A clean catalog pass is necessary but not enough: the result must still look chosen for this product.
+
+## Reject
+
+- Approving UI from TSX or HTML alone.
+- Starting CSS on a new product before `setup` when `DESIGN.md` is missing or TBD.
+- Quizzing them on hex, fonts, or motion before you know what they need.
+- Writing `DESIGN.md` from a template without asking what this setup is for.
+- Overwriting a mature `STYLE_GUIDE.md`.
+- Pasting this kit’s charcoal desk onto a downstream product.
+- Installing a design MCP, canvas CLI, or slash-command pack to “do design.”
+- Detect-mode edits.
+- A full rebuild inside an existing design system when a surgical pass would do.
+- Mesh gradients, noise overlays, and decorative atmosphere as the default “bold” move (older `frontend-design` forks). The brief can ask; the model must not invent it.
+- “We’ll make it distinctive later.” Use the product’s tokens now.
+
 ## Tools
 
-`browser` + `screenshot` + `image-review` first. Do not approve UI from TSX or HTML alone.
+`browser` + `screenshot` + `image-review` first for `build`, `review`, and `detect`. Do not approve UI from TSX or HTML alone. Setup may skip capture when nothing can render yet.
 
 ## Done when
 
-Desktop and mobile images were read. Token list is in the change or in `DESIGN.md`. No P0 slop from `deslop` remains unless Design names it as an accepted exception.
+**Setup:** architecture was reported, need questions were asked (and followed up if vague) or assumptions stated, recommendations match what they need, and the files this pass called for were written. No unsolicited CSS. Screenshots are not required if nothing can render.
+
+**Build / review / detect:** Mode and surface were named. Desktop and mobile images were read (or detect listed what could not be rendered). Token list is in the change or in `DESIGN.md`. No P0 slop from `deslop` remains unless Design names it as an accepted exception. Detect ends with the table and no file edits.

package/examples/next-supabase-installed/.cursor/skills/planning/SKILL.md

@@ -16,11 +16,12 @@ Planning, roadmaps, “what should we do,” or any request that needs an owner.
 3. Name the skill that owner must run first:
    - App engineer: `nextjs-app-router` and, if data/auth, `supabase-auth-rls` / `postgres-migrations`
    - Security: `owasp-security-review` + `supabase-auth-rls`
-   - Design: `frontend-design`
-   - QA: `browser-qa` (screens) and `testing-qa` (commands)
+   - Design: `frontend-design` (name setup, build, review, or detect) and, for screens, `accessibility-wcag`
+   - QA: `browser-qa` (screens), `testing-qa` (commands), `accessibility-wcag` for user-facing screens, and `ship` for a release go/no-go
    - Copy: `product-copy` then `deslop` last
-4. Add extra reviewers: Security for auth/data/secrets, Design for UI, QA for behavior/UI, Copy for public words.
-5. If the change is user-visible, list the desktop and mobile screenshots QA must capture.
+4. If the work is user-visible and `DESIGN.md` is missing, TBD, or the user asked for a style guide / principles: owner is Design in `setup` first. Design must ask what they need before inventing tokens. Do not let App engineer invent tokens.
+5. Add extra reviewers: Security for auth/data/secrets, Design for UI, QA for behavior/UI, Copy for public words.
+6. If the change is user-visible, list the desktop and mobile screenshots QA must capture. Setup may skip screenshots when nothing can render yet.
 
 ## Done when
 
@@ -28,4 +29,4 @@ Owner, extra reviewers, required skills, preserved behavior, and required screen
 
 ## Reject
 
-Implementing in the planning pass. Asking one chat to play every role. Skipping `supabase-auth-rls` because “it’s just a table.” Skipping `nextjs-app-router` because the route is small.
+Implementing in the planning pass. Asking one chat to play every role. Skipping `supabase-auth-rls` because “it’s just a table.” Skipping `nextjs-app-router` because the route is small. Skipping Design `setup` on a new product UI because “we’ll pick colors in CSS.” Skipping `accessibility-wcag` because “contrast looks fine in the screenshot.” Skipping `testing-qa` because “we’ll add tests later” on auth/RLS. Skipping `ship` because “LGTM, ship it.”

package/examples/next-supabase-installed/.cursor/skills/ship/SKILL.md

@@ -1,22 +1,67 @@
 ---
 name: ship
-description: Use before release. Check env vars, migration order, smoke, and rollback. User-visible releases still need browser-qa evidence.
+description: Use before deploy, promote, rollback, or when someone says LGTM, ship it. Go or no-go. Name env, migration order, rollback, commands run. User-visible still needs browser-qa screenshot paths.
 ---
 
 # Ship
 
+This skill is **go / no-go**. Commands live in `testing-qa`. Screenshots live in `browser-qa`. Keyboard pass lives in `accessibility-wcag`. Policies live in `supabase-auth-rls`. Schema order lives in `postgres-migrations`. Secrets and OWASP live in `owasp-security-review`. This skill does not replace those.
+
 ## Use when
 
-Preparing to deploy, promote, or roll back.
+Preparing to deploy, promote, roll back, or cut a production release. Also when someone says “ship it”, “LGTM”, “is this ready?”, “promote preview”, or “rollback”.
+
+Not a substitute for writing the feature. Run this **after** the owning specialists finish. QA names the verdict; App engineer names env and the app rollback; Security names secrets and RLS.
+
+## Do
+
+1. Name the target (`preview` / `production` / named env) and what commit or deployment is going out.
+2. List production-critical **env var names** (not values). Confirm they exist on that target. Flag any `NEXT_PUBLIC_` secret or service role on the client.
+3. Name migration order. If schema changed, say whether the migration already ran and how to reverse it (`postgres-migrations`). Do not drop a column the live app still reads.
+4. Run `testing-qa`: list commands actually run. Smoke of the primary path is required for a go.
+5. If anything user-visible changed: attach `browser-qa` desktop + mobile paths. For screens, `accessibility-wcag` already ran. Missing paths are a no-go.
+6. Return **go** or **no-go** with gaps. Do not imply go by omitting the word.
 
 ## Checks
 
-- Production-critical env vars are named.
-- Migration order and rollback are explicit.
-- Smoke of the primary path passed.
-- User-visible changes have desktop and mobile screenshot evidence from `browser-qa`.
-- Secrets are not in the repo or client bundle.
+| Area | Pass |
+| --- | --- |
+| Target | Preview vs production (or named env) is explicit. |
+| Env | Critical names listed. Values are not pasted into the verdict. |
+| Secrets | No secrets in git, `NEXT_PUBLIC_*`, client bundle, or logs. Service role stays server-only. |
+| Migrations | Order named. Rollback named, or expand/contract reverse named. Empty “N/A” only if schema did not change. |
+| Commands | `testing-qa` list with results. Smoke of the primary path (login or the workflow being released). |
+| UI | User-visible changes have `qa-evidence/<date>-<slug>/desktop.png` and `mobile.png`. |
+| Host | If this app is on Vercel (or similar), name preview vs production and how to restore the previous deployment. Do not require a Vercel CLI install from this kit. |
+
+## Evidence
+
+```text
+verdict: go | no-go
+target: preview | production
+commands:
+  - npx vitest run                 # pass
+  - npm run smoke                  # pass
+env: NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY set; SERVICE_ROLE not in client
+migrations: 0012_widgets applied; rollback = reverse 0012 / expand-contract reverse
+rollback:
+  app: previous production deployment / git revert <sha>
+  db: do not drop 0012 in this release if the app still reads it
+browser-qa: qa-evidence/2026-09-13-settings/desktop.png, mobile.png
+gaps: none | named
+```
+
+## Reject
+
+- “LGTM, ship it” (or “looks good, deploy”) with no env list, no rollback, and no commands.
+- User-visible release without `browser-qa` screenshot **paths**.
+- “We’ll set env in the dashboard later” or shipping with placeholder secrets.
+- `SUPABASE_SERVICE_ROLE_KEY` (or any secret) in `NEXT_PUBLIC_*`, the repo, or a client bundle.
+- Skipping rollback because “it’s a small change” or “we can just migrate forward.”
+- Treating `toBeVisible` or “tests pass” as the ship gate. Use `testing-qa` and, for UI, `browser-qa`.
+- Replacing `testing-qa`, `browser-qa`, `postgres-migrations`, `supabase-auth-rls`, or `owasp-security-review` with this skill.
+- Pasting secret **values** into the go/no-go note.
 
 ## Done when
 
-Go / no-go is explicit, with commands run and rollback named.
+Go or no-go is explicit. Commands run, env names, migration order, and rollback are named. User-visible work has `browser-qa` screenshot paths. Secrets were not written into the verdict.

package/examples/next-supabase-installed/.cursor/skills/testing-qa/SKILL.md

@@ -1,29 +1,68 @@
 ---
 name: testing-qa
-description: Use when adding unit, regression, or smoke tests. Visual proof of a screen always also uses browser-qa.
+description: Use when adding unit, regression, or smoke tests, or when someone says tests pass without listing commands. Visual proof of a screen always also uses browser-qa. RLS tests must fail when another user can read the row.
 ---
 
 # Testing QA
 
+This skill is **commands**. Screenshots live in `browser-qa`. Keyboard pass lives in `accessibility-wcag`. Policies live in `supabase-auth-rls`. Do not replace those.
+
 ## Use when
 
-Adding or reviewing tests, smoke checks, or regression coverage.
+Adding or reviewing tests, smoke, regression, “is this tested?”, or “tests pass.”
+
+## Do
+
+1. Name the kinds this change needs: unit, regression, smoke. Skip kinds that do not apply; do not skip RLS/auth when data is involved.
+2. Run the commands that already exist in this repo (`package.json` scripts). Do not invent a second test runner.
+3. For auth, RLS, or mutations: include a **negative** that fails when another user or anon can read or write the row.
+4. List what ran, the result, and gaps. If the harness is missing, name it; do not skip silently.
+5. User-visible work still goes to `browser-qa` (and `accessibility-wcag` for screens). Playwright `toBeVisible` is not that handoff.
+
+## Kinds
+
+| Kind | What | Not |
+| --- | --- | --- |
+| Unit | Core logic, schema validation, helpers | A screenshot |
+| Regression | Preserved behavior still holds | Rewriting the old test to match a bug |
+| Smoke | Critical path against a running app (login, primary workflow) | `browser-qa` image review |
+
+Smoke may use Playwright if the repo already has it. `toBeVisible` proves a node is in the DOM, not that the screen is correct.
+
+## Auth / RLS
+
+`supabase-auth-rls` owns the policy. This skill requires a test that would **fail** if another signed-in user can `select` / `update` / `delete` the row, or if anon can read a private row. A hidden button is not a test of access.
+
+Shape (adapt to the repo’s harness):
+
+```ts
+// Must fail the job if RLS is missing or too open
+const { data } = await asOtherUser().from("widgets").select().eq("id", ownerRowId);
+expect(data ?? []).toHaveLength(0);
+```
+
+`ENABLE ROW LEVEL SECURITY` without that negative is not coverage.
 
-## Checks
+If the change is App Router, Auth/RLS, or a migration, tests must cover those contracts. This skill does not replace `nextjs-app-router`, `supabase-auth-rls`, `postgres-migrations`, or `owasp-security-review`.
 
-- Core logic has unit tests.
-- Preserved behavior has regression tests.
-- Critical flows have Playwright or equivalent smoke tests.
-- Auth, RLS, and mutation paths are prioritized (other-user / anon cannot pass).
-- Network failure, empty, and error behavior is covered.
-- Gaps are named when infrastructure is missing.
+## Evidence
 
-If the change is App Router, Auth/RLS, or a migration, tests must cover those contracts. This skill does not replace `nextjs-app-router`, `supabase-auth-rls`, `postgres-migrations`, or `owasp-security-review`. Visual proof of a screen still uses `browser-qa`.
+```text
+commands:
+  - npx vitest run tests/rls.test.ts   # pass
+  - npm run smoke:install              # pass
+gaps: no Playwright harness yet; named
+```
 
-## Visual proof
+## Reject
 
-User-visible screens also require `browser-qa`. This skill does not replace screenshots. Passing `toBeVisible` is not image review.
+- `toBeVisible` (or “the test found the button”) as visual proof. Use `browser-qa`.
+- “Tests pass” with no command list and no results.
+- Skipping RLS/auth tests because “it’s just a table” or “we’ll add tests later.”
+- Replacing `browser-qa` or `accessibility-wcag` with this skill.
+- A green suite that would still pass if another user could read the row.
+- Adding Playwright as a required install of this kit. Use it when the repo already has it.
 
 ## Done when
 
-Commands run, results, and residual gaps are listed. RLS/auth tests fail closed when another user can read the row.
+Commands run, results, and residual gaps are listed. RLS/auth tests fail closed when another user or anon can read the row. User-visible work still has `browser-qa` evidence.

package/examples/next-supabase-installed/AGENTS.md

@@ -16,6 +16,7 @@ A user-visible change is not done until someone opened the running UI, captured
 | Implement Next.js or Supabase | `@app-engineer` |
 | Auth, RLS, secrets, OWASP | `@security` |
 | UI looks wrong / generic | `@design` |
+| Style guide / first UI / no DESIGN.md | `@design` (setup) |
 | Is this done? | `@qa` |
 | Headlines, CTAs, empty states | `@copy` |
 
@@ -23,7 +24,7 @@ Do not ask one chat to be all six.
 
 ## Handoff
 
-Planner names the owner. Security joins auth/data/secret work. Design joins user-facing screens. QA joins any behavior or UI change and **must use the browser**. Copy joins public/conversion copy. Stop there.
+Planner names the owner. Security joins auth/data/secret work. Design joins user-facing screens and first-run style-guide setup. QA joins any behavior or UI change and **must use the browser**. Copy joins public/conversion copy. Stop there.
 
 ## Skills
 

package/examples/next-supabase-installed/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>
@@ -610,13 +622,14 @@
             </tr>
             <tr>
               <td><code>ship</code></td>
-              <td>Release, env, rollback</td>
+              <td>Go / no-go. Env, rollback, commands. UI needs screenshot paths</td>
             </tr>
           </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,19 +693,58 @@ 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>
+        <h3>Release / ship</h3>
+        <p>Before you promote or deploy, paste to QA:</p>
+        <pre id="ship-prompt">
+Run ship. Go or no-go. Name env, migration order, rollback, commands run. User-visible needs browser-qa screenshot paths. Reject LGTM, ship it.</pre>
+        <div class="copy-row">
+          <button class="copy" type="button" data-copy-from="ship-prompt">Copy ship prompt</button>
+        </div>
+        <p>
+          QA names the verdict. App engineer names env and the app rollback. Security names secrets and RLS. Missing screenshot paths on a user-visible release
+          is a no-go.
+        </p>
       </section>
 
       <section id="qa">
@@ -716,8 +768,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">