design-gate
Implements the reviewer's half of the human gate. CLAUDE.md § Frontend changes are
HUMAN-GATED — founder review before merge says a gated PR does not merge on green CI, and:
What a gated PR owes the reviewer: rendered evidence, not a description — a screenshot
of each changed surface (and both light and dark if theming is touched), plus the before
state for anything modified rather than added. Reviewing a diff of HTML is not reviewing a
design.
This skill produces exactly that artifact, cheaply. Read the CLAUDE.md section before
running — it is the contract; this skill is only the delivery mechanism. If that section
changes, revise this skill.
Token discipline — the reason this exists
The first hand-made evidence page cost ~190k tokens and 124 tool calls, most of it the model
typing <div>s. It must never do that again.
- The model writes a manifest (a small JSON object, a few hundred tokens).
scripts/build_evidence.py emits the HTML. Every run, no exceptions.- The model decides what to capture and what to say about it. It does not decide markup,
CSS, or layout — those live in the script.
If you find yourself writing HTML tags during a /design-gate run, stop. Either the
manifest supports what you need, or the script needs a small change committed back to this
skill — not one-off markup in the output.
When NOT to use
Per CLAUDE.md, these are not gated and need no evidence page — ship on green:
- Typo, grammar, and factual corrections inside an existing block, layout unchanged
- Dead or wrong link targets
alt text, ARIA attributes, and other accessibility fixes that add no visual change- Cache-bust version bumps
- Comments, and refactors with no rendered diff
Gated (use this skill): new/removed/relocated user-facing page or section; layout, structure,
or component composition; design tokens, color, typography, spacing, motion; nav, footer,
window.GAIA_MOUNTS, or entrypoint wiring; public-page copy that changes the message;
anything rendering the graph, badges, cards, or OG images. When genuinely unsure, gate it.
Procedure
1. Scope the surfaces
From the PR diff (gh pr diff <n> --name-only, or git diff --name-only origin/main...HEAD),
list every surface a visitor could see differently. For each, record whether it is modified
(needs a before) or added (no before exists — label it, do not fake one).
For the static site, a changed shared asset (docs/js/site-nav.js, docs/css/*,
docs/js/mounts.js) means several surfaces changed, not one. Pick the representative
pages, and say in the manifest note which ones you picked.
2. Detect theming — do not assume it
grep -rl "prefers-color-scheme\|data-theme" docs/ | head
Capture a second theme only if the changed pages actually have one. Across docs/ today
this is almost entirely absent, so most runs have exactly one visual state. When there is only
one, the page must say so in gaps — a stated gap is reviewable, a silent omission is not.
Never quietly drop a dark shot the reviewer might expect.
3. Capture
Use the session's browser preview tooling. Static site:
preview_start { url: "http://localhost:8080/" } # after: python -m http.server 8080 --directory docs
Next.js or any app with a dev server: add the entry to .claude/launch.json and
preview_start { name: "<entry>" }. Then per surface:
resize_window { preset: "desktop" } → computer { action: "screenshot" }resize_window { preset: "mobile" } → computer { action: "screenshot" }
Rules:
- Mobile width is mandatory for anything with layout. Nav and footer break there first.
- Before states:
git stash / check out origin/main into a second worktree and serve
that, or capture the deployed production page. A diff cannot show whether a new nav item
crowds what was already there.
- Save PNGs into
<scratchpad>/design-gate/<pr>/img/.
- Scroll to the changed region before shooting; a full-page shot of an unchanged hero proves
nothing.
4. Write the manifest
Copy manifest.example.json and fill it in. Fields: pr, url, branch, title,
summary (one line), gaps (list of strings), and surfaces[] with name, route, note,
and shots[] of {viewport, before, after} — omit before (or set "added": true) for
newly added surfaces and the script renders a single frame labelled added - no before.
Image paths are relative to the manifest.
5. Generate
python3 .claude/skills/design-gate/scripts/build_evidence.py <scratchpad>/design-gate/<pr>/manifest.json
# add --inline to embed the PNGs as data URIs
Stdlib only, no dependencies. Prints the output path plus surface/shot counts.
Relative paths (default) vs --inline: relative keeps the HTML a few KB and the PNGs
inspectable, but the page only works alongside its img/ folder — moving the HTML alone
breaks it. --inline produces one genuinely portable file that survives being copied or
attached anywhere, at roughly 1.35× the total PNG bytes (base64 overhead), which gets slow to
open past a couple dozen shots. Default to relative; use --inline when the founder is
going to move or forward the file.
6. Present
Surface the page with SendUserFile using display: "render". If that tool is unavailable in
the session, report the absolute path and offer open <path> — do not paste the HTML into
chat.
Output is session-local — never committed
Everything lands in the session scratchpad, never in the repo.
- PNG evidence is not repo-pushable — a previous attempt to push an
evidence/* branch was
blocked by a permission gate. Do not try, and do not ask the user to work around it.
- The artifact is for the founder's eyes in-session, then discarded. The PR body links to
nothing; the review happens on the rendered page.
- Do not add screenshots to
docs/. They would become site-served Class S bytes.
Guardrails
- Never merge the gated PR. This skill produces evidence and stops. Marking a PR ready is
allowed; merging is the founder's, always. Squash is disabled on this repo — merge commits only.
- Do not edit the frontend during a
/design-gate run. Capture what is on the branch. If a
surface looks wrong, report it and let the founder decide.
- Do not fabricate a before state. If the previous state is genuinely unavailable, say so in
gaps.
- Stop at human gates. Anything needing a founder decision rather than an implementation
choice: stop and report.
Files
| Path | Role |
|---|
SKILL.md | This contract |
scripts/build_evidence.py | Manifest → self-contained HTML. Stdlib only. |
manifest.example.json | Copy-and-fill starting point |
Mirrored byte-identical in .claude/skills/design-gate/ and .agents/skills/design-gate/;
edit both (verify with diff -r).