gaia-research/gaia-skill-tree / .agents/skills/design-gate
design-gate
VerifiedProduce the rendered evidence a human-gated frontend PR owes its reviewer: capture each changed surface (plus the before state for anything modified, plus mobile width), then generate one self-contained local HTML page the founder can open and review without checking anything out. Use when a PR is gated by the "Frontend changes are HUMAN-GATED" section of CLAUDE.md, or when the user says "/design-gate", "screenshot evidence for this PR", "prep this for founder review", "build the design evidence page", "what does this look like before and after". The page comes from a template script, not hand-written markup. Output is session-local and never committed. Do NOT use for non-gated changes: typo/grammar/factual fixes in an unchanged block, dead link targets, alt/ARIA fixes with no visual change, cache-bust bumps, or refactors with no rendered diff.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.8 KB |
| manifest.example.json | config | 1.4 KB |
| scripts/build_evidence.pyexecutable | script | 8.8 KB |
SKILL.md
View on GitHub---
name: design-gate
description: >-
Produce the rendered evidence a human-gated frontend PR owes its reviewer: capture each
changed surface (plus the before state for anything modified, plus mobile width), then
generate one self-contained local HTML page the founder can open and review without
checking anything out. Use when a PR is gated by the "Frontend changes are HUMAN-GATED"
section of CLAUDE.md, or when the user says "/design-gate", "screenshot evidence for this
PR", "prep this for founder review", "build the design evidence page", "what does this
look like before and after". The page comes from a template script, not hand-written
markup. Output is session-local and never committed. Do NOT use for non-gated changes:
typo/grammar/factual fixes in an unchanged block, dead link targets, alt/ARIA fixes with
no visual change, cache-bust bumps, or refactors with no rendered diff.
version: 1.0.0
argument-hint: "<PR number, branch, or list of changed surfaces>"
---
# 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
```bash
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
```bash
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`).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |