Design Eval Loop

intent

use this skill to iteratively drive an existing ui artifact from its current state to a verified 5/5 design score. the artifact must already exist (code, figma file, prototype, or live build). enumerate every distinct view and interactive element, run parallel dead-item and design-rubric audits, apply fixes to the canonical source, then re-score with fresh agents until every view and the whole app pass the bar. use it to ship with zero dead controls and with honest scoring backed by evidence, not vibes.

inputs

before starting the loop, lock down these inputs:

target artifact(s)

• file path(s), url(s), or repo reference(s) of the ui to evaluate. if multiple builds or branches exist, confirm which one(s) the loop runs against. each artifact gets its own complete pass.
• required: read access to the canonical file or build; write access if fixes will land there.

view inventory

• the exhaustive list of every distinct view, screen, panel, overlay, modal, sheet, drawer, and detail view. derive it by examining the artifact directly, not by guessing. state the count aloud (e.g. "18 views total"). detail panels count as separate views, not as part of a parent view.
• required: this inventory must be complete before phase 1 ends.

design rubric

• location of the rubric used to score each view. default: references/rubric.md. the rubric must define all scoring dimensions (e.g. visual hierarchy, spacing, contrast, state feedback, accessibility), the 0-5 scale per dimension, and the calculation of per-view and whole-app scores.
• if the user specifies a named rubric or dimension (e.g. "wcag aa compliance", "2026 design system best practices"), honor it and confirm it exists or create it.
• required: the rubric must be available before phase 2 begins.

pass bar

• default: 5.0/5.0 per individual view, then 5.0/5.0 for the whole-app experience. users may relax this (e.g. "4.5/5 is acceptable"). state the pass bar explicitly at the start.
• required: confirm with the user before loop begins.

iteration caps

• maximum 4 complete audit-fix-rescore cycles per individual view. maximum 3 whole-app cycles. if a view hits its cap without reaching the bar, stop iteration on that view and report the named structural blocker.
• required: enforced automatically; breaking this rule voids the score.

reference materials

• references/sub-agent-prompts.md: paste-ready prompts for the dead-item auditor (agent a) and design evaluator (agent b). use verbatim; do not paraphrase.
• references/rubric.md: the scoring dimensions and weights.

external connections

• none required. all scoring, auditing, and fixing happens on the artifact itself and the canonical source file.

procedure

1. write a plan in todowrite. create one todo per phase (enumerate, audit+score, fix, rescore, whole-app). add a final todo for "review and sign off". above the todos, note the iteration cap (4 per view, 3 whole-app). nail the view count in the plan.

2. phase 1: enumerate. list every view by name and description. a view is any distinct surface: home screen, drawer, modal, sheet, overlay, settings panel, and every detail panel or sub-screen. do not collapse a detail panel into its parent. count and state aloud (e.g. "enumerated 22 views"). output: a numbered list with view name and one-line description per view.

3. phase 2: audit and score in parallel. for each iteration round, launch two sub-agents in a single message (two agent tool calls, zero wait between). do not let them run sequentially.

   • sub-agent a (dead-item audit): paste the prompt from references/sub-agent-prompts.md for the dead-item auditor. input: the artifact file or url, the view inventory from step 2, and the definition of "dead item" (a clickable element with no handler, no navigation target, no visible state feedback, or navigation to undefined/missing location). output: a structured list of dead items, each with selector/element id, expected vs. actual behavior, and impact (blocker or low priority).
   • sub-agent b (design eval): paste the prompt from references/sub-agent-prompts.md for the design evaluator. input: the artifact file or url, the view inventory, and references/rubric.md. output: a scored table with one row per view, columns for each rubric dimension, a 0-5 score per dimension, a one-line reason for each sub-score, the per-view average, and the specific blocker keeping that view below the pass bar.

4. phase 3: fix. collect the outputs from agents a and b. prioritize fixes in this order: (i) real bugs (undefined design tokens, occluded panels, z-index collisions, missing handlers), (ii) dead items, (iii) rubric gaps (lowest-scoring dimensions first). apply fixes to the canonical file only. after each fix, run a static integrity check (balanced brackets/braces/tags, all panels declared, all rows mapped, no orphan elements). document each fix with a one-line summary in a fix log.

5. phase 4: re-score changed views. launch a fresh agent (agent c, not the same agent that fixed) with the same design-eval prompt from references/sub-agent-prompts.md. input: the artifact file with fixes applied, the list of views that were modified in phase 3, and references/rubric.md. output: a before-after scorecard showing delta per dimension per changed view. do not trust the fixer's self-report; the re-scorer is independent.

6. phase 5: check convergence per view. for each view, compare the re-score (phase 4) to the pass bar (from inputs). if the view hits the bar, mark it pass and move on. if it does not hit the bar and the view has not yet hit the 4-iteration cap, loop back to phase 2 for that view only (re-audit, re-fix, re-score). if the view hits the cap, stop and report the true score and the named remaining blocker (do not round up). record which views pass and which do not after this round.

7. phase 6: whole-app pass. once every individual view reaches the pass bar, score the app as one unified experience. input: the entire artifact, the context of all individual view scores, and references/rubric.md but applied to cross-view consistency (shared design theme, navigation coherence, orphan-free surface list, internal link integrity, state sync across views). launch a fresh agent to score the whole app. output: a single score with per-dimension breakdown and blockers. if the whole-app score hits the pass bar, declare the loop complete. if not and the whole-app iteration cap (3 rounds) is not exhausted, loop back: identify the highest-impact blocker, fix it across all affected views, re-score the whole app. repeat until the whole-app score hits the bar or the cap is reached.

8. emit final scorecard and sign-off. output a compact table: view name, individual-view initial score, final score, pass/fail, named blocker if fail. below the table, emit a single whole-app score and pass/fail. include the dead-item audit result: count of dead items found and fixed per round, final count (target: zero). include a notes field with any structural gaps that could not be fixed within scope (e.g. "native control rewrite required", "focus-trap implementation out of scope"). if all views and the app pass the bar, sign the scorecard "verified 5/5, [date], [agent name]". if not, sign it with the true ceiling and the blocker.

decision points

• if multiple artifacts are in scope: confirm which one(s) get the loop. if the user says "all of them," run the full loop per artifact sequentially, keeping separate scorecards. do not merge scores.

• if the rubric is not provided or found: ask the user for the rubric url or file path. if none exists, create a minimal rubric on the spot (visual hierarchy, spacing, contrast, state feedback, accessibility) and confirm it with the user before phase 2.

• if a view is inaccessible or cannot be rendered (404, permission denied, broken build): report it immediately. do not skip it. offer to loop on a different artifact or to wait for the artifact to be fixed.

• if a view hits the 4-iteration cap without reaching the pass bar: stop iterating on that view. report the true final score, the named blocker, and whether it is a cosmetic gap (fixable in a later pass) or a structural gap (out of scope). do not round up the score.

• if the whole-app score hits the 3-iteration cap without reaching the bar: stop the loop. report the true whole-app score, the named blocker, and offer a retro to discuss scope or timeline. do not claim 5/5.

• if the user requests to stop the loop mid-round: halt immediately. output the current state (which views pass, which don't, latest scores, any in-flight fixes), and offer to resume.

• if dead-item audit finds zero dead items and design eval shows all views at 5/5: declare the loop converged. emit the scorecard and move to sign-off.

• if the artifact is a live product and fixes require a deploy: confirm the user has write access to the canonical source and a path to deploy before fixes land. do not fix-in-chat without the user confirming the changes will be applied to the actual artifact.

output contract

each round must emit:

• round header: "iteration round N for views [list]" or "whole-app round N".
• dead-item audit output: structured list of all dead items found (selector, expected behavior, actual behavior, impact rating). format: markdown list or table. count total dead items discovered this round and cumulative.
• design eval output: table with columns [view name | rubric dimension | score 0-5 | one-line reason | blocker if <5]. include per-view average and whole-app average (if applicable).
• fix log: one entry per fix applied, with selector/location, what changed, and why.
• re-score output: before-after comparison, delta per dimension, per-view average delta, and pass/fail per view.
• convergence status: which views pass the bar, which do not, iteration count per view, remaining cap per view.
• next round targets: which views will be re-audited, which are locked (cap reached or pass bar hit), whole-app status.
• scorecard table (final round only): [view | initial score | final score | pass/fail | blocker if fail], signed with date and agent name.

all output must be file-grounded: every claim must cite the view, the rubric dimension, and the specific element or section in the artifact that is being scored or fixed.

outcome signal

the skill is complete and successful when:

• every view in the view inventory reaches the pass bar (default 5.0/5 per view). this is confirmed by a fresh independent scoring agent, not by the fixer.
• the whole-app experience reaches the pass bar (default 5.0/5). this is confirmed by a fresh independent scoring agent evaluating cross-view consistency, navigation, and orphan-free structure.
• the dead-item audit reports zero dead items (all clickable elements have handlers, targets, and visible feedback).
• the final scorecard is signed with a date and the independent scorer's name.
• the user has read the scorecard, confirmed the 5/5 claim, and signs off (or rejects it and halts the loop).

success = verified 5/5 on every view and the whole app, zero dead items, honest scoring with evidence, and user sign-off.

failure / incomplete:

• any view does not reach the pass bar after 4 iterations. report the true final score and the named blocker. do not claim 5/5.
• the whole-app experience does not reach the pass bar after 3 iterations. report the true score and the blocker. do not claim 5/5.
• dead-item audit finds unresolved dead items after phase 4. report the count and do not sign off as 5/5.
• the user rejects the scorecard or stops the loop before convergence. emit the current state and suspend until user resumes.