design-polish-iteration
Render→look→diagnose→fix loop for making a live web UI look right, judged from rendered pixels instead of class names/tokens, edited in place. Use when a layout is called tight/cramped/loose/off/unbal
SKILL.mdskills/design-polish-iteration/SKILL.md
GitHubDesign Polish Iteration
You edit the top of the chain (token → utility → responsive variant → flex/grid → content → browser layout); the look only exists at the bottom. Judging spacing from tokens produces confident, wrong results. So: render, look at the pixels, diagnose in design terms mapped onto the project's token scale, fix, look again.
Routing: this skill edits the live page in place and ends there. If the accepted design must then be built (epic + sub-issues), or the ask is alternative directions rather than refinement, use /big-plan -pr. If exploration itself is the deliverable, use /protodev.
Three modes
| Mode | Trigger | Judged against |
|---|---|---|
| Diagnose | "tight", "off", a CSS change needs to look right | design principles you supply (below) |
| Reference-match | user supplies a reference image, or --target <image> |
the reference bitmap — fidelity, not taste |
| Polish | "polish this", "level up the look", plain/dated/flat | a north-star mockup (fuzzy reference) |
Arguments (polish mode)
- count: polish rounds, default 2.
- route-or-url: page to polish; if omitted, infer the single obvious WIP route or ask.
- -n <directions>: north-star mockups generated up front, default 2.
- --no-imagegen: no mockups; self-judged diagnose loop only (free, but only nudges the current look).
- --target <image>: supplied image is the north-star; skips imagegen.
- --cleanroom: implement in a
/protodevprototype, then port back deliberately. For directions that would fight the existing markup; default is in-place.
Core principle
Spacing encodes grouping. Bind tight, separate loose. The ratio between hierarchy levels is the design — not the absolute size.
- "Tight" usually = too little contrast (all gaps similar → uniform wall). Fix: raise separators (between-group, around-heading); keep or tighten binders.
- "Loose" usually = oversized binders (within-group gaps dissolved the group). Fix: shrink the binders.
- Never uniformly scale a hierarchical layout.
- On larger viewports, escalate separators, hold binders.
Full vocabulary, symptom→cause→fix cheatsheet, mobile reflow failures, and the gap-measuring snippet: references/design-knowledge.md — load it at the Diagnose step.
The loop
0. Context
- Token source: a project
*design-system*/*design-tokens*skill or doc (e.g./l-design-system) defines allowed values. Never invent raw px/rem/hex where a token exists; with no system, the values already in the codebase are the de-facto scale. - Polish mode: load
/css-wisdomtight-token articles up front —methodology/design-systems/tight-token-strategy/index.mdxandcomponent-tokens.mdx, pluscolor-tokens.mdx/typography-tokens.mdx/token-preview.mdxas needed. - Server: find the dev/serve command and port; reuse a running server, don't spawn a duplicate. Note any auth cookie/header for gated previews.
1. Capture
/headless-browser screenshots at ~390 / ~760 / ~1300px — one width misleads. Capture the worst case, not the page top: the longest title / most wrapping text, the longest list, AND the shortest near-empty group, at the narrowest viewport. Read every PNG.
2. Propose north-star directions (polish mode, unless --no-imagegen / --target)
A model handed the source over-anchors on it and "polish" collapses back to the original; a mockup generated from the screenshot breaks that anchor. Feed the baseline (usually desktop) to /codex-imagegen, once per direction:
$HOME/.claude/skills/codex-imagegen/scripts/codex-imagegen.sh \
--in <baseline-desktop.png> --out direction-1.png \
--prompt "Polished, premium redesign of this screen. Keep the same content, structure, and information. Elevate spacing rhythm, typographic hierarchy, color, depth, and detailing. Modern, restrained, on-brand — not generic AI gradient slop."
Vary the brief per direction ("editorial / high-contrast", "calm / airy", "denser / utilitarian"). Show the mockups and let the user pick — a taste call.
Cost: each mockup is ~90k–230k ChatGPT tokens. Generate once up front, not per round; re-invoke only for a new direction or a plateau.
A mockup is direction, not spec. It hallucinates text, numbers, and components. Match its intent (rhythm, hierarchy, palette, treatment); take content from the live page. An arbitrary #hex or 13px to "match the mockup" is a regression even if it looks closer — find the token.
3. Look, then measure
- Look at each width: where do groups blur, what floats apart, what is misaligned or heavy. With any reference, looking is comparative — crop your render to the reference's framing and diff element by element; never judge your render alone.
- Measure close calls: real rendered gaps via
/verify-uior the bounding-box snippet in the reference file, then check the invariants below. - Never report a color or exact value from looking.
rgb(214,211,209)andrgb(255,255,255)look identical on a dark background; same for 1px vs 2px, opacity, near-miss alignment. QuerygetComputedStyle(el)— authoritative for any real element. If the user insists a value is wrong and you "can't see it," that is the tell: stop looking and sample. - Pixel sampling is the fallback (pseudo-element, box-shadow, image, gradient, antialiased edge), and the harness lies unless robust: (a) Playwright
clipis CSS pixels but the saved image is device pixels — don't multiply clip coords bydevicePixelRatio; divide the read coords instead. (b) A 1px line sits at a sub-pixel y, so sample a ±5px band and take, per column, the pixel furthest from the background color (never hard-code "brightest"). (c) Sample a text-free region — glyphs read as a false line. When two probes disagree, the naive one is wrong.
4. Diagnose
Name the problem in design terms mapped to the token scale. Bad: "rows need more spacing" / "add shadow." Good: "within-series row gaps ≈ between-series gaps → no grouping contrast; tighten rows, raise the between-series gap two steps" / "cards read flat → raise elevation one step, tighten in-card gaps, widen between-card gap."
5. Fix, re-capture, compare
Minimal, targeted change with project tokens/components. Re-capture all breakpoints; confirm the fix did what the diagnosis predicted and broke nothing at another width. Usually 2–4 rounds converge. In polish mode, commit each accepted round (via /co) or stash before a risky one so every round is revertible; exit early when a round closes no meaningful gap.
6. Stop and hand to the human
Taste is the human's call. When the invariants pass and every width reads clean, stop and show before / after (plus north-star or reference side by side). Don't loop chasing a verdict only a person can give. Human checkpoints: picking the direction, accepting the result.
Matching a reference
With a concrete reference, the failure mode is confirming your render against your own restatement of the request instead of the reference's pixels. Skipping any of these is the bug:
- Read presence AND absence. A green line along the bottom edge says "border here" and "no border on any other edge." Write the spec both ways before coding. The classic miss: reading "border here" and adding a full perimeter.
- Apply the user's annotation legend verbatim ("green = must have, red = must not"). If a mark is truly ambiguous, ask one question; don't guess.
- Verify by diff, never self-judgment. Same region, same zoom, side by side; walk every element. Every "present in only one" is a defect — including things in yours that the reference lacks.
- Don't author pass/fail checks from your interpretation — they only confirm your misread. If a subagent verifies, give it the reference image, never your paraphrased checklist.
- On "still wrong," re-derive the spec from the reference from scratch. Repeated feedback on the same element means the underlying model is wrong, not one step short; patching it keeps it wrong.
Computable invariants
Checked against measured px:
- Contrast: between-group gap ≳ 2× within-group gap.
- Cohesion: sibling gap ≤ the item's own line-height / height.
- Monotonic hierarchy: spacing strictly increases up the grouping tree (atom < item < sibling-gap < group < section).
- Reference fidelity (when a reference exists): everything marked present is present, every unmarked region is unchanged, and nothing exists in your render that the reference does not show.