Version: 2.0.0
visual-to-spec
Convert a finalized UI screenshot into a complete frontend implementation contract.
Trigger Conditions
- User provides a UI screenshot and asks to extract visual specs
- User asks to generate design tokens from a screenshot
- User asks to build a component tree or frontend implementation contract from a screenshot
- User asks to analyze screenshot layout, color, typography, spacing, overlay controls, or panorama/3D scene UI
- Keywords: "extract spec from screenshot", "image to design spec", "screenshot to spec"
Required Inputs
| Item |
Description |
| reference.png |
Finalized UI screenshot (the only required input) |
| Project token standards |
Optional, adapt to existing standards if available |
Outputs
All files written to 03_visual_spec/ directory:
| File |
Content |
| visual-analysis.md |
UI type, visible element evidence, composition, color, typography, spacing analysis |
| layout-spec.md |
Layout positioning and sizing spec, branching by UI type |
| component-tree.md |
Hierarchical component tree with per-component style summaries |
| tokens.json |
DTCG-inspired design tokens with source/confidence annotations |
| implementation-risks.md |
Implementation risk assessment |
| human-review-needed.md |
Low-confidence items and manual review checklist |
| DESIGN.md |
Summary document referencing all above files |
See references/output-files.md for detailed output formats.
Source of Truth
reference.png is the sole visual source of truth.
- Do not redesign.
- Do not treat UI elements invisible in the screenshot as screenshot facts.
- Do not introduce colors, fonts, spacing, panels, charts, or navigation structures absent from the image.
- Do not default to a dashboard / SaaS / three-column layout; UI type determination must come first.
reference-visible components must have bbox and visual evidence in the screenshot; components without bbox must not be labeled reference-visible.- Inferred implementation wrapper components (e.g., AppShell, MainContent, SceneImageLayer, OverlayLayer) are permitted but must be labeled
source: inferred-implementation.
- For image-led, panorama-scene, 3D exhibit, and product-render screenshots, output an asset strategy: which visual content must be raster/image assets, and which can be implemented as HTML/CSS/SVG.
All values must carry source and confidence annotations.
See references/source-strictness-rules.md for complete rules.
Phase Overview (9 phases, sequential)
| # |
Phase |
Key Output |
| 1 |
Global composition analysis + UI type determination + visible element evidence |
visual-analysis.md §1 |
| 2 |
Color extraction |
visual-analysis.md §2 + tokens.json (color) |
| 3 |
Typography extraction |
visual-analysis.md §3 + tokens.json (typography) |
| 4 |
Spacing and grid system |
visual-analysis.md §4 + tokens.json (spacing) |
| 5 |
Layout specification |
layout-spec.md |
| 6 |
Component tree construction |
component-tree.md |
| 7 |
Token merge and validation |
tokens.json (final) |
| 8 |
Implementation risk assessment |
implementation-risks.md |
| 9 |
Human review checklist |
human-review-needed.md |
See references/extraction-workflow.md for detailed workflow.
Hard Rules
- Every extracted value must include
source, confidence, confidenceLabel, and strictness.
reference-visible must include bbox or reference bbox within the same component detail; visibility claims without bbox are invalid.- Phase 1 must output
uiType, one of: application-dashboard, panorama-scene, image-led-landing, mobile-app, poster-like-ui, unknown.
- If
uiType is panorama-scene or image-led-landing, phases 5/6 must use the image layer + overlay layer layout model.
- Components not present in the screenshot must be listed in Rejected Assumptions, not placed in the component tree.
- Values with confidence < 0.6 must appear in
human-review-needed.md; low-confidence layout type must go into human review even if confidence >= 0.6.
- Every color in the component tree must exist in tokens.json.
- Every component dimension must match layout-spec.md.
- Sum of sibling component widths must not exceed parent container width; overlay components must verify bbox does not overflow.
- Typography scale must decrease monotonically: h1 > h2 > h3 > body.
- No orphan tokens (defined but unused).
- No missing tokens (used in component tree but undefined).
Capability Boundaries
See references/script-backed-boundary.md for detailed boundary definition.
| Category |
Examples |
| LLM can do |
Visual recognition, UI type determination, color estimation, layout judgment, component classification, proportion estimation |
| Script-assisted |
Precise color values, WCAG contrast, delta-E, exact pixel measurement, bbox measurement, visual regression comparison |
| Human confirmation |
Low-confidence colors, ambiguous component boundaries, uncertain font identification, whether the main visual needs real assets |
When scripts are unavailable, LLM does best-effort estimation and annotates confidence and notes.
Supporting Files Index
references/
extraction-workflow.md — 9-phase detailed workflow, UI type branching, asset strategy rulestoken-schema.md — Token JSON schema definition and field descriptionsoutput-files.md — Structure templates for each output filesource-strictness-rules.md — Complete rules for source/confidence/strictness/bbox labelsscript-backed-boundary.md — Boundary definitions for LLM / script / human operations
examples/
tokens.example.json — Complete tokens.json examplecomponent-tree.example.md — Component tree example, including panorama-scene vs dashboard branchinglayout-spec.example.md — Layout spec example, including overlay coordinate modelvisual-analysis.example.md — Visual analysis example, including UI type, visible elements, rejected assumptionshuman-review-needed.example.md — Human review checklist example
1---2name: visual-to-spec3description: Use when a user provides a reference UI screenshot and asks to extract visual specs, generate design tokens, create a component tree, or produce a frontend implementation contract, including dashboards, landing pages, mobile screens, image-led UIs, panorama scenes, 3D exhibit UIs, and screenshot-to-spec tasks.4---5Version: 2.0.067# visual-to-spec89Convert a finalized UI screenshot into a complete frontend implementation contract.1011## Trigger Conditions1213- User provides a UI screenshot and asks to extract visual specs14- User asks to generate design tokens from a screenshot15- User asks to build a component tree or frontend implementation contract from a screenshot16- User asks to analyze screenshot layout, color, typography, spacing, overlay controls, or panorama/3D scene UI17- Keywords: "extract spec from screenshot", "image to design spec", "screenshot to spec"1819## Required Inputs2021| Item | Description |22|------|-------------|23| reference.png | Finalized UI screenshot (the only required input) |24| Project token standards | Optional, adapt to existing standards if available |2526## Outputs2728All files written to `03_visual_spec/` directory:2930| File | Content |31|------|---------|32| visual-analysis.md | UI type, visible element evidence, composition, color, typography, spacing analysis |33| layout-spec.md | Layout positioning and sizing spec, branching by UI type |34| component-tree.md | Hierarchical component tree with per-component style summaries |35| tokens.json | DTCG-inspired design tokens with source/confidence annotations |36| implementation-risks.md | Implementation risk assessment |37| human-review-needed.md | Low-confidence items and manual review checklist |38| DESIGN.md | Summary document referencing all above files |3940See `references/output-files.md` for detailed output formats.4142## Source of Truth4344**reference.png is the sole visual source of truth.**4546- Do not redesign.47- Do not treat UI elements invisible in the screenshot as screenshot facts.48- Do not introduce colors, fonts, spacing, panels, charts, or navigation structures absent from the image.49- Do not default to a dashboard / SaaS / three-column layout; UI type determination must come first.50- `reference-visible` components must have bbox and visual evidence in the screenshot; components without bbox must not be labeled `reference-visible`.51- Inferred implementation wrapper components (e.g., AppShell, MainContent, SceneImageLayer, OverlayLayer) are permitted but must be labeled `source: inferred-implementation`.52- For image-led, panorama-scene, 3D exhibit, and product-render screenshots, output an asset strategy: which visual content must be raster/image assets, and which can be implemented as HTML/CSS/SVG.5354All values must carry source and confidence annotations.55See `references/source-strictness-rules.md` for complete rules.5657## Phase Overview (9 phases, sequential)5859| # | Phase | Key Output |60|---|-------|------------|61| 1 | Global composition analysis + UI type determination + visible element evidence | visual-analysis.md §1 |62| 2 | Color extraction | visual-analysis.md §2 + tokens.json (color) |63| 3 | Typography extraction | visual-analysis.md §3 + tokens.json (typography) |64| 4 | Spacing and grid system | visual-analysis.md §4 + tokens.json (spacing) |65| 5 | Layout specification | layout-spec.md |66| 6 | Component tree construction | component-tree.md |67| 7 | Token merge and validation | tokens.json (final) |68| 8 | Implementation risk assessment | implementation-risks.md |69| 9 | Human review checklist | human-review-needed.md |7071See `references/extraction-workflow.md` for detailed workflow.7273## Hard Rules74751. Every extracted value must include `source`, `confidence`, `confidenceLabel`, and `strictness`.762. `reference-visible` must include bbox or reference bbox within the same component detail; visibility claims without bbox are invalid.773. Phase 1 must output `uiType`, one of: `application-dashboard`, `panorama-scene`, `image-led-landing`, `mobile-app`, `poster-like-ui`, `unknown`.784. If `uiType` is `panorama-scene` or `image-led-landing`, phases 5/6 must use the image layer + overlay layer layout model.795. Components not present in the screenshot must be listed in Rejected Assumptions, not placed in the component tree.806. Values with confidence < 0.6 must appear in `human-review-needed.md`; low-confidence layout type must go into human review even if confidence >= 0.6.817. Every color in the component tree must exist in tokens.json.828. Every component dimension must match layout-spec.md.839. Sum of sibling component widths must not exceed parent container width; overlay components must verify bbox does not overflow.8410. Typography scale must decrease monotonically: h1 > h2 > h3 > body.8511. No orphan tokens (defined but unused).8612. No missing tokens (used in component tree but undefined).8788## Capability Boundaries8990See `references/script-backed-boundary.md` for detailed boundary definition.9192| Category | Examples |93|----------|----------|94| LLM can do | Visual recognition, UI type determination, color estimation, layout judgment, component classification, proportion estimation |95| Script-assisted | Precise color values, WCAG contrast, delta-E, exact pixel measurement, bbox measurement, visual regression comparison |96| Human confirmation | Low-confidence colors, ambiguous component boundaries, uncertain font identification, whether the main visual needs real assets |9798When scripts are unavailable, LLM does best-effort estimation and annotates confidence and notes.99100## Supporting Files Index101102### references/103- `extraction-workflow.md` — 9-phase detailed workflow, UI type branching, asset strategy rules104- `token-schema.md` — Token JSON schema definition and field descriptions105- `output-files.md` — Structure templates for each output file106- `source-strictness-rules.md` — Complete rules for source/confidence/strictness/bbox labels107- `script-backed-boundary.md` — Boundary definitions for LLM / script / human operations108109### examples/110- `tokens.example.json` — Complete tokens.json example111- `component-tree.example.md` — Component tree example, including panorama-scene vs dashboard branching112- `layout-spec.example.md` — Layout spec example, including overlay coordinate model113- `visual-analysis.example.md` — Visual analysis example, including UI type, visible elements, rejected assumptions114- `human-review-needed.example.md` — Human review checklist example
jason904