bitovi/ai-enablement-prompts/10-validator

Skill: Figma Rebuild Validator

Validates the output of figma-from-code by navigating the live app, screenshotting each component in its natural context, and comparing against the matching Figma variant — not the entire component set. Produces a structured report with side-by-side screenshots.

This skill can be used two ways:

• Standalone: Run directly to validate a completed rebuild (all phases below)
• As a reference for Phase 5: The orchestrator's Phase 5 agent reads this skill for the Component App Map, variant resolution logic, and structural QA scripts

When to Use

• After running figma-from-code to verify the output (standalone)
• When auditing whether Figma components match their React implementations
• When the orchestrator's Phase 5 agent needs the Component App Map or comparison scripts

Prerequisites

Placeholders like {devServerUrl} and {skillRoot} resolve from state.json → config.

• Figma MCP must be connected and authenticated
• Dev server must be running at {devServerUrl} — use the URL from state.json → config.devServerUrl (default http://localhost:5173)
• .temp/figma-from-code/state.json must exist (produced by figma-from-code)
• compare.js for pixel diff is vendored at {skillRoot}/scripts/compare.js

Workflow

Phase 1: Inventory        → list all Figma components + classify app visibility
Phase 1e: Variant Resolve → for each component set, find the specific variant used in the app
Phase 2: Screenshots      → process each tier sequentially to capture app + Figma screenshots and run pixel diffs
Phase 3: Structural       → check variables, pages, screen sizes
Phase 4: Report           → merge tier results, write .temp/figma-validation/report.md

Phase 1: Build Component Inventory

Step 1a — Read state file

cat .temp/figma-from-code/state.json

Extract fileKey.

Step 1b — Query Figma for all components

// use_figma
await figma.setCurrentPageAsync(figma.root.children.find((p) => p.name === '📦 Components'));
const sets = figma.currentPage.findAll((n) => n.type === 'COMPONENT_SET');
const singles = figma.currentPage.children.filter((n) => n.type === 'COMPONENT');
const all = [
  ...sets.map((s) => ({ name: s.name, id: s.id, type: 'set' })),
  ...singles.map((s) => ({ name: s.name, id: s.id, type: 'single' })),
];
return JSON.stringify(all);

Step 1c — Classify each component

Use the Component App Map below to assign each component a url, selector, optional click action, and figmaVariant (the variant properties that match what's rendered in the app).

Step 1d — Check dev server

curl -s --max-time 3 {devServerUrl} > /dev/null && echo "running" || echo "not_running"

If not_running: halt and tell the user to run the dev server.

Print the classification to the conversation:

📱 App visible (44): Button, Input, ...
⚠️  Requires interaction (4): Dialog, Sheet, ...
🚫  Not visible in app (1): Skeleton (loading state only)

Phase 1e: Variant Node Resolution

This is the key step that ensures Figma screenshots match the app variant.

For every component whose type === 'set' and that has a figmaVariant specified in the Component App Map, resolve the specific child variant node ID before taking screenshots.

What this solves

Without this step, get_screenshot(fileKey, setNodeId) returns an image of all variants tiled in the component set — not the single variant that the app is rendering. Resolving to the child node gives an apples-to-apples comparison.

Resolution script (run once per component set)

// use_figma
const setNodeId = '{nodeId from Phase 1b}';
const targetProps = { Variant: 'primary', State: 'Default' }; // from Component App Map figmaVariant column
const componentSet = figma.getNodeById(setNodeId);
if (!componentSet || componentSet.type !== 'COMPONENT_SET') {
  return JSON.stringify({
    resolvedId: setNodeId,
    resolvedName: componentSet?.name ?? 'unknown',
    fallback: true,
  });
}
// Log available variant property names and their values to aid debugging
const available = componentSet.children.map((c) => ({
  id: c.id,
  name: c.name,
  props: c.variantProperties,
}));
// Try exact match first (case-insensitive values)
let match = componentSet.children.find((child) =>
  Object.entries(targetProps).every(
    ([k, v]) => child.variantProperties?.[k]?.toLowerCase() === v.toLowerCase()
  )
);
// Partial match fallback: match only props that exist on the set's property keys
if (!match) {
  const availableKeys = Object.keys(componentSet.children[0]?.variantProperties ?? {});
  const filteredTarget = Object.fromEntries(
    Object.entries(targetProps).filter(([k]) => availableKeys.includes(k))
  );
  match = componentSet.children.find((child) =>
    Object.entries(filteredTarget).every(
      ([k, v]) => child.variantProperties?.[k]?.toLowerCase() === v.toLowerCase()
    )
  );
}
// Last resort: first child
match = match ?? componentSet.children[0];
return JSON.stringify({
  resolvedId: match.id,
  resolvedName: match.name,
  props: match.variantProperties,
  available,
});

Store the resolved `variantNodeId` for each component. Use this in Phase 2 when calling get_screenshot.

Handling multiple app variants for one component

Some components appear in multiple variants in the app (e.g., Button appears as primary on form submit and ghost in menus). For these, create two entries in the comparison table:

Component App Map

The Component App Map assigns each Figma component a URL, Playwright CSS selector, optional click/hover action, and Figma variant properties for comparison targeting.

This map is built dynamically during Phase 1c from the component-map.json output (Phase 0a). It is NOT hardcoded.

The screenshot script is: {skillRoot}/scripts/screenshot.js

Usage:

# Element screenshot (preferred)
node screenshot.js <url> <output> --selector "css" [--click "click-css"] [--hover "hover-css"] [--variant "label"] [width] [height]
 
# Full-page fallback
node screenshot.js <url> <output> [width] [height]

Flags:

• --selector — CSS selector for the element to screenshot
• --click — click this element before screenshotting (opens overlays, enters edit mode)
• --hover — hover over this element before screenshotting (reveals tooltips, hover cards)
• --variant — label printed in output for logging (no effect on screenshot)
• --nth N — use the Nth matching element (0-indexed)

Batch manifest entries additionally support fallbackSelectors (ordered alternates tried when the primary selector times out — the output line notes which one was used) and click as an ordered array for multi-step interactions.

Building the Map

For each component discovered in component-map.json, prefer its capture object — it records the exact URL, validated selector, ordered fallbackSelectors, and the interaction replay recipe (clicks array + hover) from discovery time. Use capture.url verbatim; never pair a selector with a different route than the one it was derived on.

For legacy maps without capture:

1. URL: Use the route(s) where the component appears (from component-map.json -> routes)
2. Selector: Use the best CSS selector (from component-map.json -> selector). Prefer [data-component="Name"], [aria-label="..."], or class-based selectors
3. Click action: If the component requires interaction to become visible (overlays, dropdowns, edit modes), specify a click selector
4. Hover action: If the component requires hover to reveal (tooltips, hover cards), specify a hover selector
5. Figma variant: The variant properties that match the app's default rendering (e.g., {Variant: "primary", State: "Default"})

Selector Strategy by Component Type

Components Not Directly Visible in App

Some components are not rendered by default and require special handling:

For hover-only components, use Playwright's .hover() API in a custom script rather than the --click flag.

Phase 2: Screenshot Pairs (Sequential by Tier)

Process all tiers sequentially inline. For each tier, handle every component: check for pre-built screenshots, capture app + Figma screenshots, run the pixel diff. Components within a tier share URLs, so reuse a single Playwright page load per URL where possible.

Per-Tier Process

For each tier in state.json -> buildOrder.tiers, process all components using Steps 2a–2e below. After completing a tier, write results to .temp/figma-validation/tier-{N}-results.json:

[{ "name": "...", "matchPct": 94.2, "borderMatchPct": 91.0, "verdict": "match", "issues": [] }, ...]

Collecting Results

After all tiers are processed, read each tier-{N}-results.json and merge into a single component list for Phase 3/4. Components with verdict: "mismatch" or verdict: "minor_diff" are candidates for Phase 5 fixes.