---
name: product-ui-prototyping
description: "Design and validate product UI behavior as visual state prototypes before coding. Use when tasks ask how screens should change after user actions (click, tap, submit), when non-developers need to review web/iOS/Android UX flows, or when teams need interaction-state assets and acceptance checks for implementation."
---

# Product UI Prototyping

## Overview

Turn product ideas into testable UI behavior using generated and edited screen images. Produce state-by-state visuals, click-through transition logic, and per-platform viewers that teams can navigate end-to-end before implementation.

## Prototype Folder Convention (Project-Local)

- For each prototype effort, create/use one folder under the current project's `ui-prototypes/` directory:
  - `ui-prototypes/<prototype-name>/`
- Keep all prototype artifacts in that folder so each prototype remains self-contained.
- Use clear kebab-case for `<prototype-name>`.
- Keep image assets separated by platform:
  - `ui-prototypes/<prototype-name>/images/web/<flow>/...`
  - `ui-prototypes/<prototype-name>/images/ios/<flow>/...`
  - `ui-prototypes/<prototype-name>/images/android/<flow>/...`
- Keep flow maps separated by platform and flow:
  - `ui-prototypes/<prototype-name>/flow-maps/<platform>/<flow>.json`
- Keep a manifest that maps each image to its exact generation/edit prompt:
  - `ui-prototypes/<prototype-name>/image-prompt-manifest.md`
  - `ui-prototypes/<prototype-name>/prompts/<platform>/<flow>/<screen>-<state>.md`
- If the user specifies a different location, follow the user-specified path.

## Input Strategy (Flexible)

- If `ui-prototypes/<prototype-name>/experience-story.md` exists, use it as upstream source for screens, actions, and transitions.
- If it does not exist, proceed directly and define screens/transitions in this workflow.
- Do not block prototyping on any specific upstream file.

## Workflow

### Audible Notifications (Speak Tool, Required)

- Use the `Speak` tool for key stage-boundary status so the user does not need to watch the screen continuously.
- Hard rule: speak at both stage start and stage completion for each key stage below (no selective skipping).
- Required speak stages:
  - workflow kickoff (`prototype target acknowledged`, `next stage`),
  - transition model stage (`started`, then `ui-behavior-test-matrix.md` drafted/updated),
  - baseline screen stage for each platform+flow (`started`, then baseline set written),
  - interaction-state stage for each platform+flow (`started`, then state set written),
  - manifest synchronization stage (`started`, then `image-prompt-manifest.md` updated and consistent),
  - click-through bundle stage (`started`, then flow-map + viewer written),
  - viewer smoke test stage (`started`, then `Pass`/`Fail` result),
  - final handoff stage (`started`, then package-ready completion).
- Speak trigger policy:
  - do not skip required stage-boundary speak events,
  - for completion events, speak only after the milestone is durably completed (files written + relevant checks known),
  - do not speak for partial drafts or intermediate prompt iterations between required stage-boundary events,
  - batch close-together milestone updates into one short message.
- Keep each spoken message short (1-2 sentences), status-first, with one clear next step.
- If the `Speak` tool fails or is unavailable, continue workflow and provide the same update in text.
- Do not speak secrets, tokens, or full sensitive payloads.

### Tool Execution Discipline

- Execute image tool calls strictly one at a time.
- Do not run multiple generate/edit image calls in parallel for different screens/states.
- Wait for each call to finish, inspect the output, then issue the next call.
- For multi-screen/multi-state batches, process a deterministic queue sequentially.
- When calling image tools, always use absolute filesystem paths.
- Always pass an absolute `output_file_path` for generated/edited images.
- For edit calls, use absolute paths for source images.

### Prompt Lineage And Update Discipline

- For iterative updates, default to `edit image` anchored to the latest approved source image ("shell").
- Use `generate image` for first drafts, major structural resets, or when repeated edit attempts cannot recover accuracy.
- Before updating an image, read the current prompt from manifest `Prompt Path` and identify its `Parent Image` (if any).
- Create the next prompt by updating the current prompt (preserve unchanged constraints, modify only requested deltas, and explicitly call out unchanged regions).
- Save the updated prompt back to the same prompt path as latest source of truth.
- For edit operations, prompt files must document:
  - Human intent header: `UI Purpose`, `User Can Do`, `Transition Outcome`
  - Transition metadata: `Trigger`, `From State`, `To State`
  - I/O linkage: `Input Image`, intended `Output Image`
- For replacement updates, write the new image to the same image path unless the user explicitly asks for a new variant.
- Do not create version-sprawl prompt files (`v2`, `v3`, etc.) unless the user explicitly requests branching.
- Keep one canonical shell per screen/flow and derive state variants from that shell or its approved descendants.

### Transition Traceability Model

- Treat documentation as four linked layers:
  - Canonical behavior intent: `ui-behavior-test-matrix.md` (`transition_id`, trigger, from/to state, acceptance checks)
  - Navigation runtime: `flow-maps/<platform>/<flow>.json` transitions derived from the behavior matrix
  - Edit execution: prompt file for the target state (exact edit prompt + transition metadata)
  - Artifact lineage: `image-prompt-manifest.md` (input/output image paths and parent linkage)
- Use the same `transition_id` across all four layers for one transition.
- If reusing the same image path across iterations, keep latest output on disk and append an iteration log section in the prompt file (short delta summary + previous input image path).

### Artifact Lifecycle Discipline (Required)

- Keep only active artifacts that match the latest product vision and current valid use cases.
- When a use case/flow/screen/state becomes invalid, deprecated, or obsolete, delete its files from:
  - `images/`
  - `prompts/`
  - `flow-maps/`
  - `viewer/` (if the flow is removed)
- Do not keep deprecated artifacts "just in case" unless the user explicitly asks to archive them.
- If naming is stale or unclear, rename files/folders to reflect current product language and use-case intent.
- After any rename or deletion, update all references in the same change:
  - `image-prompt-manifest.md`
  - flow-map `screens[].image` paths
  - viewer map path configuration
- Prefer stable, descriptive kebab-case names that communicate platform, flow, screen, and state.

### Aspect Ratio Discipline

- Specify an explicit aspect ratio in every image generation prompt.
- Use only supported ratios: `1:1`, `4:3`, `3:4`, `3:2`, `2:3`, `5:4`, `4:5`, `16:9`, `9:16`, `21:9`.
- For each platform + flow, keep one fixed ratio across all screens/states to avoid distortion drift.
- For edits, keep the same ratio as the baseline source image.
- Do not normalize, stretch, or re-encode generated images unless the user explicitly asks.

### 1) Define Product Intent And Constraints

- Define target platform (`web`, `ios`, `android`) and viewport assumptions.
- Define target aspect ratio per platform/flow from the supported ratio list.
- Define user personas, primary jobs-to-be-done, and critical paths.
- Define design constraints: brand tone, accessibility needs, component style, and data density.
- Define fidelity level (`wireframe`, `mid`, `high`) before generating assets.
- Define the platform+flow bundles that must be navigable in local viewers.

### 2) Map Screens, Actions, And States

- Create a state transition table for each flow:
  - `transition_id` (stable key, e.g., `gateway_validate_to_success`)
  - `screen`
  - `trigger` (click/tap/submit/navigation/system event)
  - `from_state`
  - `to_state`
  - `expected_feedback` (visual + microcopy)
- Treat this table as canonical and keep all map/manifest transition IDs aligned to it.
- Cover at minimum: `default`, `focus`, `pressed`, `disabled`, `loading`, `success`, `error`, and `empty` where applicable.
- Prioritize one critical flow first, then expand to secondary flows.

### 3) Create One Canonical Product Base Spec And Shell Lock

- Build one reusable `product_base_spec` (platform, viewport, typography, spacing, tokens, accessibility intent).
- Reuse the same base spec in all generate/edit prompts to prevent style drift between screens.
- For each screen, create and lock a canonical shell image before state branching.
- If the initial generation is not accurate, iteratively edit the same shell until layout and visual identity are stable.

### 4) Generate Baseline Screens

- Generate net-new screen drafts with the image generation tool.
- If a draft is not accurate enough, refine it with iterative `edit image` passes until the canonical shell is locked.
- Run baseline work sequentially: one screen per tool call, then review result before the next.
- Include explicit ratio in each generation prompt and keep it constant for that platform + flow.
- Use absolute `output_file_path` in every generation/edit tool call.
- Save the exact prompt used for each baseline image to:
  - `ui-prototypes/<prototype-name>/prompts/<platform>/<flow>/<screen>-default.md`
- Use deterministic style instructions and the shared base spec to keep typography, spacing, iconography, and color consistent across screens.
- Save locked shell outputs in a stable structure:
  - `ui-prototypes/<prototype-name>/images/<platform>/<flow>/<screen>-default.png`
- Speak completion after baseline screen set is physically written for the target platform+flow.

### 5) Create Interaction States From Baselines

- For iterative state updates, default to `edit image` from the locked shell (or latest approved state predecessor).
- Use `generate image` for state creation only when a state requires intentional structural divergence.
- Preserve layout and visual identity continuity by carrying forward unchanged constraints and fixed shell elements in the updated prompt.
- Run state updates sequentially: one tool call per update, then review result before the next.
- Preserve the source image ratio for every edit call.
- Use absolute paths for edit inputs and `output_file_path`.
- For each edit call, record tool-call inputs/outputs in the manifest row:
  - `Input Image` (required)
  - `Output Image` (same as `Image Path` unless branching)
- Ensure every edited state maps to one transition tuple:
  - (`transition_id`, `trigger`, `from_state`, `to_state`)
- Save the exact prompt used for each edited image to:
  - `ui-prototypes/<prototype-name>/prompts/<platform>/<flow>/<screen>-<state>.md`
- Edit only state-relevant deltas:
  - Hover/focus rings
  - Pressed depth
  - Disabled contrast
  - Loading affordance
  - Validation/success/error messages
- Save outputs as:
  - `ui-prototypes/<prototype-name>/images/<platform>/<flow>/<screen>-<state>.png`
- Speak completion after interaction-state set is physically written for the target platform+flow.

### 6) Maintain Image/Prompt Manifest (Required)

- Maintain `ui-prototypes/<prototype-name>/image-prompt-manifest.md` in real time.
- Treat this manifest as the latest source of truth (current artifact set only).
- Add one row per image artifact (`default` and each edited state).
- For each row, record at minimum:
  - `Transition ID`
  - `Use Case`
  - `Platform`
  - `Flow`
  - `Screen`
  - `State`
  - `Trigger`
  - `From State`
  - `To State`
  - `Situation/Purpose`
  - `Image Path`
  - `Input Image` (for edits)
  - `Prompt Path`
  - `Source` (`Generate`/`Edit`)
  - `Parent Image` (for edited states)
- Ensure every image in `images/` has exactly one matching manifest row.
- Ensure every `Edit` row has a non-empty `Input Image` and transition tuple (`Trigger`, `From State`, `To State`).
- For replacement updates, update the existing manifest row instead of creating a new row.
- Remove stale/legacy rows when images or prompts are replaced or deleted.
- Keep only active image/prompt pairs for the current prototype revision.
- When artifacts are deleted or renamed, update/remove rows immediately so manifest and filesystem stay 1:1.
- Speak completion after manifest synchronization is physically written and consistent with current artifacts.

### 7) Connect Screens For Click-Through Simulation

- Create one flow map per platform+flow:
  - `ui-prototypes/<prototype-name>/flow-maps/<platform>/<flow>.json`
- Derive map transitions from `ui-behavior-test-matrix.md`; do not maintain an independent transition definition.
- Include per-link definitions:
  - `transition_id`
  - `screen`
  - `trigger`
  - `hotspot` (`x`, `y`, `width`, `height`)
  - `target_screen`
  - `transition` (`instant`, `fade`, `slide`)
- Keep hotspot naming deterministic so non-developers can review and iterate quickly.

### 8) Assemble Behavior Test Matrix

- Produce `ui-prototypes/<prototype-name>/ui-behavior-test-matrix.md` with one row per transition.
- Treat this file as the canonical transition source of truth.
- Include:
  - `transition_id`
  - `flow`
  - `screen`
  - `trigger`
  - `from_state`
  - `to_state`
  - `expected next state image`
  - `acceptance check`
  - `open question / risk`
- Mark blocking issues where any trigger has ambiguous or missing feedback.
- Speak completion after `ui-behavior-test-matrix.md` is physically written/updated.

### 9) Deliver Review Package For Non-Developers

- Produce a concise review packet:
  - Optional: `ui-prototypes/<prototype-name>/ui-prototype-spec.md` summary if the team requests a narrative overview
  - `ui-prototypes/<prototype-name>/image-prompt-manifest.md` for prompt/image traceability
  - `ui-prototypes/<prototype-name>/flow-maps/<platform>/<flow>.json` for click-through linkage
  - `ui-prototypes/<prototype-name>/viewer/<platform>/<flow>/` local click-through viewer files
  - Image gallery links grouped by flow and platform
  - Explicit unresolved decisions for product/design sign-off
- Keep wording product-facing and avoid implementation jargon when possible.

### 10) Publish Local Click-Through Viewer

- For each platform+flow image set, copy the viewer template into:
  - `ui-prototypes/<prototype-name>/viewer/<platform>/<flow>/`
- Configure each viewer instance to load its matching map file:
  - `../../../flow-maps/<platform>/<flow>.json`
- In viewer code, always resolve map/image URLs from an absolute base URL:
  - build map URL with `new URL(mapPath, window.location.href)`
  - resolve each `screens[].image` against the resolved map URL
- Serve the workspace root locally and open:
  - `http://localhost:4173/ui-prototypes/<prototype-name>/viewer/<platform>/<flow>/index.html`
- Use per-platform/per-flow viewers for product/design review so each image set can be reviewed directly.
- Speak completion after flow-map + viewer files are physically written for the target platform+flow.

### 11) Viewer Smoke Test (Required)

- Run syntax check on viewer JavaScript before handoff.
- Serve the project locally and verify at least:
  - viewer page loads,
  - flow-map JSON loads,
  - one referenced image loads,
  - start screen renders with no URL-resolution errors.
- If any check fails, fix viewer path resolution before delivery.
- Speak the viewer smoke-test result (`Pass`/`Fail`) after checks complete.

## Prompt Patterns And Checklists

- Read and reuse `references/prompt-patterns.md` for:
  - UX criteria coverage and product base spec
  - Production screen generation and state edit templates
  - Shell-lock and iterative edit prompt patterns
  - Image/prompt manifest template and logging checklist
  - Flow-step and cross-platform adaptation templates
  - Click-through flow map template, viewer compatibility rules, and acceptance checklist

## Default Outputs

- `ui-prototypes/<prototype-name>/ui-behavior-test-matrix.md`
- `ui-prototypes/<prototype-name>/image-prompt-manifest.md`
- `ui-prototypes/<prototype-name>/prompts/<platform>/<flow>/*.md`
- `ui-prototypes/<prototype-name>/flow-maps/<platform>/<flow>.json`
- `ui-prototypes/<prototype-name>/viewer/<platform>/<flow>/index.html`
- `ui-prototypes/<prototype-name>/viewer/<platform>/<flow>/viewer.css`
- `ui-prototypes/<prototype-name>/viewer/<platform>/<flow>/viewer.js`
- `ui-prototypes/<prototype-name>/images/web/<flow>/*.png`
- `ui-prototypes/<prototype-name>/images/ios/<flow>/*.png`
- `ui-prototypes/<prototype-name>/images/android/<flow>/*.png`

## Quality Gate

- Ensure every critical trigger produces clear, visible feedback within one state transition.
- Ensure states are visually consistent across platforms and flows.
- Ensure aspect ratio is explicitly defined and consistent for each platform + flow.
- Ensure no generated image is normalized/stretched in a way that distorts UI geometry.
- Ensure every image has a corresponding prompt record in `image-prompt-manifest.md`.
- Ensure manifest contains only latest active artifacts (no stale legacy entries).
- Ensure each iterative update prompt is derived from the current prompt referenced by manifest `Prompt Path`.
- Ensure each state image preserves shell continuity (layout/frame/spacing/component geometry) unless a deliberate structural change is documented.
- Ensure each edited image has traceable lineage: `Parent Image` + `Input Image` + (`Trigger`, `From State`, `To State`).
- Ensure each manifest `Transition ID` exists in `ui-behavior-test-matrix.md`.
- Ensure each flow-map transition corresponds to a matrix `transition_id` and matching trigger semantics.
- Ensure no obsolete/deprecated artifacts remain for removed or invalidated use cases.
- Ensure file/folder names reflect latest product vision and are consistent across images, prompts, maps, and viewers.
- Ensure error and empty states include recovery guidance.
- Ensure accessibility cues (focus visibility, contrast intent, readable hierarchy) are represented in mockups.
- Ensure each click-through trigger in each flow map points to a valid target screen.
- Ensure viewer navigation works for each clickable hotspot and start screen in each platform+flow viewer.
- Ensure viewer smoke tests pass for each platform+flow bundle.

## Handoff

- Hand off approved behavior specs and state assets to implementation.
- If engineering planning is requested next, invoke `$software-engineering-workflow-skill` with `ui-prototypes/<prototype-name>/ui-behavior-test-matrix.md`, relevant `ui-prototypes/<prototype-name>/flow-maps/<platform>/<flow>.json` files, `ui-prototypes/<prototype-name>/image-prompt-manifest.md`, and viewer behavior notes as inputs.
- Speak final handoff completion after all required handoff artifacts are written.