@appsforgood/next-supabase-kit 0.4.3 → 0.4.5

package/examples/next-supabase-installed/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 |
+| `ship` | Go / no-go. Env, rollback, commands. UI needs screenshot paths |
 
-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,23 +111,51 @@ 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
 
 Copy reviews **rendered** screenshots, not just strings in TSX. Run `product-copy`, then **`deslop` last**. Do not hand off after the first draft.
 
+### Release / ship
+
+Before you promote or deploy, paste to QA:
+
+```text
+Run ship. Go or no-go. Name env, migration order, rollback, commands run. User-visible needs browser-qa screenshot paths. Reject LGTM, ship it.
+```
+
+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.
+
 ## QA screenshot loop
 
 Bad request (reject this):
@@ -141,8 +176,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/examples/next-supabase-installed/skills/accessibility-wcag/SKILL.md

@@ -1,26 +1,83 @@
 ---
 name: accessibility-wcag
-description: Use for keyboard, focus, labels, contrast, semantics, and WCAG 2.1 AA checks on user-facing screens.
+description: Use when the user can't tab, a screen reader misses a control, contrast fails, a modal traps focus, or you need a WCAG 2.1 AA pass. Keyboard in the running browser, not a screenshot guess.
 ---
 
 # Accessibility (WCAG 2.1 AA)
 
+Scan 2026-09-12 (structure only, no bodies copied): W3C WCAG 2.1 AA; GitHub packs that split keyboard / contrast / forms into specialist swarms. This pack keeps **one** skill. Do not install axe, Pa11y, an a11y MCP, or an 11-agent accessibility roster. Visual proof stays in `browser-qa`. Access control stays in `supabase-auth-rls` — hiding a control is not an accessibility pass and not authorization.
+
 ## Use when
 
-Interactive UI, forms, navigation, or any screen a keyboard or screen-reader user will use.
+Interactive UI, forms, navigation, dialogs, menus, tables, or any screen a keyboard or screen-reader user will use. Also when someone says “can't tab”, “contrast looks fine”, “add aria”, “WCAG”, or “is this accessible?”
+
+Not a substitute for `frontend-design` (look and tokens) or `owasp-security-review` (auth). Run those as their owners; this skill is the keyboard-and-semantics pass.
+
+## Do
+
+1. Open the **running** changed flow. Name the route, auth state, and what the user must finish.
+2. Keyboard-only: Tab, Shift+Tab, Enter, Space, and Escape. Record traps, missing focus, and controls you cannot reach.
+3. Check the mapping table. Skip rows that do not apply; do not skip keyboard because “it's a mouse app.”
+4. Capture desktop (~1280) and mobile (~390) for `browser-qa`. Screenshots help for contrast and target size; they do not replace step 2.
+5. Return a findings table (P0 / P1 / P2) with where it showed up and whether it is **code-certain** or **inferred**.
 
 ## Checks
 
-- Semantic headings, landmarks, and labels.
-- Keyboard order matches visual order; focus is visible.
-- Contrast meets 4.5:1 for text.
-- Tap targets are usable on mobile.
-- Errors are announced; motion is not the only signal.
+Map the change to a concrete control. Skip rows that do not apply.
+
+| Area | In this pack |
+| --- | --- |
+| Semantics (1.3.1) | Real headings, landmarks, lists, and buttons. One `h1`. ARIA only when native HTML cannot. |
+| Keyboard (2.1.1, 2.1.2, 2.4.3, 2.4.7) | Tab order matches visual order. Focus is visible. No trap except a real dialog. Escape closes overlays. |
+| Contrast (1.4.3, 1.4.11) | 4.5:1 normal text, 3:1 large text and UI chrome. Do not sign off from the screenshot alone. |
+| Color (1.4.1) | Color or a left-edge rail is not the only selected / error / success signal. |
+| Forms (3.3.1–3.3.3) | Visible `<label htmlFor>`. Errors associated (`aria-describedby` / `aria-invalid`) and announced. |
+| Name, Role, Value (4.1.2) | Custom controls expose name, role, and state. A `div` with an onClick is a finding. |
+| Status (4.1.3) | Save, error, and loading results are announced (live region or a focus move). |
+| Non-text (1.1.1) | `next/image` (and other images) have meaningful `alt`. Decorative images use empty `alt`. |
+| Bypass (2.4.1) | Skip link or landmarks so repeating chrome is skippable. Kit HTML already has a skip link. |
+| Motion | Honor `prefers-reduced-motion`. Motion is not the only signal. |
+| Targets | Taps are usable on mobile. WCAG 2.1 AA does not require 2.2’s 24×24 rule; this pack still rejects unusable hits. |
+| Auth vs a11y | A hidden button is not an a11y fix for unauthorized users. Enforce access in RLS / the server. |
+
+## App Router mapping
+
+- **Server Action forms:** every field has a label. Validation errors render in the UI, bound to the field, not only a thrown Error. Disabled submit is explained; `disabled` removes the control from the tab order — do not use it as the only “you cannot do this” hint if the user still needs to reach help text.
+- **Dialogs / sheets:** labelled (`aria-labelledby` or visible title), focus moves in, Tab cycles inside, Escape closes, focus returns to the opener.
+- **Menus / disclosure:** keyboard opens and closes; collapsed content is not in the tab order.
+- **`next/image`:** `alt` describes the image’s job, not the filename.
+- **Kit HTML (`USER_GUIDE.html`):** keep the skip link and safelight `:focus-visible` outline. Do not add `border-left` selection rails. Do not drop `lang` on `<html>`.
+
+Field checklist: `checklists/accessibility.md`.
 
 ## Tools
 
-Confirm in the running browser. Screenshots help for contrast and target size; keyboard must still be exercised.
+Confirm in the running browser. Preferred: host IDE browser. Playwright is backup for capture, not a substitute for Tab.
+
+Screenshots are evidence for contrast, clipping, and target size. **Keyboard must still be exercised.** Optional automated scanners (axe, Pa11y) may run *after* the keyboard pass; they are not the pass.
+
+Visual proof: `browser-qa` (`qa-evidence/<date>-<slug>/` plus `notes.md`). Record keyboard results in `notes.md`:
+
+```text
+keyboard: tab-order pass|fail; focus-visible pass|fail; trap none|expected-modal|unexpected
+contrast: measured|inferred-from-screenshot
+```
+
+`inferred-from-screenshot` is not enough to accept.
+
+## Reject
+
+- “Contrast looks fine in the screenshot” without a keyboard pass.
+- Approving from TSX, ARIA comments, or a Storybook file without opening the running UI.
+- Color or a left-edge rail as the only selected / error / success signal.
+- Installing axe, Pa11y, or an accessibility MCP as the required tool.
+- Copying a third-party accessibility skill body or standing up an a11y-agent swarm.
+- Treating a hidden control as the accessibility fix for a user who is not allowed to act (that is `supabase-auth-rls`).
+- A modal that does not restore focus, or that traps the page with no Escape.
+- `aria-label` that contradicts visible text.
+- Skipping keyboard because the flow is “mouse-only” or “admin-only.”
+- Kit HTML: dropping the skip link or the `:focus-visible` outline.
 
 ## Done when
 
-A keyboard-only pass works on the changed flow and remaining gaps are named.
+A **keyboard-only pass works on the changed flow in the running UI**. Tab order matches visual order. Focus is visible. Remaining gaps are named with severity and code-certain vs inferred. Visual proof is in `browser-qa` evidence. Contrast was not signed off from the screenshot alone.

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

@@ -54,6 +54,7 @@ Use the host browser when it exists. Playwright is required text for Claude, Cod
 - Playwright `toBeVisible` with no image.
 - Updating screenshot baselines without saying what changed in the picture.
 - Skipping mobile, or skipping auth/empty/error when those states exist.
+- “Contrast looks fine in the screenshot” with no keyboard-only pass (`accessibility-wcag`).
 
 ## Screenshot critique
 

package/examples/next-supabase-installed/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/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/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/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/tree.txt

@@ -55,6 +55,18 @@ CLAUDE.md
 .cursor/skills/testing-qa/SKILL.md
 .github/copilot-instructions.md
 README.md
+skills/accessibility-wcag/SKILL.md
+skills/browser-qa/SKILL.md
+skills/deslop/SKILL.md
+skills/frontend-design/SKILL.md
+skills/nextjs-app-router/SKILL.md
+skills/owasp-security-review/SKILL.md
+skills/planning/SKILL.md
+skills/postgres-migrations/SKILL.md
+skills/product-copy/SKILL.md
+skills/ship/SKILL.md
+skills/supabase-auth-rls/SKILL.md
+skills/testing-qa/SKILL.md
 tree.txt
 USER_GUIDE.html
 USER_GUIDE.md

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appsforgood/next-supabase-kit",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "Agents, skills, and a user guide for Next.js and Supabase projects. QA reviews screenshots, not code alone.",
   "type": "module",
   "repository": {