Skip to content

Prototype Refinement Loop

The chain of helper skills and agents between /vt-c-pd-3-prototype (build the prototype) and /vt-c-pd-4-validate (plan the user test). Documents which helper to reach for, when, and why — so you refine deliberately instead of falling back to plain prompting.

[!IMPORTANT] Recommendation, not a mandate (Empfehlung, nicht Zwang). This is a suggested sequence, not a required pipeline. Skip steps that do not apply, reorder freely, and stop when the prototype is good enough for validation. pd-3 does not run this sequence for you — you invoke each helper as needed.

The gap this closes

Today the path from prototype to validation is undocumented:

/vt-c-pd-3-prototype  →  ???  →  ???  →  /vt-c-pd-4-validate

Eight existing helpers already cover this ground; they were just never chained. This guide names them, gives a trigger condition for each, and shows the order they usually apply in.

The sequence

/vt-c-pd-3-prototype  ──▶  build the prototype (Angular+PrimeNG or Astro+Tailwind)
        │
        ▼
  visitrans-design-system  ──▶  CD compliance: tokens, logos, theme (almost always)
        │
        ▼
  frontend-design          ──▶  distinctive UI polish (when it feels generic)
  gemini-imagegen          ──▶  hero / placeholder imagery (when imagery is missing)
        │
        ▼
  design-iterator          ──▶  iterative visual refinement (visible gaps persist)
  figma-design-sync        ──▶  match a Figma source (a Figma file exists)
  design-implementation-reviewer ──▶  impl-vs-Figma review (only when a Figma reference exists)
        │
        ▼
  container-logistics-ux-expert  ──▶  domain UX critique (PRD domain = container/logistics)
        │
        ▼
  webapp-testing           ──▶  interaction smoke test (before handing off)
        │
        ▼
/vt-c-pd-4-validate   ──▶  plan the usability test

Canonical helper set

These eight helpers make up the refinement chain. The table below is the single source of truth for helper names and types — the drift-guard test parses it and fails if any name stops resolving in the skill/agent manifest. Keep it in sync with the identical table in the pd-3 SKILL.md refinement block.

Helper Type
visitrans-design-system skill
frontend-design skill
gemini-imagegen skill
webapp-testing skill
container-logistics-ux-expert skill
design-iterator agent
figma-design-sync agent
design-implementation-reviewer agent

Skills are guidance you apply in place (invoke as /vt-c-<name>); agents are sub-tasks you dispatch. The product-design-orchestrator lists agents under Sub-Agents Under Your Coordination and skills under Skills to Reference.

Per-helper detail

1. visitrans-design-system (skill)

  • What it does: validates that the prototype uses the locked VisiTrans/VisiMatch/VisiFair color palette, Inter typography, correct logo lockups, and the two-theme (light/dark) system.
  • When to invoke: almost always, immediately after the prototype is generated. CD drift is the most common and most visible defect in a fresh prototype.
  • Example: /vt-c-visitrans-design-system --validate

2. frontend-design (skill)

  • What it does: raises the UI from functional to distinctive — layout rhythm, spacing, typographic hierarchy, avoiding the generic "AI default" look.
  • When to invoke: when the prototype works but feels bland or template-like.
  • Example: /vt-c-frontend-design

3. gemini-imagegen (skill)

  • What it does: generates or edits imagery (hero images, mockups, logos-with-text, product shots) via the Gemini API.
  • When to invoke: when the prototype has placeholder or missing imagery that blocks a realistic look for the user test.
  • Example: /vt-c-gemini-imagegen

4. design-iterator (agent)

  • What it does: takes screenshots, analyzes what is not working, applies improvements, and repeats N times — systematic visual refinement no single change achieves.
  • When to invoke: when visible visual gaps persist, or you have already made more than one or two manual design changes without the design converging. That non-convergence is the signal to hand it to the iterator rather than keep hand-tuning.
  • Example: dispatch the design-iterator agent with 5–10 iterations.

5. figma-design-sync (agent)

  • What it does: compares the live implementation against a Figma design and fixes visual differences, iterating until they match.
  • When to invoke: only when a Figma source exists for the screen. Skip entirely if the prototype has no upstream Figma file (the common case for code-first prototypes).
  • Example: dispatch the figma-design-sync agent with the Figma URL and the local URL.

6. design-implementation-reviewer (agent)

  • What it does: visually diffs the live implementation against its Figma design (via the Figma + Playwright MCPs) and reports discrepancies (already listed in the orchestrator's Sub-Agents table). Its workflow requires a Figma source — it is not a general design-review pass.
  • When to invoke: only when a Figma design reference exists for the screen — the same condition as figma-design-sync above. Skip it for code-first prototypes with no Figma source. This is a review pass, not an edit pass — run it after the iterator/sync steps settle.
  • Example: dispatch the design-implementation-reviewer agent against the Figma source and the running prototype.

7. container-logistics-ux-expert (skill)

  • What it does: applies container-logistics domain UX expertise — terminology, workflows, and interaction patterns specific to freight/consignee/terminal users.
  • When to invoke: explicitly, when the PRD domain is container / logistics (e.g. a VisiMatch consignee portal). There is no auto-detection — you decide from the PRD.
  • Example: /vt-c-container-logistics-ux-expert

8. webapp-testing (skill)

  • What it does: drives the running prototype (navigation, forms, primary flows) as an interaction smoke test.
  • When to invoke: last, right before /vt-c-pd-4-validate, to confirm the prototype is clickable end-to-end and won't derail a real usability session.
  • Example: /vt-c-webapp-testing
  1. visitrans-design-system — fix CD first; everything downstream inherits it.
  2. frontend-design / gemini-imagegen — polish and fill imagery gaps.
  3. design-iterator → figma-design-sync → design-implementation-reviewer — visual convergence, then parity, then review (only the ones whose trigger fires).
  4. container-logistics-ux-expert — domain critique, if the domain applies.
  5. webapp-testing — smoke test before validation.

Only step 1 and step 5 apply to almost every prototype; the middle steps are conditional on their triggers.

Worked example: refining a VisiMatch Consignee-Portal prototype

A narrated walkthrough of how a real refinement pass runs. This is a narration of the decisions and helper choices — not a captured screen recording. Effort estimates are rough per-step guides for planning.

Starting point: /vt-c-pd-3-prototype --feature consignee-portal has produced an Angular 21 + PrimeNG prototype of the VisiMatch Consignee-Portal (shipment list, detail view, document upload). It runs, but it looks like an untuned PrimeNG default and has stock imagery.

  1. CD compliance first — visitrans-design-system --validate (~10 min). Run the design-system validation against the prototype. It flags that the primary action buttons use PrimeNG blue instead of VisiMatch orange, the header logo is the generic VisiTrans mark rather than the VisiMatch lockup, and dark mode is missing the orange glow. Fix the tokens and logo lockup. Why first: every later screenshot the iterator takes should already be on-brand, or it will "fix" brand-correct colors back toward defaults.

  2. Polish the layout — frontend-design (~20 min). The shipment list is a bare table. Apply frontend-design guidance: give the list card rhythm, tighten the detail-view spacing, and establish a clear typographic hierarchy between shipment ID, status chip, and metadata. Why: the prototype now reads as a designed product, which makes the usability test about the flow rather than about the rough styling.

  3. Fill imagery — gemini-imagegen (~15 min). The empty-state for "no shipments yet" uses a broken placeholder. Generate a simple on-brand illustration for the empty state and a hero image for the portal landing. Why: placeholder gaps distract test participants and read as unfinished.

  4. Iterate visual gaps — design-iterator, 5 iterations (~25 min). After the manual passes above, the status chips and the document-upload zone still feel inconsistent — two manual tweaks did not converge. Dispatch the design-iterator agent for 5 iterations to systematically refine chip colors, upload-zone affordance, and overall balance. Why: this is exactly the "more than one or two manual changes without convergence" trigger — stop hand-tuning, let the iterator drive.

  5. (Skipped) Figma parity — figma-design-sync. There is no Figma source for the Consignee-Portal; this was a code-first prototype. Skip the sync step entirely. Why documented: recording the skip keeps the walkthrough honest about which triggers actually fired.

  6. (Skipped) Design-vs-Figma review — design-implementation-reviewer. Like figma-design-sync, this agent's workflow requires a Figma source — it diffs the running UI against Figma via the Figma MCP. This code-first prototype has none, so skip it too. Why documented: the two Figma-dependent helpers share one trigger, and on a code-first prototype the design-iterator screenshots in step 4 already cover the visual-review need.

  7. Domain critique — container-logistics-ux-expert (~20 min). The Consignee-Portal is squarely a container/logistics surface, so invoke the domain expert explicitly. It flags that "ETA" should be split into vessel-ETA vs. gate-ETA for consignees, and that the document-upload should surface the B/L number prominently. Apply the wording and field-priority fixes. Why: domain-correct terminology is invisible to a generic reviewer but obvious to real consignee users in the validation session.

  8. Smoke test — webapp-testing (~15 min). Finally, run webapp-testing to click through the three primary flows (browse shipments → open detail → upload a document). It surfaces one broken route on the upload confirmation; fix it. Why last: a dead click in a usability session wastes the participant's slot — the smoke test protects the pd-4 investment.

Then: /vt-c-pd-4-validate --plan to design the usability test on the now-refined prototype.

Total refinement effort for this example: roughly 2 hours, of which about half is the design-iterator and domain-expert passes.

Keeping this guide from going stale

If a helper is renamed or removed, this guide would silently point at a dead name. The tests/spec-134/ drift-guard test parses the canonical-helper table above (and the identical one in the pd-3 SKILL.md refinement block) and asserts every name still resolves — skills in skill-symlinks.manifest, agents as files under agents/. Prose drift is accepted; broken names fail the test. Run it with bash tests/spec-134/run.sh.