Figma to WordPress: The Handoff Checklist That Prevents Rebuilds

The design was signed off six weeks ago. The build came back, and now the designer is filing tickets about 4px of letter-spacing, a hover state nobody drew, and a mobile menu that “obviously” should have been a slide-over. Somebody is about to eat those hours, and it will probably be your agency.

A clean Figma to WordPress handoff is a document problem, not a talent problem. This post gives you the file structure, the token and state coverage, the content rules and the pre-build checklist that stop a signed-off design turning into a partial rebuild.

Why rebuilds happen

Rebuilds are almost never caused by a developer misreading a layout. They are caused by decisions that were never made in the design file, so the developer made them instead — and made them differently from what the designer had in their head.

• Only desktop and one mobile frame exist, so every tablet decision is invented at build time.
• Type is set with one-off sizes rather than styles, so the developer cannot tell what is a system and what is a mistake.
• No empty, loading, error or long-content states, so the design collapses the first time real client copy lands in it.
• Interactive behaviour lives in the designer’s head or in a comment thread, never in the file.
• Nobody said which sections must be editable by the client, so the build hardcodes what should have been fields.

Each gap is small. Together they are the difference between a build that lands in one review round and one that limps through four. If you are outsourcing the front-end work, the gaps get expensive faster, because a partner cannot lean over and ask the designer. The wider context on running that relationship is in the white label WordPress development guide for agencies.

Structure the Figma file for a builder, not a reviewer

Presentation files and build files have different jobs. The version you hand to a developer should be organised so that anyone can find the source of truth for any pixel in under thirty seconds.

1. One page per purpose. Separate pages for Foundations, Components, Pages (build-ready), and Archive. Anything exploratory goes to Archive, not into the build page.
2. Name frames after templates, not marketing. “Single Post”, “Archive – Category”, “Page – Default”, “WooCommerce – Product” map to what actually gets built. “Homepage v3 FINAL” does not.
3. Use auto layout everywhere. It communicates padding, gaps and growth direction without a single annotation. A frame without auto layout tells a developer nothing about how it should behave at 1100px.
4. Publish components, not copies. If the button appears in eleven places, it is one component with variants, and the developer builds it once.
5. Lock the file before handoff. Duplicate to a versioned build file and mark it read-only. Silent edits after the estimate is given are the single most common source of dispute.

Tokens, type and spacing

The developer will translate your design into CSS custom properties or theme.json settings. Give them a system to translate, and the front end becomes maintainable for years. Give them 43 unique font sizes and the site becomes a museum of one-off rules.

Token group	What to define	What happens without it
Colour	Named roles: surface, surface-alt, text, text-muted, accent, accent-hover, border, error, success	Hex values scattered through stylesheets; rebranding costs days
Type	Named styles with size, line height, weight and letter-spacing per breakpoint	Developer guesses mobile sizes; designer rejects the guess
Spacing	A fixed scale, e.g. 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64 / 96	Arbitrary margins, inconsistent vertical rhythm across templates
Radius and shadow	Two or three of each, named	Every card looks slightly different
Breakpoints	The exact px values the design assumes	Tablet layout invented at build time

Design three widths as a minimum: 1440, 768 and 375. If a section reflows in a non-obvious way — a four-column grid that becomes a horizontal scroller rather than a stack, for instance — draw it. Anything undrawn will be interpreted, and interpretation is where the hours go.

States, edge cases and the content that will actually exist

Designs are made with the best possible content. Sites run on the worst available content. Cover both.

• Interactive states: default, hover, focus-visible, active, disabled, and loading for anything that submits.
• Form states: empty, filled, inline validation error, submission error, success confirmation.
• Content extremes: the longest realistic headline, a two-word headline, a card with no image, an archive with one result and with none.
• Navigation reality: what happens when the client adds a ninth top-level menu item, because they will.
• Media rules: aspect ratios, crop behaviour, and whether portrait uploads are allowed.

Focus-visible deserves its own mention. Accessibility requirements are tightening, and a design that never specifies a visible focus style forces the developer to either invent one or ship the browser default over your careful colour palette. Decide it in Figma.

Say which parts the client can edit

This is the field that separates a Figma file from a WordPress brief, and it is the one most often missing. For every section, mark one of three levels:

• Static. Hardcoded in the template. Cheapest to build, requires a developer to change.
• Field-driven. Editable through defined fields with fixed layout. The client changes copy and images, not structure.
• Composable. Built as a reusable block or pattern the client can place, reorder and duplicate. Most flexible, most expensive, most likely to be broken by an enthusiastic editor.

Getting this wrong in either direction costs money. Over-build everything as composable and you pay for flexibility nobody uses; hardcode a section the client wants to update monthly and you have created a support ticket that recurs forever. Where sections do need to be editable, building them as constrained blocks — the approach in our guide to reusable Gutenberg blocks clients cannot break — gives you flexibility without handing over the ability to wreck the design.

The pre-build Figma to WordPress handoff checklist

Run this before any estimate is given. If an item is missing, either fill it in or write down the assumption the build will proceed on. An explicit assumption is defensible; a silent one is not.

• Build file duplicated, versioned and locked; edit access restricted.
• Every template that exists on the site is drawn, including 404, search results and the archive.
• Three breakpoints per template; non-obvious reflows explicitly drawn.
• Colour, type, spacing, radius and shadow defined as named styles or variables.
• All interactive and form states present.
• Long and short content variants shown for headings, cards and navigation.
• Fonts named with licence and source (self-hosted or CDN) confirmed.
• Icons and images exported or accessible; SVGs outlined where needed.
• Editability level marked per section.
• Animation intent described in one line per element, or explicitly waived.
• Named person who answers design questions during the build.

Ten minutes to run, and it routinely removes a whole review round. When we take on a Figma to WordPress conversion the first thing we do is exactly this pass, and the difference in build time between a file that passes and one that does not is substantial — not because the design is worse, but because every gap becomes a question, and every question becomes a day.

Pixel-perfect, and when it is the wrong goal

“Pixel-perfect” is a reasonable standard for a fixed-width hero at a stated breakpoint. It is a meaningless standard for a responsive site with client-editable content across four viewport widths and two operating systems’ font rendering.

Agree a tolerance instead: type scale and spacing tokens match exactly, colours match exactly, component structure matches exactly, and rendered positions may vary within a few pixels where text reflows. Put that sentence in the scope. It converts an unwinnable argument into a specification.

Also decide the performance target before the design is signed off, not after. A hero with a full-bleed video, three web fonts and a parallax layer will not hit a good Largest Contentful Paint on a mid-range Android phone, whatever the developer does. That is a design decision with an engineering consequence, and it is much cheaper to have the conversation while things are still vectors. For campaign work where conversion depends on load time, the standards in our landing page development service assume that trade-off is settled up front, and the build standards in high-converting WordPress landing pages go further into what to cut.

Frequently asked questions

Do developers still need static exports, or is Figma inspect enough?

Inspect is enough for measurements and CSS values if the file is properly structured with styles and auto layout. You still need explicit exports for raster images and any SVG that needs optimising, plus the source files for logos.

How many breakpoints should we design?

Three as a baseline: a large desktop, a tablet portrait and a small phone. Add a fourth only where a specific template genuinely changes behaviour again, such as a data table or a complex product grid.

Should the design be built with a page builder or a custom theme?

It depends on who maintains the site afterwards. A builder suits clients who want to compose new pages themselves; a custom block theme gives tighter control, cleaner markup and better performance. Decide before the handoff, because it changes how components should be structured.

Who owns fixes when the design changes mid-build?

The party that requested the change. That only works if the file was locked at handoff, so the before and after are provable. Without a locked version, every change becomes a discussion about what was originally agreed.

How long should a conversion take?

It varies far too much with template count, animation and editability to quote generically. What is predictable is the direction: a file that passes the checklist above is estimated quickly and confidently, while a file with gaps gets padded to cover the unknowns.

If you have a design file ready and want a straight answer on what it will take to build, send it over with your target launch date and we will tell you what is missing before anyone commits to a number.

If you want the commercial side of this mapped out, the dedicated developer plans show what a fixed monthly block of hours costs and what it covers.