How We Convert Figma HTML to Shopify Sections in Under 2 Hours

A furniture client once asked why a single hero module took a full day. Dhruv Goyani timed every phase of that sprint — export cleanup, converter pass, schema labels, scoped CSS, JSON template wiring — and found forty minutes lost to unfixed Figma export noise. The two-hour target below follows the section workflow K2 Devworks runs on every client project.

"Two hours per section" sounded like marketing until we actually timed sprints with a stopwatch. Not every module qualifies — interactive tabs with custom JS still take a day — but standard marketing sections (split hero, three-up features, logo strip, FAQ accordion, testimonial slider) routinely land in 90–120 minutes from Figma export to theme editor approval. The trick is not typing faster. It is eliminating decision fatigue: fixed export cleanup steps, converter-first schema, a CSS scoping template, and a QA script you do not improvise. Below is the minute-by-minute breakdown Dhruv uses for client work and Nishad uses when training junior developers. Total target: 120 minutes.

Minutes 0–15: Figma export and HTML cleanup

Open the approved frame in Dev Mode. Copy the HTML structure for the module — not the entire page. Strip wrapper divs Figma adds that exist only for canvas positioning. Replace absolute positioning with flex or grid unless the design genuinely overlaps elements; absolute HTML converts poorly to responsive sections. Rename generic classes: Frame427 → hero-split__content. Delete inline styles that hardcode width: 1440px. Note repeatable rows and mark them in comments so you remember to export in block mode. If design is not final, stop here. Converting twice is what blows the two-hour budget.

Assets out of Figma

Export SVG icons and hero images separately at 2x when raster. Drop icons into assets/ with semantic names before coding. For image placeholders in HTML, use a temporary src; you will replace with {{ section.settings.image | image_url: width: 1200 }} after schema exists. We upload permanent assets to the theme files panel during QA, not during conversion. HTML to Shopify Liquid Guide covers export pitfalls we see on every new hire's first project.

Minutes 15–35: Converter pass and first export

Paste cleaned HTML into the converter workspace. Pick Flat for heroes and single-column promos; pick Block when you marked repeatables. Generate section.liquid, download, and drop into sections/ with the final filename — renaming later costs JSON edits. Open the file and scan inferred settings: delete phantom fields from data attributes, merge duplicate text settings, change generic labels to merchant language. This pass takes twenty minutes when you focus only on schema — no CSS tweaking yet. Cross-check setting types against Schema Guide for images, URLs, and richtext.

{%- comment -%} Typical hero output after converter + 10 min cleanup {%- endcomment -%}

  

    {% if section.settings.image != blank %}
      
    {% endif %}
  
  

  {% if section.settings.eyebrow != blank %}
    
{{ section.settings.eyebrow }}
  {% endif %}
    
{{ section.settings.heading }}
    
{{ section.settings.body }}
    {% if section.settings.button_label != blank %}
      
        {{ section.settings.button_label }}
      
    {% endif %}
  

Minutes 35–55: Block loops and Liquid edge cases

For block sections, verify the {% for block in section.blocks %} loop wraps every repeatable row, each row has {{ block.shopify_attributes }}, and block types in schema match the HTML structure. Add {% if block.settings.image != blank %} guards so empty merchant rows do not render broken image icons. Set max_blocks in schema — we use 12 for FAQs, 8 for sliders unless the client pays for more. Presets must include at least two blocks so the section does not look empty on insert. Read Dynamic Blocks Guide if loop output looks wrong after converter export.

Minutes 55–80: Scoped CSS and responsive tweaks

Converter CSS is a starting point, not finished styling. Prefix every selector with #shopify-section-{{ section.id }} or nest inside a single wrapper class. Fix mobile stacking: Figma desktop exports often assume 1200px width. We write mobile-first min-width media queries to match the client theme's breakpoints — usually 750px and 990px on Dawn. Remove unused rules the converter carried from Figma class names you deleted. Do not import Google Fonts in section CSS; use theme font settings. This twenty-five-minute block is where junior developers lose an extra hour by tweaking hover animations — ship layout parity first, polish in a follow-up ticket if budget allows.

#shopify-section-{{ section.id }} .hero-split {
  display: grid;
  gap: 1.5rem;
}
@media screen and (min-width: 990px) {
  #shopify-section-{{ section.id }} .hero-split {
    grid-template-columns: 1fr 1fr;
    align-items: center;
  }
}

Minutes 80–95: JSON template registration and presets

Add the section to templates/index.json with realistic setting values copied from Figma copy deck. Confirm the type string matches filename. If the section is not ready for homepage but you want to preview, create templates/page.section-test.json in a dev branch — some teams keep a hidden template for QA. Verify presets array in schema so merchants can Add section elsewhere later. How Shopify Sections Work explains template JSON when order array disputes continue with PM.

Minutes 95–110: Theme editor QA sprint

Deploy to duplicate theme. Open customizer on mobile and desktop. Click each block row — selection highlight must match. Toggle settings. Clear optional fields and confirm layout does not collapse. Paste long merchant-style copy into richtext to test overflow. Click primary CTA to confirm url setting works with shopify:// routes. Add a second instance of the section to test scoped CSS isolation. This is non-negotiable; we have never regretted the fifteen minutes. We have regretted skipping it.

Minutes 110–120: PR, screenshot, handoff note

Commit with message feat(sections): add hero-split from Figma module 3. PR body: before/after screenshot, setting ids list, block max count, known limitations. Slack client channel: "Hero split ready for review on staging — edit heading and CTA in theme editor, blocks not needed." Done. If you are over 120 minutes, log which phase slipped — usually CSS or unfinalized design. Best HTML to Liquid Converter and Hero Conversion Guide supplement this timing for component-specific quirks.

What breaks the two-hour budget

• Design changes mid-conversion — treat as new sprint.
• Missing mobile frame — you invent responsive rules from scratch.
• Client theme without OS 2.0 JSON templates — migration work is separate.
• Custom JS carousels — use theme or library patterns, do not npm install in theme without build step.
• Twelve-setting hero with four nested grids — simplify schema for merchants.

Batching: four sections in one afternoon

When Figma delivers a full homepage, we batch by structural similarity: all block-loop sections back-to-back while block patterns are fresh in muscle memory, then flat heroes. We keep converter and Cheat Sheet on separate monitors — converter on left, reference on right. First section of the day takes 150 minutes; fourth takes 75 because CSS scoping template and PR format are copy-paste. That is how agencies make margin on fixed-price theme work. Speed is a skill built from repeatable phases, not shortcuts on presets or QA.

Real client example: four-up feature grid in 105 minutes

Last month we timed a four-up icon feature grid for a supplement brand: Figma export with four identical card rows, block export from converter, schema labels edited to Icon, Heading, Description, twelve-minute CSS pass to match Dawn spacing, JSON registration on homepage, QA on iPhone 14 width. Total 105 minutes. The client changed icon SVGs themselves the next day — block architecture worked. The same module quoted at six hours by another agency was hardcoded HTML with no presets. Timing discipline is competitive advantage, not vanity metrics.

Converter vs hand-code: when we still type Liquid manually

We hand-write when Liquid logic exceeds markup: collection sorting rules, metafield-driven badges, market-specific copy, cart thresholds. We still start from converter HTML shell when the layout is static — strip generated schema, keep scoped wrapper, inject logic, re-add schema by hand. HTML to Liquid Guide describes hybrid workflow. Junior mistake: hand-writing entire FAQ from scratch when converter block export would have produced loop and schema in minute fifteen. Senior mistake: running converter on a section that is 80% Liquid logic and fighting inferred settings.

Checklist we tape to the monitor

1. HTML cleaned and repeatables marked
2. Flat or block mode chosen before paste
3. Labels merchant-ready, ids stable
4. block.shopify_attributes on every row
5. CSS scoped to section.id
6. Presets non-empty with two blocks minimum
7. index.json type matches filename
8. Mobile + desktop QA complete
9. PR screenshot attached

After two hours: what we do not ship same day

Animation polish, A/B copy variants, alternate color schemes beyond the design system, and integration with apps that need API keys — these are follow-up tickets. The two-hour window is structural correctness: editable, scoped, discoverable in theme editor, visually matching approved desktop and mobile frames. Clients appreciate honest phase gates more than a hero that animates but has no preset. Schema Guide and Cheat Sheet stay open for the polish phase on day two.

Figma handoff red flags that add hours

Red flags before we commit to two-hour timing: components not published as variants in Figma, desktop-only frames, raster text in heroes, mixed grid systems, or auto-layout frames collapsed to absolute positioning in export plugins. We send one consolidated feedback PDF to design before conversion starts. One hour of design cleanup saves three hours of CSS surgery. Hero conversion guide lists HTML patterns that convert cleanly versus patterns that need design revision.

Tailwind, Bootstrap, and client theme CSS coexistence

When the HTML export is Tailwind-heavy but the client theme is Dawn CSS, we do not ship Tailwind CDN in theme.liquid — we map utilities to scoped BEM in the twenty-minute CSS phase. Mixing Tailwind JIT with theme base.css creates specificity wars. If the client theme officially uses Tailwind via build pipeline, we align with their config instead. Ask once at kickoff; assume wrong and you rewrite CSS twice.

Accessibility pass in the last ten minutes

Quick a11y before PR: heading order not skipped for styling, focus states visible on CTAs, accordion uses details/summary or aria-expanded pattern, decorative images have alt="", meaningful images have alt from settings. Merchants will not fix keyboard traps. Two minutes with tab key through the section prevents compliance escalations on enterprise clients. Liquid for Beginners does not cover a11y — we keep WCAG checklist in Notion linked from PR template.

Scaling the pipeline across a team of four

Nishad trains converters on the same minute buckets so estimates align: 15 export, 20 converter, 20 blocks/CSS, 15 JSON, 15 QA, 10 PR. Dhruv reviews schema labels only on merged PRs to avoid bottleneck. Shared snippet library for card-product and icon reduces CSS phase variance. Team throughput: four standard sections per developer per day when designs are approved. Bottleneck is always design approval, not Liquid typing. Converter evaluation guide explains why we standardized on one tool instead of four.

End-to-end timing worksheet (copy for your team)

Copy this into your project tracker: 0–15 export cleanup, 15–35 converter and schema labels, 35–55 block loops and guards, 55–80 scoped CSS responsive, 80–95 JSON template, 95–110 theme editor QA, 110–120 PR and handoff note. Log actuals per section for two sprints — your team will discover whether CSS or schema is your systematic overrun, then fix the process instead of blaming Figma. Ours was CSS until we standardized breakpoint variables from the parent theme. Converter time dropped once export cleanup was non-negotiable in design handoff.

Under two hours is achievable on approved designs because the decisions are made before the timer starts: flat or block, filename, parent theme breakpoints, merchant labels. Everything else is execution. Ship the first section with a stopwatch; adjust the worksheet; then batch the rest of the homepage with confidence.

Under two hours is a discipline, not a dare. Skip schema labels or QA and you are just moving the work to launch night.

If you are still over budget after three timed sections, the problem is upstream: design export quality, unclear block boundaries, or a theme without JSON templates. Fix upstream once instead of shaving QA on every module. Reusable sections guide helps when clients want the same module on landing pages and homepage — clone via presets, not duplicate files. Timed workflow only works when scope is frozen for that sprint.