product-ui-prototyping（产品 UI 原型设计）

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.