design-compare

Design Compare

Compare Figma design screenshots against local preview screenshots, producing a structured visual review and an interactive HTML comparison page. Supports multiple screens in a single report.

Setup

$SKILL_DIR refers to the directory containing this SKILL.md file. Resolve it based on where the skill is installed (e.g. .claude/skills/design-compare, .agents/skills/design-compare, etc.).

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

Important: Ensure .env is listed in .gitignore to avoid committing tokens.

Workflow

Step 1: Obtain Images for Each Screen

Repeat for each screen being compared. Use a slug (e.g. empty-state, list-view) to name files.

Derive the report folder from the project or context name, e.g. design-compare-reports/LayoutCheckExample/. Within this folder, store images in per-view subfolders named after the source file (without extension), e.g. ContentView/, SliderView/. The report folder holds a single shared config.js and report.html.

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 for visual comparison in Step 2.
• To save it as a file for the HTML page, run the export script:

  mkdir -p "design-compare-reports/<ReportName>/<ViewName>"
  bash "$SKILL_DIR/scripts/export-figma-node.sh" "<fileKey>" "<nodeId>" "design-compare-reports/<ReportName>/<ViewName>/<slug>_figma.png"
  

  The script validates that fileKey is alphanumeric (with hyphens/underscores) and nodeId matches digit-colon/hyphen patterns. Invalid inputs are rejected. 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.
• Copy to the report folder:

  cp "<preview_path>" "design-compare-reports/<ReportName>/<ViewName>/<slug>_preview.png"
  

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 single markdown table ordered by visual importance:

Status	Aspect	Detail
✅	Layout alignment	Matches design
❌	Background color	Expected #1A1A1A, got #FFFFFF

Use ✅ for matches, ❌ for mismatches. Keep each row concise (one line). For mismatches, include what differs and how to fix it.

Step 4: Generate HTML Comparison Page

All shared artifacts (config.js, report.html) are stored in design-compare-reports/<ReportName>/. Images live in per-view subfolders (<ViewName>/).

1. Generate config.js with screen metadata. Image paths use the <ViewName>/ prefix. Write the following JavaScript to design-compare-reports/<ReportName>/config.js:

   // config.js — generated by design-compare skill
   const reportConfig = {
     generatedAt: "TIMESTAMP",       // replace with current date/time
     screens: [
       {
         name: "SCREEN_NAME",        // replace with human-readable name
         figma: "VIEW_NAME/SLUG_figma.png",
         preview: "VIEW_NAME/SLUG_preview.png",
         figmaUrl: "FIGMA_URL"       // replace with full Figma URL for the node
       }
     ]
   };
   

   Replace placeholders: TIMESTAMP → current date/time, SCREEN_NAME → human-readable name, VIEW_NAME → source file name (without extension), SLUG → file slug, FIGMA_URL → full Figma URL.

   For multiple screens, add entries to the screens array.

2. Copy the HTML template:

   cp "$SKILL_DIR/assets/compare.html" "design-compare-reports/<ReportName>/report.html"
   

3. Open the file with open design-compare-reports/<ReportName>/report.html.

The HTML page provides swipe (default) and side-by-side comparison modes, screen tabs for multi-screen reports, and direct Figma links.