figma-pixel-perfect
Iterative pixel-perfect implementation of Figma designs. Covers the full lifecycle: screen decomposition, component extraction, fixture data population, Playwright visual regression testing with pixel
SKILL.mdpackages/skills/figma-pixel-perfect/SKILL.md
GitHubFigma Pixel-Perfect Implementation
End-to-end workflow for translating Figma designs into production code with verified visual
fidelity. Builds on figma-implement-design by adding a closed-loop verification cycle
with measurable convergence targets.
Architecture: Three Tool Layers
| Layer | Tool | What It Does | Who Can Use It |
|---|---|---|---|
| Design Source | Figma MCP (get_design_context, get_screenshot, get_metadata) |
Read design intent: layout, tokens, screenshots | Main session ONLY — subagents cannot access MCP |
| Design Export | Figma REST API (/v1/images/:fileKey) |
Download node PNGs to disk at 2x scale | Main session or subagents (with token) |
| Verification | Playwright (toHaveScreenshot() with pixelmatch) |
Compare browser render against Figma baseline | Main session or subagents |
Critical Constraint: Subagent MCP Access
Subagents (dispatched via Agent tool) CANNOT access Figma MCP tools. Only the main orchestrating session has MCP access. This means:
- The main session must fetch all Figma data (screenshots, design context, metadata) and save it to disk BEFORE dispatching subagents.
- Subagents work from committed files — baseline PNGs, design context JSON, fixture data.
- If a subagent needs additional Figma data, it must request it and wait for the main session to fetch it.
Figma REST API vs MCP
| REST API | MCP | |
|---|---|---|
| Auth | Personal access token (X-Figma-Token header) |
OAuth via remote server |
| Rate limit | ~30 req/min on /v1/images/ (per account, not per token) |
Separate limit, unaffected by REST |
| Output | JSON with S3 URLs → download PNGs to disk | Inline images in conversation |
| Use for | Batch downloading baselines to commit | Viewing designs inline, getting design context |
| Subagent access | Yes (pass token in prompt) | No |
Rate limit recovery: /v1/images/ returns retry-after header (can be hours on Pro plan).
Use a secondary account's token if available. The /v1/files/ and /v1/me endpoints have
separate, more generous limits.
Phase 0: Screen Decomposition (Main Session)
Goal: Break Figma designs into a hierarchy of testable units.
Step 1: Identify Target Screens
Start with the container node (section or page) that holds all screens. Use get_metadata
to discover the full inventory:
get_metadata(fileKey, containerNodeId)
Catalog every 1920x1080 frame. For each, note:
- Node ID
- Name (e.g., "Knowledge Base & Playbook - categories - all")
- What state it represents
- Which screens are state variations of the same page
Key insight: Most Figma files have many screens that are just DIFFERENT STATES of the same page component. Group them:
- Browse views (different selections, filters, permissions)
- Reader views (different articles, panel states)
- Editor views (empty, populated, with modals open)
- Error/empty states
Step 2: Extract Component Hierarchy
For each screen, use get_metadata to understand the node tree:
get_metadata(fileKey, screenNodeId)
Map the visual hierarchy:
Screen (1920x1080)
├── SideMenu (260px, shared across app — exclude from KB scope)
├── Header (64px, shared chrome)
└── Content Area
├── Left Panel (sidebar, 410px)
│ ├── Search input
│ ├── Filter pills
│ └── Category tree
├── Center Content (fluid)
│ ├── Breadcrumb
│ ├── Section headers
│ └── Article cards / Reader
└── Right Panel (390px)
├── Table of Contents
└── Metadata grid
Step 3: Identify Components and Their States
Components aren't always well-named in Figma. Look for:
- Repeated patterns — the same frame structure appearing multiple times (e.g., post cards)
- Instance nodes — Figma components that are reused
- State variations — selected vs default, expanded vs collapsed, admin vs limited role
For each component, extract:
- Figma node ID
- Dimensions (width × height)
- All visual properties via
get_design_context:- Colors (as hex — Figma uses 0-1 RGBA, multiply by 255)
- Typography (font family, size, weight, line-height, letter-spacing)
- Spacing (padding, margin, gap)
- Border (radius, width, color)
- Icons (SVG assets from MCP asset URLs)
- Images (embedded screenshots, illustrations)
Step 4: Download Everything to Disk
Before dispatching any subagents, save:
Baseline PNGs (Figma REST API at scale=2):
export FIGMA_TOKEN="your-token"
curl -H "X-Figma-Token: $FIGMA_TOKEN" \
"https://api.figma.com/v1/images/:fileKey?ids=NODE1,NODE2&format=png&scale=2"
# Returns JSON with S3 URLs, then:
curl -o tests/visual/baselines/<name>/<name>.png "<s3-url>"
Design context JSON (Figma REST API):
curl -H "X-Figma-Token: $FIGMA_TOKEN" \
"https://api.figma.com/v1/files/:fileKey/nodes?ids=NODE1,NODE2" \
> tests/visual/design-context/components.json
Commit both so subagents can read them.
Directory structure:
tests/visual/
baselines/ ← Figma PNGs (SACRED — never overwrite)
status-filter-pills/
status-filter-pills.png
post-card/
post-card.png
kb-page-categories/
kb-page-categories.png
design-context/ ← Figma node data as JSON
screen1-components.json
screen2-components.json
specs/ ← Playwright visual test specs
atoms/
components/
sections/
screens/
integration/
helpers/ ← Test utilities
dismissOverlay.ts
injectMswAuth.ts
test-results/ ← Diff artifacts (gitignored)
report/ ← HTML report (gitignored)
Phase 1: Infrastructure Setup
Dev Harness
Create a route-based component gallery for isolated rendering:
src/pages/__dev/
DevHarness.tsx ← Route index with links to all harnesses
MockStoreProvider.tsx ← Wraps components with mock MobX/Redux store
fixtures/
kbFixtures.ts ← Article data matching Figma content
kbSidebarFixtures.ts ← Tree/nav data matching Figma structure
harnesses/
StatusFilterPillsHarness.tsx
PostCardHarness.tsx
KBPageCategoriesHarness.tsx ← Full-page harness with SideMenu stub
...
Key principles:
- Each harness renders ONE component at a fixed size inside
<Box data-testid="harness-root"> MockStoreProviderprovides store context without API calls- Fixture data must match Figma content EXACTLY (titles, dates, author names, article text)
- Dev-only routes gated behind
process.env.NODE_ENV === 'development' - Use
React.lazy()for code-splitting
Playwright Configuration
// playwright.visual.config.ts
export default defineConfig({
testDir: './tests/visual/specs',
workers: 1, // Serial for deterministic rendering
retries: 0, // No retries — diffs are real
expect: {
toHaveScreenshot: {
threshold: 0.2, // Per-pixel color sensitivity
maxDiffPixels: 100, // Override per-spec
animations: 'disabled',
caret: 'hide',
scale: 'device', // CRITICAL: capture at device DPR
},
},
projects: [{
name: 'chromium',
use: {
...devices['Desktop Chrome'],
viewport: { width: 1920, height: 1080 },
deviceScaleFactor: 2, // CRITICAL: match Figma 2x export
launchOptions: {
args: ['--disable-gpu', '--font-render-hinting=none'],
},
colorScheme: 'light',
},
}],
webServer: {
command: 'npm run create', // or npm run dev
url: 'http://localhost:3000',
reuseExistingServer: true,
timeout: 120_000,
},
snapshotDir: './tests/visual/baselines',
snapshotPathTemplate: '{snapshotDir}/{arg}/{arg}{ext}',
});
DPR Handling — The Biggest Gotcha
Figma exports at scale=2 produce 3840×2160 images for a 1920×1080 viewport.
Playwright must capture at the same resolution.
WRONG (resets DPR to 1):
test.beforeEach(async ({ page }) => {
await page.setViewportSize({ width: 1920, height: 1080 }); // RESETS DPR!
});
RIGHT (preserves DPR):
test.use({
viewport: { width: 1920, height: 1080 },
deviceScaleFactor: 2,
});
ALSO REQUIRED in toHaveScreenshot():
await expect(locator).toHaveScreenshot('name.png', {
maxDiffPixels: 415000,
threshold: 0.3,
scale: 'device', // Without this, screenshot is at CSS pixels, not device pixels
});
Fixture Data from Figma
Use MCP to extract actual content from Figma for fixture data:
get_design_context(fileKey, nodeId)
This returns the actual text content, colors, and structure. Use it to populate:
- Article titles, body text, excerpts
- Category/navigation tree names
- Author names, dates
- Tag labels
- Any embedded images (download asset URLs)
The fixture data must match Figma exactly — different text content accounts for the largest portion of pixel diff in visual regression tests.
Phase 2: Bottom-Up Component Iteration
Work bottom-up: atoms → components → sections → screens.
Why Bottom-Up?
If a component is wrong, every screen containing it will have that error multiplied. Fix components first, then screens automatically improve.
Hierarchy
| Level | Example | Figma Source | Playwright Target |
|---|---|---|---|
| Atom | StatusFilterPills, BreadcrumbNav | Crop/sub-node | page.locator('[data-testid="..."]') |
| Component | PostCard, CategoryTree, ArticleReader | Component frame | page.locator('[data-testid="..."]') |
| Section | KB Sidebar (search + pills + tree) | Region of screen | page.locator('[data-testid="..."]') |
| Screen | Full KB categories page | Full artboard | page.locator('[data-testid="harness-root"]') |
Convergence Loop (Per Component)
ITERATION 1 — Structural alignment (target: 10% pixel diff)
1. Read Figma baseline PNG
2. Read design context JSON for exact values
3. Take Playwright screenshot
4. Compare — identify layout/structural differences
5. Fix: wrong widths, missing elements, incorrect flex layout
6. Re-screenshot and verify
ITERATION 2 — Visual refinement (target: 5% pixel diff)
7. Read diff image — focus on colors, typography, spacing
8. Fix: wrong font sizes, colors, padding, border radius
9. Re-screenshot and verify
ITERATION 3 — Polish (target: 3% if achievable)
10. Read diff image — remaining differences
11. Fix: fine spacing, icon alignment, text content
12. If remaining diff is anti-aliasing noise (text rendering), STOP
13. Set maxDiffPixels to measured value + 10% margin
DONE when diff is under 5% (415K pixels for 3840×2160).
Anti-Aliasing Reality
Chromium and Figma use different text rendering engines. At threshold: 0.2, every
text pixel registers as "different" because sub-pixel anti-aliasing produces slightly
different RGB values.
The fix is threshold tuning, not code changes:
- Text-heavy screens:
threshold: 0.75filters out anti-aliasing while catching layout issues - Icon/graphic-heavy screens:
threshold: 0.3is tighter - The
#3A3A46dark text on white has ~75% LAB distance — that's the boundary
Structural regressions are STILL caught at high thresholds because:
- A missing 1250×40px section header = 100K+ pixels of wrong color
- A removed card = 200K+ pixels of exposed background
- A shifted panel = massive contiguous diff block
Set tight maxDiffPixels budgets per screen to catch these.
Phase 3: Screen-Level Convergence
After components pass individually, verify full screens.
Full-Screen Harnesses
For each Figma screen, create a harness that composes all components:
- SideMenu stub (260px dark rectangle — exclude real SideMenu from KB scope)
- KB page header (title + search + action icons)
- All content panels with fixture data matching Figma
TinyMCE / Third-Party Component Masking
Components like TinyMCE render in iframes with their own CSS — they'll never pixel-match Figma's static mockup. Options:
- Use the real component (preferred) — render live TinyMCE with the API key. The toolbar/chrome will be close to Figma. Accept higher diff tolerance.
- Mask the region — apply CSS to cover the iframe with a solid color before screenshot, so only the surrounding layout is compared.
- Exclude from comparison — take element-level screenshots of non-iframe regions.
Embedded Images in Articles
Figma may show screenshots/illustrations embedded in article body content. These are
<img> tags in the HTML body, NOT modal overlays. Extract the image from Figma
(get_screenshot on the internal frame node) and save as a static asset:
src/assets/images/kb/add-task-form-screenshot.png ← source
public/assets/images/kb/... ← CRA serves from public/
Reference in fixture HTML: <img src="/assets/images/kb/add-task-form-screenshot.png" />
Phase 4: Real App Verification
Harnesses prove components work in isolation. Real app verification proves they compose correctly within the actual application shell.
MSW Integration
Wire fixture data into MSW (Mock Service Worker) handlers so the real app pages render with the same data as harnesses:
- Auth bypass: Add MSW handler for login endpoint + app settings endpoint
- KB data: Sync MSW fixture data with harness fixtures (same categories, articles, tree)
- Playwright auth injection: Use
page.addInitScript()to write auth token to localStorage BEFORE React mounts (NOTpage.evaluate()which runs after)
Integration Tests
Test real app routes (not harnesses):
- Navigate to
/crm/knowledge-basewith auth injected - Verify page structure (sidebar, content, panels)
- Test interactive behaviors (category selection, panel collapse, navigation)
- Compare real page screenshot against harness screenshot for structural match
Baseline Management — SACRED RULES
- Figma baseline PNGs are GROUND TRUTH — they represent what the designer intended.
- NEVER run
--update-snapshotson Figma baselines. - NEVER overwrite baselines with browser screenshots — this creates circular comparisons that always pass but prove nothing.
- Diff means YOUR CODE is wrong, not the baseline.
- Agents WILL try to regenerate baselines if not explicitly told not to. Every agent prompt must include the rule.
- Update baselines only when: Figma designs change, and you re-export from Figma.
Agent Dispatch Pattern
Pre-Dispatch Checklist (Main Session)
Before dispatching a subagent for pixel-perfect work:
- All target Figma screenshots downloaded as PNGs to
tests/visual/baselines/ - Design context saved as JSON to
tests/visual/design-context/ - Embedded images/assets saved to
src/assets/orpublic/ - Fixture data in harness files matches Figma content
- All files committed (subagents read from git)
- Agent prompt includes: "NEVER overwrite Figma baseline PNGs"
- Agent prompt includes: "NEVER run --update-snapshots"
- Agent prompt includes Figma API token (for additional REST API calls if needed)
Agent Prompt Template
You are running pixel-perfect iteration for [component/screen].
Compare browser renders against FIGMA-EXPORTED baseline PNGs.
## CRITICAL RULES
1. NEVER overwrite baseline PNGs — they are Figma ground truth
2. NEVER run --update-snapshots
3. Diff means YOUR CODE is wrong — fix the code, not the baseline
4. Iterate until pixel diff < [target] — don't do one pass and report
## Baselines
- [list baseline paths]
## Design Context
- [path to JSON]
## Figma API Token (for additional data if needed)
export FIGMA_TOKEN="..."
## Convergence Targets
- Round 1: maxDiffPixels [generous], threshold 0.3 (structural)
- Round 2: maxDiffPixels [medium], threshold 0.5 (refinement)
- Round 3: maxDiffPixels [tight], threshold 0.75 (polish)
Parallelization
Split work by component independence:
- Agent 1: Sidebar components (CategoryTree, SearchOverlay, StatusFilterPills)
- Agent 2: Content components (PostCard, ArticleListView, ArticleReader)
- Agent 3: Panel components (TableOfContents, PrimaryDetailsPanel)
- Agent 4: Full screens (after components converge)
Use isolation: "worktree" for parallel agents to avoid file conflicts.
Quick Reference: Key Measurements
| Property | Value |
|---|---|
| Figma export scale | 2x |
| 1920×1080 at 2x | 3840×2160 pixels |
| Total pixels | ~8.3M |
| 5% target | ~415K pixels |
| 3% target | ~249K pixels |
| Anti-aliasing noise floor | ~1-2% at threshold 0.2 |
| Text-safe threshold | 0.75 (filters font anti-aliasing) |
| Playwright DPR setting | deviceScaleFactor: 2 |
| Screenshot scale | scale: 'device' |
| Snapshot path template | {snapshotDir}/{arg}/{arg}{ext} |