screenshot-to-prototype

Screenshot To Prototype

Restore a runnable prototype from a local screenshot. First complete a 1:1 absolutely positioned visual draft under a fixed viewport, then convert it to React; prioritize effect, keep review information concentrated in the main spec, use Chinese for the body text, and keep it concise.

Scope

Only handle local screenshots or design drafts that the user explicitly requests to restore. Ordinary image materials, style references, URL cloning, and theme extraction do not trigger this skill.
Obtain the local path of the source image; chat attachments must first be saved locally. The source image itself is the visual basis, and no additional request is made to select a theme or create a design specification.
When bitmap materials need to be generated, edited, or derived, use ui-image-generation; tool selection, config reading, and fallback rules all follow that skill. Screenshot restoration only supplements the constraints for local source images, bbox, cropping, repair, and material triage.
All material extraction, repair, upscaling, and design analysis must pass the user's local image path as the reference image; materials must not be generated from a text description alone.
For screenshots, prefer the Axhub Preview MCP's preview_capture; only switch to the existing browser screenshot capability when the built-in screenshot does not support the current content.

Use the main spec

Follow rules/requirements-alignment-guide.md. If .spec/spec.html already exists, extend it directly; if not, create it from the general HTML template. Do not modify the general spec template.
Use data-page-target and data-spec-pageas needed for the current project. Do not prescribe a fixed number of pages or page names.
The spec displays the source image information, the absolutely positioned visual draft, the final materials and their uses, and places the original image and the real running screenshot side by side, left and right, to form a quick result comparison.
The material review area displays candidates and the final real content item by item using the same preview box, left and right; transparent materials use a checkerboard background, and the name or ID, use/source, and output dimensions are labeled. Images, SVGs, and components must all actually render; do not provide only text, file names, or paths.
The visual draft stage equals the source image viewport, using position: relative and overflow: hidden; elements are absolutely positioned and retain stable data-reconstruction-id。
Result comparison is ordinary spec content; do not establish per-element or global approval states. When the user has comments, iterate according to the comments.
When the user requests to see the visual draft first, stop at the spec stage; when the user explicitly requests the complete prototype, there is no need to wait for additional confirmation, and after updating the result comparison, continue with the React implementation.

Work steps

Read the source image, existing specs, related prototypes, and materials. Write preprocessing results to a local temporary directory:

node .agents/skills/screenshot-to-prototype/scripts/prepare-reconstruction-source.mjs \
  --input <source.png> \
  --output .local/screenshot-to-prototype/<slug>/source-summary.json

The image AI determines the specific extraction targets; only the filtering rules are explained: first route by UI responsibility, then choose the representation method by visual complexity; information and interaction structures use HTML/CSS, interface graphics use SVG, and only content media and decorative visuals that are difficult to quickly and reliably reproduce with HTML/CSS become bitmap candidates.
Bitmaps are cropped individually by bbox by default. Only when multiple independent decorative bitmaps exist on the same screen and are suitable for batch separation, use slice-asset-sheet.mjs or slice-alpha-components.mjs; candidates and candidate-manifest.json are placed in .local/。
Use audit-assets.mjs to audit candidates. Key-color transparency is used only when a candidate needs a transparent background and the current background color is continuous and pure; first run probe-key-color.mjs, then run key-transparent-image.mjs。
Organize element bboxes, candidates, and selection results into the local elements.json, then build and verify the restoration mapping:

node .agents/skills/screenshot-to-prototype/scripts/build-reconstruction-manifest.mjs \
  --source-summary .local/screenshot-to-prototype/<slug>/source-summary.json \
  --elements .local/screenshot-to-prototype/<slug>/elements.json \
  --output src/prototypes/<slug>/.spec/reconstruction/reconstruction-manifest.json

node .agents/skills/screenshot-to-prototype/scripts/validate-reconstruction-manifest.mjs \
  --manifest src/prototypes/<slug>/.spec/reconstruction/reconstruction-manifest.json \
  --project-root src/prototypes/<slug> \
  --source <source.png>

When generated candidates exist, append --generation-artifacts src/prototypes/<slug>/.spec/generation-artifacts.json。

In spec.html , implement the absolutely positioned visual draft. When Tailwind is needed, run compile-reconstruction-tailwind.mjs, use an independent prefix; do not use the Tailwind CDN, and do not load Tailwind preflight.
Call preview_capture, capture the spec visual page according to the source image viewport at DPR 1, and output to .spec/reconstruction/visual-check/render.png. If the screenshot is empty, has the wrong size, or has diagnostic anomalies, fix the capture issue first.
In the current spec.html , add a quick results comparison area, referencing only the stable original image and render.png; the two images use the same viewport and scale, placed side by side left and right, without creating a separate comparison document.
Convert to real text, React components, Grid/Flex, CSS variables, responsive constraints, and interaction states. React does not reference .local/, nor does it keep editable UI as a whole-block screenshot. After completion, take another screenshot at the same viewport and update the results comparison in the spec.

Asset strategy

First route by UI responsibility, then handle by visual complexity; do not use "looks complex" as the basis for bitmap conversion.
Text, buttons, input fields, navigation, cards, lists, and tables use HTML/CSS; icons, logos, progress indicators, and simple charts preferentially use existing icon libraries or SVG.
Photos, avatars, product images, illustrations, textures, and screenshots embedded in the page use bitmaps, retaining clean-cropby default; when repair is needed, add generated-refined。
Secondary image generation always passes in the local source image, and does not generate UI copy, controls, generic icons, or data content; the output aspect ratio and clarity are determined by the target bbox and DPR.
When a solid-color generated background needs to be made transparent, use generated-chromawhen other methods are insufficient for continuous complex backgrounds clean-plate。
flatten-in-page is only used for the first-stage visual draft; the final React restores text, controls, repeated structures, and data graphics that need interaction.
Final file-based assets are placed directly into the prototype assets/, and their usage locations and trade-offs are written into the main spec.

Mapping

reconstruction-manifest.json only stores the source image hash/viewport, as well as the element's bbox, representation method, candidates,selectedCandidateId、specElementId and React target. The validator checks out-of-bounds, missing resources, generation records, unknown routes, duplicate element IDs, candidate audits, and source image hash.

Delivery

The final reply provides the spec link, the original image and the real running screenshot, as well as a lightweight deviation explanation. Explain still-visible issues by P0-P3; do not create a separate summary document.

About this skill