# Product UI Prototyping > 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. - Skill: `autobyteus/product-ui-prototyping` (Agent Skill, multi-file: 6 files) - Install (CLI): `npx skillmds@latest add autobyteus/product-ui-prototyping` - Raw SKILL.md: https://api.skillmd.com/api/skills/autobyteus/product-ui-prototyping/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: autobyteus (https://skillmd.com/u/autobyteus) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/autobyteus/product-ui-prototyping --- # 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//` - Keep all prototype artifacts in that folder so each prototype remains self-contained. - Use clear kebab-case for ``. - Keep image assets separated by platform: - `ui-prototypes//images/web//...` - `ui-prototypes//images/ios//...` - `ui-prototypes//images/android//...` - Keep flow maps separated by platform and flow: - `ui-prototypes//flow-maps//.json` - Keep a manifest that maps each image to its exact generation/edit prompt: - `ui-prototypes//image-prompt-manifest.md` - `ui-prototypes//prompts///-.md` - If the user specifies a different location, follow the user-specified path. ## Input Strategy (Flexible) - If `ui-prototypes//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//.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//prompts///-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//images///-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//prompts///-.md` - Edit only state-relevant deltas: - Hover/focus rings - Pressed depth - Disabled contrast - Loading affordance - Validation/success/error messages - Save outputs as: - `ui-prototypes//images///-.png` - Speak completion after interaction-state set is physically written for the target platform+flow. ### 6) Maintain Image/Prompt Manifest (Required) - Maintain `ui-prototypes//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//flow-maps//.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//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//ui-prototype-spec.md` summary if the team requests a narrative overview - `ui-prototypes//image-prompt-manifest.md` for prompt/image traceability - `ui-prototypes//flow-maps//.json` for click-through linkage - `ui-prototypes//viewer///` 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//viewer///` - Configure each viewer instance to load its matching map file: - `../../../flow-maps//.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//viewer///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//ui-behavior-test-matrix.md` - `ui-prototypes//image-prompt-manifest.md` - `ui-prototypes//prompts///*.md` - `ui-prototypes//flow-maps//.json` - `ui-prototypes//viewer///index.html` - `ui-prototypes//viewer///viewer.css` - `ui-prototypes//viewer///viewer.js` - `ui-prototypes//images/web//*.png` - `ui-prototypes//images/ios//*.png` - `ui-prototypes//images/android//*.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//ui-behavior-test-matrix.md`, relevant `ui-prototypes//flow-maps//.json` files, `ui-prototypes//image-prompt-manifest.md`, and viewer behavior notes as inputs. - Speak final handoff completion after all required handoff artifacts are written.