product-ui-prototyping

What this skill does

# 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 fl