# Capturing the current state

**Verify the capture command works before round 1.** A loop that discovers in round 3 that it has
been judging a blank page or a stale image has burned every round before it.

Each capture must be of the **real running thing**, at the same framing and viewport as the
target. Changing framing between rounds makes scores meaningless.

## Find the project's own path first

Look for an existing way to run and capture before building one:

- A project skill covering launch or rendering
- Claude Code's built-in `run` skill, which launches the app and can screenshot it
- Existing render or gallery scripts in the repo

Use what exists. A one-off script that duplicates the repo's renderer will drift from it.

## By surface

| Surface | Path |
| --- | --- |
| **Web / HTML doc** | Headless browser screenshot at a fixed viewport. Capture each required breakpoint and both themes as separate images. |
| **iOS / Mac app** | Simulator screenshot, or the OS screenshot utility against a running build. Fixed device and scale factor. |
| **Blender** | Blender MCP `get_viewport_screenshot`, or a scripted render. Read the MCP server instructions before scripting. |
| **Project renderer or mock tool** | The repo's own capture scripts, if it has them. Label output **Mock** or **Renderer** so a concept image is never mistaken for the shipped surface. |
| **Game at play zoom** | Capture at the actual zoom levels the player uses, not only hero framing. The readability axis depends on this. |

## Known gaps

**A web project with no screenshot tooling cannot run this loop yet.** Standing up a headless
browser capture is a prerequisite and it is real work — raise it rather than faking a capture from
a component gallery or a static mockup.

## Capture rules

- **One capture per round, saved as `.design-loop/round-<n>.png`.** Keep them all; the judge needs
  the previous one and you need the series to detect a stall.
- **Multi-image surfaces** — breakpoints, themes, zoom levels — pass the full set to the judge each
  round. Do not rotate which one you show; that hides regressions.
- **Never substitute a mockup, a component gallery or a prior render** for a live capture. The
  entire value of the loop is that it measures the real artifact.
- **Fix breakage before capturing**, not after. Failed asset loads, wrong orientation and missing
  fonts produce a capture that wastes a judge round on gaps you already know about.

# The judge

## Why it is a separate agent

The agent that built the thing has already decided the thing is good — it chose every value in it.
It also carries the whole build conversation, so it scores its own reasoning rather than the
pixels. A judge with **no build context** sees only the two images.

Spawn the **`design-judge` agent** with the image paths, the surface type and the target path — a
fresh one every round; never fork it and never reuse the previous judge.

## What to pass it

Absolute paths, all of them, every round:

- The locked target
- The current capture
- **The previous round's capture and verdict**, if any

The prior-verdict handoff is what makes regressions visible. Without it the judge cannot tell
improvement from drift, and scores wander.

Name the mode — `ui` or `scene` — and the agent reads its own rubric. Do not tell it what you
changed, what you intended, or what you found hard. That is the context you are paying to keep out.

## Handling the verdict

Write it to `.design-loop/verdict-<n>.md` verbatim. You need the history to detect a stall.

**Address every gap, hardest first.** Cherry-picking the cheap ones is how a loop stalls at 6/10:
the expensive gap survives every round and the judge keeps naming it.

The judge can be wrong. If a gap contradicts a hard gate, the design system or real-world scale,
**the gate wins** — note the disagreement in `notes.md` and move on. Do not argue with the judge
by re-running it on the same state hoping for a better number.

## Relaying to the user

Judge output is a subagent's raw prose and does not follow the house output style. **Never paste
it through verbatim.** Reformat before it reaches the user: score and verdict first, gate failures
next, then what you changed and what is still open.

# Scene rubric

For 3D scenes, game views, rendered assets and Blender output.

## Scored axes — 10 total

### Composition and scale (0-3)

Camera position, framing and focal length. Silhouette readability — the strongest single predictor
of whether an asset reads well. Proportion within an asset and between assets.

**Real-world scale is judged here, not assumed.** A vehicle that is subtly too large relative to a
building is a composition failure even when every surface looks correct.

### Lighting and atmosphere (0-3)

Colour palette, exposure, shadow softness and direction, contrast, ambient occlusion. Reflections,
speculars, glows and bloom where the target has them. Atmospheric depth — fog, haze, aerial
perspective — doing distance separation.

Common failure: the scene reads uniformly too dark or too flat against the target. Check overall
exposure before chasing individual materials.

### Materials and texture (0-2)

Every surface should read as the substance it is. Roughness variation, wear, edge damage,
translucency, wetness. Normal and roughness maps present where they matter.

Losing points: blocky, plasticky, uniformly smooth or flatly-coloured surfaces — unless the target
deliberately does that too. Procedural noise standing in for a real texture is a fail, not a
shortcut.

### Readability at game zoom (0-2)

**The axis a hero shot will not give you.** Judge the scene at the actual zoom levels the player
uses, not only at the framing that flatters it.

Does the silhouette still read? Does the detail survive, or does it turn to mush? Does it turn to
noise and shimmer? Do assets remain distinguishable from each other at a glance? A scene that
scores 8 on the first three axes and 0 here is not shippable.

## Hard gates — pass/fail, not scored

- **Runtime budget met** at the target resolution and zoom. Frame time and draw calls measured on
  the composed scene, not estimated per asset.
- **Every asset has a recorded qualifying licence**, a third-party manifest entry and shipped
  notices. See the chosen `licensing` stance and any path-scoped asset rule the project carries.
  Unresolved material fails this gate and stays out.
- **Real-world scale preserved.** Where the target and scale disagree, scale wins.
- **LOD present** where the class requires it, and LOD transitions do not pop visibly.
- **Style coherent with existing assets.** Imported assets are normalised to our direction rather
  than mixing styles. One photoreal asset in a stylised set is a regression, however good it is.

## Notes

Optimise only after the score clears the bar, then **re-judge** — lossless wins first, then
changes with minimal visual cost. An optimisation pass that quietly drops the score has not
succeeded.

Label evidence **Mock**, **Renderer**, or **Both**. A pretty offline render proves nothing about
the game. Sourcing an asset is not by itself a visual upgrade.

# UI rubric

For web apps, iOS/Mac apps, landing pages, dashboards and standalone HTML documents.

## Scored axes — 10 total

### Hierarchy and composition (0-3)

Does the eye land on the most important thing first, and travel in the intended order? Judge
spacing rhythm (is there a consistent scale, or arbitrary values), alignment (do edges actually
line up, including optical alignment), density (is it cramped or is it floating in dead space),
and grouping (does whitespace communicate relatedness).

Reaching for: a clear primary element, deliberate secondary and tertiary tiers, and nothing
competing for the same rank.

### Type and color (0-3)

Type scale coherence — a real scale, not seven arbitrary sizes. Weight and size doing hierarchy
work rather than color alone. Line length in a readable range and leading that matches the size.

Palette discipline — a small committed set, not accumulated one-off values. Color carrying meaning
consistently. Sufficient contrast between foreground, background and accent that the contrast gate
passes on its own merits rather than by tweaking one value at the end.

### Surface and depth (0-2)

Elevation, borders, corner radii and shadows applied as a coherent system. Every surface at a
given depth should look like it is at that depth. Shadows should match a single implied light
source and be soft enough not to read as a dark rectangle.

Losing points: muddy layering, borders and shadows both doing the same job, radii that vary
without reason, gradients that band.

### Detail and state (0-2)

Go over it with a fine-toothed comb. Icon optical alignment and consistent stroke weight. No
half-pixel edges, no ragged wrapping, no orphaned words, no clipped descenders.

Then the states that carry real product quality: **hover, focus, active, disabled, empty, loading,
error**. A design that only looks good in its happy, fully-populated state is not finished. Empty
and error states are where most UIs visibly fall apart.

## Hard gates — pass/fail, not scored

- **Contrast meets WCAG AA.** 4.5:1 for body text, 3:1 for large text and meaningful UI borders.
  Measure it; do not eyeball it. This is never traded for aesthetics.
- **Focus is visible** on every interactive element, and keyboard order is sane.
- **Design tokens and primitives are used**, not ad-hoc values. Whatever the project's token
  package and primitive library are, use them. A beautiful screen built from hardcoded hex values
  and magic numbers fails this gate.
- **Responsive at the target breakpoints**, with no horizontal scroll and no overlap at the
  narrowest supported width.
- **Both themes correct**, where the surface supports light and dark.
- **Content extremes do not break it** — longest realistic string, empty list, one item, many.

## Notes

The target does not outrank the design system. When a generated mockup wants something the tokens
do not offer, **the system wins**; record the conflict rather than forking the palette.

For HTML documents meant to read as siblings of previously shipped ones, matching the existing
family is itself a gate. Novel styling that looks good standalone but breaks the set has failed.

# Establishing the target

The target is the whole point. A loop without a locked external reference degenerates into the
agent grading its own taste, which is exactly the failure this skill exists to prevent.

**Lock it before round 1 and never regenerate it mid-loop.** If the target turns out to be wrong,
stop the loop, say so, agree a new one, and restart the round count.

## Where a target comes from, best first

### 1. The user supplied one

Use it directly. A mockup, a screenshot they like, a Figma export, a competitor's screen, a prior
approved render. Do not "improve" it first.

### 2. An approved artifact already in the repo

A blessed prior render, an existing screen whose quality bar you are matching, a sibling document
whose styling the new one must match. This is the right default for **anything that must read as
part of a set** — matching a design system, or an HTML doc that has to look like a sibling of the
ones shipped before it.

Cheap and self-bootstrapping, but it can only ratchet toward what already exists. Say so when the
brief is asking for a genuine step change.

### 3. A human-authored direction plate

For a real step change, ask for one rather than inventing it. One plate per asset class or screen
type sets a far higher ceiling than any generated frame.

### 4. Generate one

Last, and mode-dependent. See the constraints below.

## Refining rather than diverging

If the thing already exists, **capture it first and feed that capture to the image model as the
base**, asking for a refined version along the user's direction. Generating from the prompt alone
produces a target that diverges instead of improving, and the loop then spends every round
fighting to become a different product.

## Prompting for a generated target

Prompt for an **exact, realistic target screenshot** of the finished thing. Not concept art, not
a cinematic shot, not an artist's interpretation, not a mood board. You are going to try to match
it closely, so it must depict something buildable.

Avoid the words "concept art", "artistic", "illustration" and "painting" in the prompt.

## Mode constraints

### ui

Generating a target is fine. A mockup is a reference that gets looked at and thrown away — no
generated pixels ship.

But the target does not outrank the design system. Where a generated mockup conflicts with the
project's tokens, primitives or accessibility gates, **the system wins and the target is wrong on
that point**. Note the conflict in `notes.md` rather than silently following either one.

### scene

**A generated frame may set direction. It may never be a source for shipped geometry or texture.**
Prefer an approved reference plate or a prior blessed render as the target.

Two reasons, both load-bearing:

- **Licensing.** Generated image → image-to-3D → shipped asset is a derivation chain on unresolved
  terms. The chosen `licensing` stance keeps unresolved material out of production.
- **Correctness.** An image model does not respect real-world scale, LOD budget or readability at
  playable zoom. Matching its frame produces a beautiful hero shot that is wrong in the game.

Where the target and real-world scale disagree, **scale wins**.