design-compare

name	design-compare
description	This skill should be used when the user asks to "compare design with preview", "compare Figma with screenshot", "check design implementation", "compare design to implementation", "design review", or provides a Figma URL alongside a screenshot file for visual comparison.

Design Compare

Compare a Figma design screenshot against a local preview screenshot, producing a structured visual review and an interactive HTML comparison page.

Prerequisites

The export script requires a FIGMA_ACCESS_TOKEN env var. Store it in .env at the repo root:

FIGMA_ACCESS_TOKEN=figd_...

The script auto-loads .env from the repo root. Get a token from https://www.figma.com/developers/api#access-tokens

Workflow

Step 1: Obtain Both Images

Figma design image:

• Extract fileKey and nodeId from the Figma URL.
• Call mcp__figma__get_screenshot with the extracted parameters. The screenshot is returned inline in the conversation for visual comparison in Step 2.
• To save it as a file for the HTML page, run the export script:

  bash .claude/skills/design-compare/scripts/export-figma-node.sh <fileKey> <nodeId> /tmp/figma_design.png
  

  The script exports at 3x scale with use_absolute_bounds=true to match device pixel density and clip to exact frame bounds.
• If the script fails (no token), ask the user to provide a Figma screenshot file.

Preview image:

• If using Xcode MCP, call mcp__xcode__RenderPreview to render a fresh preview and use the returned previewSnapshotPath.
• Otherwise accept a preview image path from the user. Common location: preview.png at repo root.

Note: The Xcode preview canvas and Figma export produce different pixel dimensions and aspect ratios. This is expected — the normalize step in Step 4 handles it.

Step 2: Visual Comparison

Read/view both images (Figma inline screenshot + preview file) and analyze them. Evaluate:

1. Layout - positioning, alignment, spacing between elements
2. Typography - font sizes, weights, line heights, text content
3. Colors - backgrounds, text colors, tint colors, opacity
4. Components - buttons, toolbars, icons, navigation elements
5. Sizing - element dimensions, padding, margins

Step 3: Output Comparison Summary

Produce a structured summary with two sections:

Positive (matches): List aspects where the implementation matches the design.

Negative (mismatches): List aspects where the implementation diverges from the design, with specific details about what differs and how to fix it.

Keep each item concise (one line). Order by visual importance.

Step 4: Generate HTML Comparison Page

Generate an interactive HTML file for manual visual comparison. Both images must be available as files on disk.

1. Normalize images to the same height for accurate comparison:

   bash .claude/skills/design-compare/scripts/normalize-images.sh <figma_path> <preview_path> /tmp/figma_norm.png /tmp/preview_norm.png
   

2. Generate the HTML using Python (not sed — base64 strings exceed shell argument limits):

   python3 -c "
   template = open('.claude/skills/design-compare/assets/compare.html').read()
   import base64
   with open('/tmp/figma_norm.png','rb') as f: figma_b64 = base64.b64encode(f.read()).decode()
   with open('/tmp/preview_norm.png','rb') as f: preview_b64 = base64.b64encode(f.read()).decode()
   html = template.replace('{{FIGMA_IMAGE}}', f'data:image/png;base64,{figma_b64}')
   html = html.replace('{{PREVIEW_IMAGE}}', f'data:image/png;base64,{preview_b64}')
   open('design-compare.html','w').write(html)
   "
   

3. Open the file with open design-compare.html.

The HTML page provides two modes:

• Swipe (default) - drag a slider to reveal one image over the other
• Side by Side - both images displayed next to each other with labels