figma-web-refactor

name

figma-web-refactor

description

Refactor selected Figma nodes for web implementation by creating a strong visual-equivalent target HTML first, validating that target HTML, then editing Figma structure to match the target intent while preserving visual intent. Use this skill whenever the user asks to optimize a Figma design for web, make a Figma node more HTML/CSS friendly, convert absolute-looking design structure into Auto Layout/component-like structure, or run /figma-web-refactor. This workflow intentionally does not use repeated figma-to-html regeneration as an optimizer feedback loop because the exporter can fail to express valid Figma structure as flex/grid HTML.

Figma Web Refactor

Refactor a selected Figma node, frame, or page into a more web-friendly design structure. The workflow treats the architect's target HTML as the source of truth, not regenerated figma-to-html output from each Figma edit.

This skill exists because figma-to-html is useful for bootstrapping baseline HTML and assets, but it is not reliable enough to judge whether a Figma structural refactor succeeded. Valid Figma Auto Layout and component structure may still export as fixed margins or absolute-looking HTML. Do not punish good Figma structure just because the exporter cannot express it.

Operating Principle

The run succeeds when:

1. html-target-architect produces target HTML that is visually equivalent to the baseline and materially better for web integration.
2. integration-quality-judge validates the target HTML and its Figma change report. If it fails, send the result back to the architect for revision; multiple architect ⇄ judge rounds are allowed.
3. figma-optimizer edits the Figma working node so its layer structure, Auto Layout, grouping, naming, and component/repeated-item expression match the validated target HTML intent as closely as practical.
4. visual-regression-judge verifies that the final Figma render preserves visual intent or only has acceptable bounded drift.

Do not run a per-iteration Figma → HTML regeneration loop. A final Figma export may be captured as an artifact only, not as the success gate.

Required Capabilities

Verify these before destructive work:

• Figma MCP access for reading metadata, screenshots, and editing via Plugin API.
• figma-to-html for the initial baseline HTML and optional final artifact capture.
• chrome-cdp for rendering target HTML and screenshots.
• Node.js and npm for image comparison scripts.

Stop with a missing-capability report if any required capability is unavailable.

Authentication Boundary

This workflow uses two separate Figma authentication paths:

• Figma MCP authentication is configured by the MCP server itself, typically through mcp.json headers. When calling Figma MCP tools, never pass FIGMA_TOKEN, --token, or a token-like argument unless that exact MCP tool schema explicitly requires it.
• figma-to-html and its bundled scripts use the export/API token path. They need FIGMA_TOKEN or a user-provided token for --token, because the exporter and image downloader call the Figma REST/export APIs separately from MCP.

If the user explicitly provides FIGMA_TOKEN, treat it only as the figma-to-html export token. Do not assume it is also the MCP credential, and do not add it to MCP tool arguments. If MCP calls fail authentication, ask the user to fix MCP configuration rather than retrying with the export token as a parameter.

Task Workspace

Create a stable workspace under:

.figma-refactor/{task-name}/

Use a lowercase slug derived from the node name or user request. Keep the same task name for the run.

Recommended structure:

.figma-refactor/{task-name}/
├── manifest.json
├── baseline/
│   ├── figma.png
│   ├── html/
│   ├── html-screenshot.png
│   └── inspection.json
├── target-html/
│   ├── index.html
│   ├── screenshot.png
│   ├── diff.png
│   └── diff.json
├── analysis/
│   ├── target-structure-report.md
│   └── target-html-judgment.md
├── optimizer/
│   ├── edit-log.md
│   ├── before.json
│   ├── after.json
│   ├── after.png
│   ├── diff.png
│   └── diff.json
├── visual-judgment.md
└── final-report.md

manifest.json records: task name, Figma file key, working node ID, backup node ID, source URL, baseline paths, target paths, optimizer paths, and Chrome CDP endpoint.

Subagents

Use these project subagents for this workflow when they are available in the current context:

• html-target-architect — creates the visual-equivalent, structurally strong target HTML and writes the Figma-side change report.
• integration-quality-judge — validates the architect's target HTML and change report. It does not judge regenerated Figma exports.
• figma-optimizer — edits the Figma working node to match the validated target structure intent. It does not use repeated HTML regeneration as feedback.
• visual-regression-judge — judges the final Figma screenshot diff by visual intent.

Fallback: if the current context does not define one of these named subagents, read the corresponding prompt file from ../../agents/{subagent-name}.md, invoke the General subagent instead, and pass both the file prompt and the concrete task requirements to that General subagent. Keep using the same workflow role and expected deliverables described below; only the invocation mechanism changes.

There is no auditor stage. The architect owns target structure analysis, risk notes, and Figma change implications.

Workflow

1. Preflight

1. Load required skills/tools: figma, figma-to-html, chrome-cdp.
2. Verify Figma MCP authentication and selected node access using MCP tool schemas as-is; do not pass FIGMA_TOKEN to MCP calls.
3. Resolve the export token separately for figma-to-html from user input, FIGMA_TOKEN, or .env.
4. Verify Node.js/npm and install compare script dependencies if needed.
5. Confirm the selected node can be exported as image and baseline HTML.

2. Backup

Before editing Figma:

1. Duplicate the target node via Figma MCP.
2. Record the backup node ID in manifest.json.
3. Only edit the working node. Never edit the backup.

3. Capture Baseline

Capture the minimum baseline artifacts:

• Figma screenshot: baseline/figma.png.
• Baseline generated HTML: baseline/html/.
• Baseline HTML screenshot: baseline/html-screenshot.png.
• Optional DOM/CSS/layout inspection: baseline/inspection.json.
• Figma metadata for the selected node when useful to the architect or optimizer.

The baseline HTML is only the starting material for the architect. It is not the long-term quality gate.

4. Build Strong Target HTML

Invoke html-target-architect with:

• Baseline HTML and assets.
• Baseline HTML screenshot.
• Figma screenshot and metadata if available.
• Output paths for target-html/ and analysis/target-structure-report.md.
• Chrome CDP endpoint and compare script path.

The architect must produce:

• target-html/index.html — div-only unless user explicitly requests semantics.
• target-html/screenshot.png, target-html/diff.json, target-html/diff.png.
• analysis/target-structure-report.md — the Figma change report for optimizer.

Target HTML expectations:

• Preserve visible design intent as strictly as possible.
• Be structurally ambitious: use flex/grid/gap, repeated item structure, component-like grouping, and dynamic-data-friendly containers when they can preserve the screenshot.
• Prefer real layout relationships over fixed left/top and magic margins.
• Convert simple UI chrome to CSS primitives when visually safe: rounded rectangles, pills, badges, dividers, simple gradients, shadows.
• Keep complex artwork as assets: avatars, logos, icons, rank badges, decorative illustrations, masks, complex gradients, and any image whose visual role cannot be safely represented as CSS.
• Explicitly report any area intentionally left conservative and why.

analysis/target-structure-report.md must include:

• Target DOM/CSS structure summary.
• Concrete improvements vs baseline: wrapper reduction, flex/grid regions, repeated lists, component-like clusters, CSS primitive replacements, asset retention.
• Figma-side structure plan: which visible regions should become Auto Layout, grouped frames, repeated components, variants, constraints, or named structural layers.
• Risk notes for visual preservation.
• Measurable indicators from the target HTML.

5. Validate Target HTML

Invoke integration-quality-judge in target-only mode with:

• Baseline HTML and baseline screenshot.
• Target HTML, target screenshot, and target diff.
• analysis/target-structure-report.md.

The judge answers whether the target is good enough for the optimizer:

• Visual equivalence: strict for target HTML.
• Web friendliness: must be materially better than baseline, not just annotation cleanup.
• Structural coverage: important regions such as sidebar, toolbar, tabs/filters, podium/cards, table/list, forms, repeated controls should be addressed when present.
• Figma editability: the change report must be concrete enough for the optimizer.

If the verdict is FAIL, resume html-target-architect with the judge's findings. Repeat architect ⇄ judge until PASS or until a clear blocker is documented. Do not start Figma edits from a weak target.

6. Optimize Figma Structure

Invoke figma-optimizer with:

• Figma file key, working node ID, backup node ID.
• Baseline Figma screenshot.
• Baseline Figma metadata.
• Baseline HTML path.
• Validated target HTML path.
• analysis/target-structure-report.md.
• Workspace path optimizer/.
• User tolerance notes, including whether bounded visual drift is allowed.

The optimizer should:

1. Read the validated target HTML and change report.
2. Inspect current Figma structure.
3. Directly edit Figma to align layer structure with the target intent: Auto Layout, constraints, grouping, naming, repeated structures, component-like frames, and CSS-friendly simple shapes.
4. Prefer high-value visible layout regions over low-impact renames.
5. Preserve complex artwork as assets unless the target report says a CSS primitive replacement is safe.
6. Write optimizer/edit-log.md, optimizer/before.json, and optimizer/after.json.
7. Export final Figma screenshot to optimizer/after.png and compare to baseline/figma.png into optimizer/diff.json and optimizer/diff.png.

The optimizer must not:

• Repeatedly regenerate HTML from Figma as a feedback loop.
• Reject a real Figma structural improvement merely because the current exporter would not emit better HTML.
• Optimize for figma-to-html quirks at the expense of clean Figma structure.
• Edit the backup node.

7. Judge Final Visual Result

Invoke visual-regression-judge with:

• baseline/figma.png.
• optimizer/after.png.
• optimizer/diff.png and optimizer/diff.json.
• optimizer/edit-log.md.
• User tolerance notes.

The visual judge classifies:

• PASS — visual intent preserved.
• REPAIRABLE_DRIFT — bounded drift remains but the final result may be acceptable as best effort or should be repaired.
• DESTRUCTIVE_FAIL — visual hierarchy, content, clipping, layer order, or artwork is broken.

If the verdict is DESTRUCTIVE_FAIL, repair or revert only the destructive part when possible. If the user explicitly asked to preserve final effort instead of rollback, keep the last/best result and clearly report the visual failure.

8. Optional Final HTML Export

A final figma-to-html export may be captured for reference only. It must not decide success or failure unless the user explicitly asks to optimize for that exporter.

If captured, label it clearly as exporter output and note that exporter limitations may hide valid Figma-side structural improvements.

Final Report

Write .figma-refactor/{task-name}/final-report.md with:

• Backup node ID and working node ID.
• Target HTML quality and judge verdict.
• What the target HTML improved.
• What Figma structure was changed.
• Final visual judge verdict and diff summary.
• What was intentionally not changed and why.
• Any remaining mismatch between target HTML intent and Figma structure.
• Whether any final exporter output was captured and whether it was treated as non-gating.

Keep the user response concise and include the task workspace path.