| 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.mdui-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)screentrigger (click/tap/submit/navigation/system event)from_stateto_stateexpected_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 IDUse CasePlatformFlowScreenStateTriggerFrom StateTo StateSituation/PurposeImage PathInput Image (for edits)Prompt PathSource (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_idscreentriggerhotspot (x, y, width, height)target_screentransition (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_idflowscreentriggerfrom_stateto_stateexpected next state imageacceptance checkopen 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 traceabilityui-prototypes/<prototype-name>/flow-maps/<platform>/<flow>.json for click-through linkageui-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.mdui-prototypes/<prototype-name>/image-prompt-manifest.mdui-prototypes/<prototype-name>/prompts/<platform>/<flow>/*.mdui-prototypes/<prototype-name>/flow-maps/<platform>/<flow>.jsonui-prototypes/<prototype-name>/viewer/<platform>/<flow>/index.htmlui-prototypes/<prototype-name>/viewer/<platform>/<flow>/viewer.cssui-prototypes/<prototype-name>/viewer/<platform>/<flow>/viewer.jsui-prototypes/<prototype-name>/images/web/<flow>/*.pngui-prototypes/<prototype-name>/images/ios/<flow>/*.pngui-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.
