Design Fidelity Loop

Design fidelity loop

Agent-built UIs converge on "functional but generic" unless design quality is made checkable and iterated with a human eye. This is the loop that fixes it. Order matters: each step makes the next one cheap.

0. KIT FIRST: converge the component kit before any parallel fan-out

For greenfield iOS work with no approved design yet, run /ios-design first — it produces the direction, tokens, kit, and screen mockups in SwiftUI (same-language, per step 3 below), which this loop then hardens into product.

For greenfield or rebuild work, phase 0 — before dispatching any parallel scene/feature agents — is converging a compact composable component kit. Scenes-first inverts this and it costs real money: one project's scenes-first run produced ~50 divergent ad hoc components that a later consolidation pass had to inventory and (mostly fail to) migrate. Kit-first makes beauty and consistency propagate BY CONSTRUCTION, not by refactor.

Kit scope:

• 10-15 composable components (buttons incl. icon-only, cards, chips, list

rows, sheet headers, empty states, progress, badges, avatars...).

• Design tokens: fonts+sizes, spacing scale, radius scale, color SLOTS.
• A11y patterns baked into components (tap targets, labels, contrast).
• Material axes (which components may adopt glass/material treatments).
• The in-app gallery screen plus its debug launch seams.

Definition of kit-done (the convergence gate before fan-out):

• Gallery renders ALL kit components, reachable via launch seam.
• Contrast-audited; light AND dark screenshot evidence captured.
• Honest verdicts per /honest-verdicts — evidence, not claims.

Standing rule for the fan-out, stated in every scene lane's brief:

• Scene lanes COMPOSE kit components. They never define their own

components, styles, or tokens.

• A scene lane needing something new REQUESTS a kit addition; the kit

owner adds it (rule of two still applies to new variant axes).

Brownfield alternative: if you inherited a scenes-first codebase, run the /component-kit-consolidation method instead — that skill is the recovery path for exactly this inversion.

1. DRY the components (brownfield) / keep the kit canonical

• A component is defined once (a button defined once, used everywhere).

Beautifying N hand-rolled copies of a button is N units of work and N chances to drift; beautifying one shared component propagates for free.

• Brownfield: run the /component-kit-consolidation method before any

beautify wave. Greenfield: phase 0 above already gave you the kit — enforce the compose-never-define rule instead.

• Rule of two: no shared abstraction before a second real user exists.

2. Encode the project's design rules as a PROJECT skill

• Create a project-specific skill (project skills for rules bound to one

codebase; this global skill is the generic parent).

• Content must be CHECKABLE, never vibes:
• Exact tokens: named fonts+sizes, spacing scale (e.g. 8/16/24), radius

scale, color SLOTS (not hex in views — slots let skins remap).

• Hard rules a reviewer can verify in a screenshot ("dark-mode primary

CTA carries the dark ink label, not white").

• Component law: the canonical component list and "never fork a local copy".
• A pre-PR checklist the merge gate literally walks.
• A PR that violates a line in the skill is not gate-ready — that framing

turns taste into a gate.

3. In-framework gallery + screenshot iteration

• Build a component GALLERY screen inside the real app, behind a debug seam

(launch argument / debug flag), rendering every kit component. See the /skin-gallery skill for the full pattern.

• Iterate on SCREENSHOTS with the founder/designer: capture, they react,

you change tokens/slots, recapture. Pointing at pixels beats describing.

• Same-language design: design in the target framework (SwiftUI-to-SwiftUI,

React-to-React). HTML-mockup-to-native translation loses material effects, typography metrics, and platform behavior — the approved mockup then never matches the build.

4. Skin/token system so decisions propagate

• Views speak only in slots (background, surface, primary, textPrimary...).

A "skin" is a slot remap. An approved color decision then lands app-wide in one file instead of a migration.

• Keep semantic colors as materials, not alarms (rust/amber/olive over raw

crimson) unless the product genuinely needs alarm semantics.

5. Per-scene beautify waves, founder-gated

• Beautify one scene per wave, not the whole app: small diffs, reviewable

screenshots, easy revert.

• Every wave ships BEFORE/AFTER screenshot pairs, light AND dark, from a

fresh simulator/clean environment.

• Layout restructuring (repositioning, reordering hierarchy) is in scope

when it fixes poor placement — but per-scene and founder-gated, never a from-scratch rewrite program.

• Layout rhythm defaults: one primary action per screen; give the hero

element real presence (no content pinned top-left over a void); tap targets >= 44pt; group with cards on the spacing scale only.

Material/translucency lesson (glass, blur, frosted effects)

• Material effects need something to refract. Over a flat background, glass

reads as flat gray. Judge material effects over RICH content (gradients, imagery, layered scrolling content), never over a blank canvas.

• Blur DESATURATES: any color wash under a material needs real chroma

(roughly ~30% saturation at high lightness) or it greys out.

• Materials belong on the control/chrome layer (bars, pills, FABs, sheet

chrome), never on the content layer (text cards, lists) — overuse reads as noise.

• Always verify degraded modes: reduce-transparency/reduce-motion must fall

back to solid surfaces without layout shift; build Release to catch debug-only fixtures.

External input

• For divergent aesthetic directions, run the /council skill — but render

candidate palettes as actual skins in the gallery and judge screenshots; never decide from hex tables on paper.

• Visual verification is visual: unit tests and greps cannot prove a screen

looks right. Screenshot evidence is the gate artifact.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dndungu
• Source: dndungu/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.