Hand Rendered UI Back to Figma So Design Files Stay Honest

Tier: Advanced · Workflow area: Design-to-code & design systems · Tools: Claude Code, Figma (generate_figma_design)

Design-to-code gets all the attention, but drift flows the other way too: engineers tweak spacing during bug fixes, product tunes copy in code, states get added that no frame ever showed. The design file silently becomes archaeology. This playbook establishes the reverse pipeline — code back to canvas — as a routine sync step, not a heroic quarterly cleanup.

When to use

• Design files lag shipped realitydesigners screenshot production to see current state, or new frames restyle components that changed months ago.
• After a code-side iteration burstpost-launch polish, A/B winners, accessibility fixes that changed visuals — none of which went through Figma.
• Before a redesign kicks offthe team needs an honest "as-built" baseline to design from, not the aspirational file from two quarters ago.
• Design-system parity auditscomparing the coded component's real states against the Figma library exposes drift in both directions.

When NOT to use

• The design file is still the source of truthmid-design-cycle handback overwrites intent with implementation; sync only surfaces whose truth now lives in code.
• Pixel-perfect layer archaeology matters more than editabilityhandback produces editable approximations; if you need forensic pixel records, screenshots in an "as shipped" archive page are cheaper.
• The surface is churning dailysync at milestones (release, sprint end), not per-commit; per-commit handback trains designers to ignore the canvas.

The recipe

1. 1.

   Pick the sync set and freeze the capture conditions. List the surfaces whose canonical truth is now code — e.g., the settings area after an accessibility polish sprint. Capture like pb-11: deterministic data (MSW fixtures), fonts loaded, animations off, agreed viewport (1280 for desktop surfaces). One state list per surface: default, plus any state designers will need to edit (empty, error, upgraded-plan).

2. 2.

   Wire the agent to Figma's design-generation MCP and confirm the target file. With the Figma MCP connected (Dev Mode MCP server, pb-09) the agent gets generate_figma_design; create or open the target file — a dedicated "As-Built — <app> <release>" page, never the working design file's canvas:

   Copy

   claude mcp add --transport http figma-dev-mode http://127.0.0.1:3845/mcp
   claude
   

   Copy

   Confirm you can reach the Figma MCP and list the tools available.
   We will generate into the file "As-Built — Settings v3.4", page
   "2026-08 sync". Do not modify any other page.
   

3. 3.

   Generate Figma frames from the live UI, one surface at a time. Point the agent at the running app plus the component source — source access is what lifts output from screenshot-tracing to structured layers:

   Copy

   Open http://localhost:3000/settings/profile (MSW scenario: default).
   Using generate_figma_design, recreate this screen as an editable
   Figma frame on the "2026-08 sync" page:
   - Auto-layout frames mirroring the component structure in
     src/features/settings/ProfileSection.tsx (read it — name layers
     after the components: ProfileSection/AvatarRow/Field...)
   - Text styles and fills bound to our Figma variables where they
     exist (collection "acme/semantic"); flag any code token with no
     Figma variable in a text note beside the frame
   - Frame name: "settings-profile / default / v3.4"
   Then repeat for MSW scenarios: empty, server-error.
   

   Good output: frames with real auto-layout (drag a card — siblings reflow), semantic layer names, variable-bound fills — not one flat rasterized group. Spot-drag two elements in Figma to verify editability before generating the next surface.

4. 4.

   Run the drift review — the actual payoff. Put old design frames beside the as-built frames and make a multimodal pass produce the drift table (pb-11 mechanics, reversed roles):

   Copy

   Image 1: the design file's settings-profile frame (last edited
   2026-03). Image 2: the as-built frame generated today. Table of
   drifts: element | property | designed | shipped | likely reason
   (bug-fix / a11y / copy tune / unknown). Mark "unknown" rows — those
   need a human decision on which side is right.
   

   Triage with the designer in one sitting: shipped-wins rows update the working design file (designer copies from as-built), design-wins rows become frontend tickets, unknowns get decided. Every row leaves with an owner.

5. 5.

   Institutionalize the cadence. Add handback to the release ritual: each release cut regenerates the as-built page (new page per release, so history persists), and the drift review is a standing 30-minute design/eng sync. Script the capture half so the cost stays near zero:

   Copy

   sh scripts/asbuilt-sync.sh settings v3.4
   

   The script boots the app with fixtures, walks the surface/state list, and drives the agent through step 3's prompts per entry.

6. 6.

   Feed the design system both ways. Recurring drift on the same component (the Badge that's been 4px tighter in code for six months) is a parity signal: fix the Figma library component or the coded one — and if you run Code Connect (pb-10), update the mapping in the same PR so future design-to-code runs inherit the resolution.

Make it yours

• React web (as written)richest path: component source + live DOM + Figma variables gives structured, well-named layers.
• Vue / Angularidentical flow; give the agent the SFC/component source for layer naming, and expect one extra iteration on auto-layout fidelity for complex CSS grid areas.
• React Native / Fluttercapture per-platform: run the surface in the simulator, screenshot at a reference device size, and have the agent rebuild frames using the component tree from source; generate iOS and Android variants only where they genuinely differ (safe areas, native controls).
• No generate-capability tierfall back to a manual-but-honest loop: pb-11-style screenshots into a dated "as-built" Figma page (pasted images, not layers) plus the drift table; you lose editability but keep the honesty and the ritual.

Quality check

• As-built frames are genuinely editableauto-layout reflows on drag, text is text, fills reference variables; no flattened groups.
• Layer names trace to componentsa designer can ask "what is this?" and read the answer in the layer panel.
• Drift table fully triagedzero "unknown" rows left; each drift has an owner (design update, code ticket, or accepted).
• Working design file updatedshipped-wins drifts actually landed in the canonical frames, not just in the as-built page.
• The cadence survived a second releasetwo consecutive as-built pages exist; that's the difference between a ritual and a demo.