All WordPress HTML Templates Forms & Webhooks AI & Tools
HTML Templates

From Figma to Production HTML: A Repeatable Handoff Process

A repeatable figma to html workflow: generate CSS from Dev Mode tokens, align breakpoints, map variants to classes, and accept builds by visual diff.

A real working moment illustrating the theme of an article about figma to html workflow. Wide 16:9 banner, one strong focal point, magazine editorial quality, authentic and unstaged.
Key Takeaways

  • Export Figma Variables once, generate CSS custom properties from them in a build step, and ban hand-typed hex values in review. The Variables REST API is Enterprise-only, so budget for a plugin export path on smaller plans.
  • Reconcile Figma frame widths with your CSS breakpoints before design starts. A 1440px frame with a 1320px container maps cleanly to Bootstrap 5’s xxl; a 1366px frame with a 1200px container does not, and you’ll argue about it for a month.
  • Figma variants should map one to one onto class modifiers. If a component has 48 variant combinations and your CSS has 6 modifiers, one of the two is wrong.
  • Dev Mode annotations and Code Connect remove about 70 percent of the “what size is this gap” questions. They don’t remove state coverage: focus, loading, error, empty and 2x-length strings still need to be explicitly requested.
  • Acceptance should be a diff, not an opinion. Playwright screenshot comparisons at three viewports catch drift that nobody notices in a Zoom walkthrough.

The handoff is a contract, not a file

Treat the Figma file as a specification and you will be disappointed, because files change silently. Treat it as a contract and you start asking contract questions: what is guaranteed, what is negotiable, who signs off, what happens when reality contradicts it.

Three things we agree in writing before design work starts, usually in a pinned Figma comment and the project README:

  • The primitive set is frozen. Colour ramps, type scale, spacing scale, radii, shadows, breakpoints. Additions require a five-minute conversation, not a new local style.
  • Design owns intent, development owns implementation. If the design says 23px of padding and the spacing scale has 20 and 24, development ships 24 and nobody escalates.
  • Sections get a status. Figma’s “Ready for dev” marker is crude but it works. Anything without it is a sketch, and sketches don’t get built.

That third point saves the most time. We have had whole components built from a frame the designer considered an experiment. Twice.

Figma Dev Mode tokens to CSS custom properties

Figma Variables, surfaced through Dev Mode, finally made this part mechanical. Variables support modes, which means light and dark live in the same collection rather than two divergent files. They can also be aliased, so color/bg/surface points at palette/neutral/0 instead of duplicating a hex.

The catch: the Variables REST API (GET /v1/files/:file_key/variables/local) requires an Enterprise plan. On Professional or Organization plans you need a plugin export (Tokens Studio, or a 40-line internal plugin using the figma.variables API) and someone has to remember to run it. Put that export file in the repo and make it a reviewable artefact.

Here is the shape we normalise to, and the transform that produces CSS:

// tokens/build.mjs  -  run via: node tokens/build.mjs
import { readFile, writeFile } from "node:fs/promises";

const raw = JSON.parse(await readFile("tokens/figma-export.json", "utf8"));

// Figma names use slashes: "color/bg/surface" -> --color-bg-surface
const toVar = (name) => "--" + name.replace(/\//g, "-").toLowerCase();

const rgbaToHex = ({ r, g, b, a = 1 }) => {
  const h = (n) => Math.round(n * 255).toString(16).padStart(2, "0");
  return a === 1 ? #${h(r)}${h(g)}${h(b)} : #${h(r)}${h(g)}${h(b)}${h(a)};
};

const render = (mode) =>
  raw.variables
    .filter((v) => v.valuesByMode[mode] !== undefined)
    .map((v) => {
      const val = v.valuesByMode[mode];
      // Aliases arrive as { type: "VARIABLE_ALIAS", id }: resolve to another var()
      if (val?.type === "VARIABLE_ALIAS") {
        const target = raw.variables.find((x) => x.id === val.id);
        return   ${toVar(v.name)}: var(${toVar(target.name)});;
      }
      if (v.resolvedType === "COLOR") return   ${toVar(v.name)}: ${rgbaToHex(val)};;
      if (v.resolvedType === "FLOAT") return   ${toVar(v.name)}: ${val}px;;
      return   ${toVar(v.name)}: ${val};;
    })
    .join("\n");

const css = `/ GENERATED FROM FIGMA. Do not edit by hand. /
:root {
${render("light")}
}

[data-bs-theme="dark"] {
${render("dark")}
}
`;

await writeFile("src/scss/_tokens.generated.css", css);

Two rules make this stick. First, the generated file is committed to the repo, so a token change shows as a readable diff in the PR. Second, a lint rule rejects raw hex in component CSS:

// .stylelintrc.js
module.exports = {
  rules: {
    "color-no-hex": [true, { ignoreFiles: ["**/_tokens.generated.css"] }],
    "declaration-property-value-allowed-list": {
      // spacing must come from the scale, not from someone's ruler
      "/^(margin|padding|gap)/": [/^var\(--space-/, "0", "auto", "inherit"],
    },
  },
};

That second rule has caught more drift than any design review. It also forces an honest conversation when a designer genuinely needs a new spacing step. If you are doing theming on top of this, the mode mapping matters more than the token names. Our write-up on dark mode tokens, contrast and the flash of wrong theme covers the parts Figma cannot model, like how the theme is chosen before first paint.

Reconcile frame widths with breakpoints on day one

This is the cheapest meeting you will ever hold, and almost nobody holds it. Designers pick frame widths from device presets. Developers inherit breakpoints from a framework. The two rarely line up, and the gap surfaces as “it looks cramped on my laptop.”

Pick three or four design widths that sit cleanly inside your CSS. With Bootstrap 5 we design at 390, 768, 1200 and 1440:

  • 390 is below sm (576), so it exercises the base styles.
  • 768 is exactly md, which forces the designer to decide what happens at the boundary rather than near it.
  • 1440 gives you the 1320px xxl container with real gutters, so the designer sees the actual max content width.

Design at 1366 or 1512 and every container measurement in the file is a lie that someone will faithfully implement. If your team is still choosing a framework, that decision affects this more than people expect. Utility-first and component-first systems want different things from a Figma file, which we worked through in Bootstrap vs Tailwind: choosing by team, not by hype.

Variants in, class modifiers out

A component in Figma with Variant, Size, Icon and State properties produces a combinatorial grid. Your CSS has a base class and a handful of modifiers. Make the mapping explicit and write it down. The alternative is each developer inventing their own translation.

Figma’s Code Connect does exactly this. It is the single highest-leverage feature in design handoff that most teams skip. Publish a mapping once and anyone opening that component in Dev Mode sees your actual markup instead of Figma’s auto-generated CSS guess.

// figma/button.figma.js
import figma, { html } from "@figma/code-connect/html";

figma.connect(
  "https://www.figma.com/design/FILEKEY/DS?node-id=412-1908",
  {
    props: {
      variant: figma.enum("Variant", {
        Primary: "btn-primary",
        Secondary: "btn-outline-secondary",
        Danger: "btn-danger",
      }),
      size: figma.enum("Size", { Default: "", Large: "btn-lg", Small: "btn-sm" }),
      label: figma.string("Label"),
    },
    // Dev Mode now shows this exact snippet, filled from the selected variant
    example: ({ variant, size, label }) =>
      html<button type="button" class="btn ${variant} ${size}">${label}</button>,
  }
);

Publish with npx figma connect publish in CI on merge to main. It takes about 25 seconds for a 30-component library and ends the “which class is the ghost button” Slack thread permanently.

If a Figma component has 48 reachable variant combinations and your CSS exposes 6 modifiers, stop and look at it. Usually the design file is encoding states that should be CSS pseudo-classes, or one-off marketing treatments that do not belong in a library at all.

What Figma will never tell you

Every file is complete and every file is incomplete in the same five ways. Ask for these explicitly during design, not during QA:

  • Focus states. Hover gets designed, focus almost never does. Default to a visible :focus-visible ring built from a token and get it approved once, globally.
  • Long content. Run the German rule: every string gets 1.6x longer and the layout must survive. Names break cards, product titles break tables. Our piece on responsive data tables that survive real content exists because of exactly this failure.
  • Empty, loading and error. Three extra frames per data-driven component. Non-negotiable on anything with an API behind it.
  • Image behaviour. Figma masks a photo; the browser needs object-fit, an aspect-ratio and a focal point. Ask which edge is protected on narrow viewports.
  • Motion. Duration and easing, or you will get 300ms ease on everything and a designer who is quietly unhappy for six months.

Prototype links are useful for communicating intent and useless as a spec. If an interaction has timing that matters, get it written in an annotation with numbers.

The build pass: structure before pixels

We build in a deliberately unglamorous order, and it halves the rework.

  1. Semantic skeleton. Headings, landmarks, lists, forms, real copy pasted from the content doc. No colours, no spacing. Takes an hour on a marketing page and surfaces heading-level problems while they are still cheap to fix.
  2. Layout. Container, grid, breakpoints. Still no decoration.
  3. Tokens applied. Colour, type, spacing from the generated custom properties only.
  4. Component states. Hover, focus, disabled, active, plus the empty and error frames.
  5. Performance pass. Image formats and sizes, font loading, anything blocking the hero. The LCP wins that actually move the number are mostly decided here, not in a later optimisation sprint.

Starting from a mature component library compresses steps 2 through 4 heavily. That is the honest argument for a template: when the Figma file already uses a Bootstrap 5 grid and the markup patterns exist, you are mapping rather than inventing. We lean on Canvas for this on client work, which is why our Figma libraries are built against its class names rather than against abstract shapes.

Acceptance by diff, not by vibes

The final review should produce evidence. A side-by-side walkthrough on a shared screen catches big errors and misses every 4px gap in the file.

// tests/visual.spec.js
import { test, expect } from "@playwright/test";

const pages = ["/", "/pricing", "/contact"];
const widths = [390, 768, 1440];

for (const path of pages) {
  for (const width of widths) {
    test(${path} @ ${width}, async ({ page }) => {
      await page.setViewportSize({ width, height: 900 });
      await page.goto(path);
      // kill animation flake before the shot
      await page.addStyleTag({ content: ,::before,*::after{animation:none!important;transition:none!important} });
      await expect(page).toHaveScreenshot(${path.replace(/\//g, "_")}-${width}.png, {
        maxDiffPixelRatio: 0.001,
      });
    });
  }
}

Baselines come from the first approved build, not from Figma exports. Comparing rendered HTML to a Figma PNG is a trap: text rendering, hinting and subpixel differences will produce a 3 percent diff on a pixel-perfect page, and you will stop trusting the tool within a week.

Alongside the diffs, run a short checklist that does not change between projects: keyboard path through every interactive element, contrast check on the three lowest-contrast token pairs, 200 percent browser zoom, long-string pass, and prefers-reduced-motion. Fifteen minutes. It finds something almost every time.

On AI-generated markup from designs

Figma’s Dev Mode MCP server made it genuinely practical to point an agent at a selected frame and get markup back. The 2026 version is far better than the “design to code” plugins of 2022. It earns its place on the boring middle ground: a long marketing section with repeated cards, a table of specs, a footer.

It struggles with the things that matter most. Heading hierarchy, landmark structure, form labelling, token discipline and state coverage are exactly where generated output drifts, and those are the expensive defects. Our working rule: let it draft the skeleton, then run your own token lint and accessibility pass over the result before it goes near a PR. The wider version of that argument is in our notes on what earns a place in the 2026 AI toolchain.

Frequently Asked Questions

Do I need a paid Figma Dev Mode seat for this process?

You need a Dev seat to use Dev Mode, annotations and Code Connect, and Enterprise for the Variables REST API. Without either, you can still run most of the workflow using a free plugin to export variables as JSON and keeping the transform script identical. The expensive part is not the licence, it is nobody owning the export.

How many breakpoints should a design file actually cover?

Three or four, chosen to match your CSS. We use 390, 768, 1200 and 1440 with Bootstrap 5. Designing every component at every breakpoint is waste. Design at the two or three points where the layout genuinely reflows, write a rule for everything between, and move on.

Should designers write HTML?

No, but they should read it. The highest-performing pairs we have worked with have designers who can open DevTools, inspect a computed value and say “that gap is 20, the token is 24.” That skill removes an entire round trip and takes about a day to teach.

What do we do when the design can’t be built as specified?

Flag it inside the first build pass, with a screenshot and a specific alternative, not at acceptance. The common cases are text that overflows in other languages, sticky elements that fight mobile browser chrome, and blend modes that behave differently across browsers. A 10-minute conversation at step 2 beats a redesign at step 5.

Is a pixel-perfect build the right goal?

Usually not, and treating it as the goal produces brittle code. Match the tokens exactly, match the layout intent exactly, and allow rendering differences in text metrics and small optical adjustments. If a stakeholder insists on pixel equality against a Figma PNG, show them the same page in Safari and Chrome side by side.

Where to start tomorrow

Pick one page on your current project. Export the Figma variables, generate a tokens file, add the Stylelint rules that ban raw hex and off-scale spacing, then fix whatever the linter screams about. That single pass will show you how far your design file and your CSS have actually drifted. The number is usually worse than anyone expects.

Do that before you touch Code Connect, visual diffs or any of the rest. A handoff process built on a shared set of primitives gets stricter easily. One built on good intentions just gets older.

design handoff for developers checklist export figma variables as design tokens figma breakpoints bootstrap 5 mapping figma code connect html example figma dev mode tokens to css variables figma to html workflow stylelint rules design tokens visual regression testing playwright design handoff