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:

``bash mkdir -p "design-compare-reports//" bash "$SKILL_DIR/scripts/export-figma-node.sh" "" "" "design-compare-reports///_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 useabsolutebounds=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:

``bash cp "" "design-compare-reports///_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//. Images live in per-view subfolders (/).

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

``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, SCREENNAME → human-readable name, VIEWNAME → source file name (without extension), SLUG → file slug, FIGMA_URL` → full Figma URL.

For multiple screens, add entries to the screens array.

1. Copy the HTML template:

``bash cp "$SKILL_DIR/assets/compare.html" "design-compare-reports//report.html" ``

1. Open the file with open design-compare-reports//report.html.

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: artemnovichkov
• Source: artemnovichkov/skills
• License: MIT
• Homepage: http://skills.sh/

Install and usage instructions live in the source repository linked above.