Design Screenshot Spec

Purpose

Inspect live Figma designs or supplied screenshots, property panels, assets, and notes to produce a traceable Design Implementation Spec. Review the observed design as a product flow and resolve unspecified design and behavior decisions with the user before handing affected work to an implementer. The existing skill name remains stable for bundle compatibility.

When To Use

• The user sends screenshots of Figma frames, components, screens, or inspect panels.
• The user asks to analyze a visual design before implementation.
• The user provides a Figma file, frame, component, or prototype link and asks to inspect it or implement its design.
• The next step is frontend layout work and the implementer needs a structured spec.

When Not To Use

• The user asks to edit the design canvas, create files or whiteboards, generate a design system, or write Code Connect mappings.
• The user already provides a complete Design Implementation Spec and asks to implement it. Use frontend-layout-implementer.

Required Context

1. Read AGENTS.md.
2. Confirm the classified task is design-spec or design intake for later frontend implementation.
3. Read common/approved-patterns.md.
4. Read common/anti-patterns.md.
5. Read project/design-reference-profile.md when present.
6. Read references/spec-extraction-checklist.md.
7. For live links, read references/design-source-inspection.md.
8. For effects or a visual-effect mismatch, read references/effect-evidence.md.
9. After extraction, read references/product-behavior-review.md before formulating product questions or an implementation handoff.

Tool Contract

• Resolve live_design_source and design_reference_files through the current tool registry and tool-capabilities-manifest.json for the active source.
• A supplied link triggers scoped read-only inspection automatically: use a permitted provider selected by the current explicit role/tool instruction; otherwise use callable Figma MCP first with browser/computer-use fallback. Apply common/webdev-role-selection.md for an explicitly selected role.
• Browser fallback must support screenshots and pointer interaction with the canvas and property panel. Search results or an HTTP fetch are not inspection.
• With screenshots and no link, inspect those images directly; do not require a Figma connection. Never invent a tool, session, node, or successful read.
• Follow host tool instructions and permissions. Do not install tools, change access settings, edit the source canvas, or write mappings during intake.

Workflow

1. Inventory links, screenshots, inspect panels, exports, notes, target screens, and existing user decisions. Identify the requested frame and state scope.
2. Inspect live links using references/design-source-inspection.md; use supplied screenshots directly when no link exists. If neither source can be inspected, request the smallest missing reference and report the limitation.
3. Group evidence by screen, component, variant, state, and viewport. Record source ID, node or selected-layer identity, frame size, image crop/zoom when known, access path, and inspection coverage. Match property panels to their selected elements before assigning values. Inspect every in-scope component; reuse proven identical instances while recording overrides and state changes.
4. Treat each screenshot or design-frame size as a reference coordinate system, not as a production container cap. Record whether containment is explicitly visible and capture desktop edge anchors plus expected behavior beyond the reference viewport.
5. Extract visible layout, hierarchy, typography, color, spacing, sizing, radius, shadow, assets, states, and responsive behavior.
6. For typography, prefer copied inspect values or selected-text properties for font-family, font-size, font-weight, line-height, color, alignment, max width, and wrapping. When properties are unavailable, estimate from the screenshot and mark each estimate as screenshot-inferred.
7. For spacing, separate outside margins, section rhythm, inter-component gaps, container padding, and internal control padding instead of merging them into one generic gap value.
8. Mark values source-provided, screenshot-inferred, or unknown, with the exact source/selection and units; keep user decisions separately traceable.
9. Prefer exact properties only for the same node, state, mode, and revision. Reinspect mismatches; ask the user which reference governs unresolved conflicts.
10. Apply references/product-behavior-review.md: map observed actions and states, inspect available prototype transitions, then ask about every unresolved product/design decision needed for the requested scope. Keep recommendations unaccepted until the user answers; do not invent defaults.
11. Produce a draft spec with a decision register. Mark affected slices blocked until answers settle their dependencies. Continue independent inspection; never treat silence or a question limit as approval.
12. Hand off the resolved scope only when implementation was requested. Use frontend-design-director for requested redesign or visual choices that need proposals; source-fidelity work does not itself authorize redesign.

Output Contract

Final response: return only facts that affect the user's understanding, confidence, or next action. Omit empty fields and workflow narration.

Return a Design Implementation Spec with these sections:

• Source Inventory
• Component Evidence And Coverage
• Screen And Component Scope
• Layout Structure
• Typography
• Color And Effects (owning layers, ordered effects, bindings/modes, evidence states, proposed translation and unresolved differences)
• Spacing And Sizing
• Assets
• States And Interactions
• Product Questions And Decisions
• Responsive Behavior
• Accessibility Notes
• Implementation Acceptance Criteria
• Confidence And Unknowns

Keep detailed per-component evidence in the spec; user-facing questions should name the relevant component, observation, missing decision, and consequence.

Validation Gates

• Every concrete value must cite its source, selection/state, and confidence.
• A link-only request must attempt an available read path before requesting screenshots. Missing MCP alone must not block an available browser fallback.
• Each in-scope component/state is inspected or explicitly marked missing, unreadable, or blocked; an overview image is not complete extraction.
• Mixed selections and parent properties must not be attributed to a child.
• Source Inventory must record each screenshot's viewport or frame size when visible or provided.
• Spacing And Sizing must distinguish measured or estimated margins, section rhythm, inter-component gaps, container padding, and internal control padding with confidence labels.
• Typography must distinguish inspect-provided text properties from inferred font family, size, weight, line height, color, alignment, and wrapping.
• Responsive Behavior must include viewport-aware notes based on supplied screenshot widths, desktop edge anchors, and behavior beyond each reference viewport, and must mark inferred intermediate behavior explicitly.
• Screenshot or design-frame dimensions must not become runtime max-width, fixed container dimensions, or equivalent caps without source evidence of a centered container and an explicit responsive rationale.
• Missing states, assets, breakpoints, and token names must be explicit. Missing effect fields are unknown; inspect ancestors, instance overrides and actual effect types before proposing CSS. Never replace unread values with defaults.
• Unresolved product behavior, visual deviations, and inferred responsive or motion choices must be asked back and block their dependent implementation.
• A static screenshot does not establish transitions, timings, hidden forms, validation, persistence, or error recovery.
• The spec must be usable by frontend-layout-implementer without guessing the target layout intent.
• Report actual MCP/browser/image evidence and access gaps honestly; source inspection alone does not prove the implemented UI works.

Trigger Evals

Should trigger:

• "Here are Figma screenshots with dimensions and colors; write the layout spec."
• "Read these frame screenshots and inspect panels before coding."
• "Create a frontend implementation spec from these design screenshots."
• "Open this Figma node and inspect its components before coding."
• "MCP is unavailable; inspect the linked design in the browser."
• "Which layer do these property-panel values belong to?"

Should not trigger:

• "Implement this existing Design Implementation Spec."
• "Create a new Figma whiteboard."

Reference Map

• references/effect-evidence.md - layered effects and implementation evidence.
• common/webdev-role-selection.md - explicit conversational role preferences.
• references/spec-extraction-checklist.md
• references/design-source-inspection.md - live MCP and browser acquisition.
• references/product-behavior-review.md - evidence-led product questions and decision gates after extraction.
• skills/frontend-design-director/SKILL.md