# Design Fidelity Loop

> End-to-end method for getting real design quality out of agent-built UIs — DRY components first, project design rules as checkable tokens, in-framework gallery + screenshot iteration with the designer, skin/token propagation, founder-gated beautify waves. Use when an app's UI "works but looks agent-built" or when starting any design-quality program.

- **Type:** Skill
- **Install:** `agentstack add skill-dndungu-agent-skills-design-fidelity-loop`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [dndungu](https://agentstack.voostack.com/s/dndungu)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [dndungu](https://github.com/dndungu)
- **Source:** https://github.com/dndungu/agent-skills/tree/main/design-fidelity-loop

## Install

```sh
agentstack add skill-dndungu-agent-skills-design-fidelity-loop
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://github.com/dndungu)
- **Source:** [dndungu/agent-skills](https://github.com/dndungu/agent-skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-dndungu-agent-skills-design-fidelity-loop
- Seller: https://agentstack.voostack.com/s/dndungu
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.