HTML to Liquid QA Checklist We Run Before Client Delivery

A flawless Figma match means nothing if block.shopify_attributes is missing and merchants cannot select FAQ row four. K2 Devworks built this QA gate after client UAT failed once on converted sections that looked perfect in code review but broke in the theme editor on mobile. Pair with Figma-to-section timing and schema guide before UAT.

Conversion is half the job. QA is what separates agency work from paste-and-pray exports. Client UAT failed once on a section that matched Figma perfectly in code review — unstable schema ids, empty presets, missing block.shopify_attributes, and overlapping mobile block handles meant merchants could not select FAQ rows. The checklist below is K2 Devworks' pre-delivery gate for every HTML-to-Liquid section — whether it originated in the converter, AI section builder, or manual schema writing. Run it per section at PR merge and run the integrated pass before UAT invite. Clients should never be the first people to open the theme editor. See Figma-to-section timing for upstream habits that reduce QA surprises.

Gate 1: Schema and export validation

Before preview deploy, validate {% schema %} JSON parses without trailing commas or BOM characters. Confirm presets array is non-empty for dynamic sections. Every visible HTML text node maps to a setting or block field — no hardcoded marketing copy that should be editable unless documented as intentional. Setting ids are kebab-case, stable, never field_7. Image fields use image_picker; links use url type. Range settings have min/max matching CSS. Cross-reference types with Schema Guide. Run Theme Check CLI on the section file; fix errors before requesting review. Converter output gets the same gate — tools accelerate drafts, not exemptions.

# Theme Check — run before every section PR
shopify theme check --path sections/new-hero-split.liquid

# Manual schema grep habits
# - presets present?
# - block types in presets exist in blocks array?
# - unique ids across section and blocks?

Gate 2: Liquid structure and scoping

Outer wrapper uses #shopify-section-{{ section.id }} or equivalent scoping. No bare h1 or img selectors leaking global styles. {% render %} not {% include %}. Loops over collections and products have explicit limit from settings. Money output uses money filter. Images use image_url with width. block.shopify_attributes on every block wrapper in loops. section.blocks iterated with for block in section.blocks — not hardcoded duplicate rows unless documented static demo. Common Liquid mistakes is the companion reference for this gate.

{%- comment -%} QA fail: missing shopify_attributes {%- endcomment -%}
{% for block in section.blocks %}
  

    
{{ block.settings.question }}
  
{% endfor %}

{%- comment -%} QA pass {%- endcomment -%}
{% for block in section.blocks %}
  

    
{{ block.settings.question }}
  
{% endfor %}

Gate 3: Theme editor click script

On duplicate theme staging, open theme editor for the target JSON template. For each new section execute this script: click section — confirm highlight; edit every setting type — text, richtext, image, url, checkbox, select, range; clear required fields — confirm layout does not collapse; reorder two blocks — confirm storefront updates; add block row — confirm default content; delete block row — confirm no JS errors; duplicate section on page — confirm instances edit independently; confirm section appears in Add section via presets. Log failures in issue tracker with screenshot. This script is non-negotiable before client handoff.

Gate 4: Responsive and visual parity

Compare staging against approved Figma or HTML reference at 375px, 390px, and 1440px widths. Check image cropping, font sizes, stack order, and touch target sizes — minimum 44px for interactive controls. Long merchant headings wrap without overflow hidden clipping descenders. Video backgrounds respect prefers-reduced-motion when theme supports it. RTL if client sells in RTL markets — rare but contractual. Visual parity is not pixel perfection; it is brand-safe layout fidelity. Image optimization guide informs srcset checks during this gate.

Gate 5: Performance smoke on converted CSS

Converted CSS often imports unused rules from Figma export. Grep section CSS for unused selectors; remove dead rules. Confirm no @import of external fonts duplicate to theme.liquid. LCP image on hero sections uses fetchpriority="high" and avoids lazy loading. Below-fold images lazy load. Run Lighthouse mobile on page containing section — not whole site blame if one section regresses score. Performance checklist sets budgets; this gate catches section-level violations early.

Gate 6: JSON template registration

Section file in sections/ is insufficient. Verify templates/*.json references correct type string matching filename. order array includes section key. Default settings in JSON match preset demo when template ships pre-populated. Wrong type string — hero-split versus hero_split — causes silent failure or wrong section load. Migration and greenfield projects both fail here when developers batch-merge ten sections but forget index.json update. Grep templates for section type after every sprint.

{
  "sections": {
    "custom_hero": {
      "type": "hero-split",
      "settings": { "heading": "QA seeded default" }
    }
  },
  "order": ["custom_hero"]
}

Gate 7: Cross-browser and integration

Smoke test Safari iOS and Chrome Android — WebKit flex bugs still appear in converted CSS. If section interacts with cart or variant JS, test add-to-cart on product template with section present. App blocks nearby on product.json — confirm no CSS collisions from converted section. Form sections submit without 404 — action URLs use routes or correct endpoints. Third-party embeds iframes need consent banner compatibility for EU clients.

Gate 8: Documentation and handoff artifacts

PR includes: theme editor screenshot, list of setting ids with merchant-facing labels, note on blocks versus flat, fragile settings called out, link to Loom if complex. README or Notion entry maps section name to Figma component. Merchants receive section tutorial link — not raw schema JSON. Merchant-friendly schema review confirms labels before client sees editor. Undocumented sections generate tickets; documented sections generate referrals.

Integrated UAT pass before client invite

After all sections pass individual gates, run integrated UAT on full template: homepage narrative order, header/footer coexistence, cart drawer not obscured by new sticky sections, collection pages with card snippets from converted grids. PM walks editor without developer present — if PM gets lost, merchants will too. Fix labels and headers before external UAT. Client invite email lists known limitations — e.g., animation reduced on mobile for performance — so feedback stays actionable.

Checklist summary table

• Schema valid, presets present, stable ids
• Theme Check clean on section file
• Scoped CSS, render not include, limits on loops
• block.shopify_attributes on all blocks
• Theme editor click script completed
• Responsive parity 375 / 1440
• Lighthouse smoke on hosting page
• JSON template type and order verified
• Safari iOS smoke test
• PR artifacts and merchant labels documented

AI and converter-specific QA additions

AI-assisted conversion from AI builder or smart detection in converter gets extra review: spurious settings inferred from data attributes that are not merchant-facing; block boundaries splitting one logical row into two block types; CSS not scoped to section.id; duplicate settings for same text node. Human deletes noise before merge. Converter evaluation criteria mirror this QA — production-ready means passes gates, not merely downloads.

When to fail a section back to development

Hard fail — merge blocked: invalid schema, missing presets on marketing section, include tags, unscoped global CSS affecting collection grid, no shopify_attributes on blocks. Soft fail — merge allowed with follow-up issue: minor spacing drift, suboptimal default copy, non-critical image width tuning. Client delivery hard fails only on hard fail list. Soft fails must be triaged before client UAT if visible on homepage above fold. QA is authority to reject PR — not rubber stamp.

Post-delivery monitoring first 72 hours

After client publish, monitor support channel for editor confusion — label fixes ship fast. Watch Core Web Vitals on pages with new sections. Hotfix duplicate theme, not live, unless down. Capture tickets into schema improvements for next section sprint. QA does not end at publish; first merchant edits reveal edge cases automated tools cannot simulate — Word paste into richtext, 4000px PNG uploads, empty block rows left visible.

Gate 9: Accessibility on converted markup

HTML from Figma often ships with div-button patterns and missing alt text. QA checks: interactive elements are button or a with href, images have alt from settings or alt: '' if decorative, accordion sections use details/summary or ARIA tabs with keyboard support, color contrast meets WCAG for text on custom backgrounds, focus outlines visible after CSS scoping. Converted heroes with background images need text contrast overlays — merchants will upload busy photos.

Gate 10: Security and content sanitization

Never output plain text settings with | raw unless intentional. Richtext outputs without double-escaping. External links from url settings get rel="noopener" when target blank. Forms use Shopify form tags where applicable. Sections that embed third-party scripts from settings get client sign-off — marketing pixels in custom HTML settings are XSS vectors if accounts compromise. QA grep for | raw in converted output before merge.

Regression testing after merchant content entry

Post-UAT, merchants upload oversized images and paste Word tables into richtext. Schedule regression QA after content entry freeze — not only after dev complete. Re-run responsive and performance gates on homepage with real assets. Empty states QA repeats when merchants delete all block rows. Training reduces garbage input; regression QA catches what training misses.

QA ownership and sign-off matrix

Developer completes Gates 1–7 and documents results in PR. Senior developer spot-checks one random section per sprint for audit fatigue gaps. PM runs Gate 8 merchant-perspective walkthrough — can they change hero without help? Client UAT only after internal sign-off. Matrix prevents developers approving own work and PMs skipping technical gates because launch date is tomorrow. Launch date moves if hard fail exists — non-negotiable on retainers that value uptime.

Converter validation integration

When sections originate in converter or AI builder, export validation output attaches to PR — schema parse, preset check, scoping warnings. Automated pass does not skip Gates 3–4 manual editor and responsive testing. Validators catch typos; humans catch merchant confusion. Figma to section workflow ends at QA gate, not at download.

Checklist as client deliverable

Enterprise clients sometimes request QA evidence. We export completed checklist — gates, dates, tester initials, screenshot links — as PDF appendix to handoff package. Not every client needs it; Plus and regulated verticals increasingly do. Checklist doubles as internal quality metric: track hard fails per developer per quarter for coaching, not punishment.

Batch QA for multi-section sprints

When ten sections land in one sprint, run integrated Gate 3–4 on full homepage after individual section PRs merge — block interactions and CSS collisions appear only in combination. Order QA: schema batch Theme Check, per-section editor script, full template responsive pass, Lighthouse on assembled page. Batch QA day is calendar-blocked before UAT invite; no merging section eleven before batch QA completes on first ten.

Teaching clients minimal safe QA

Merchants benefit knowing safe editor actions versus risky ones. Handoff covers: safe — text, images, reorder blocks; risky — delete section, rename template, duplicate then forget which is live; call us — custom Liquid blocks, app block removal, JSON template edits. Client mini-QA after content entry: click every homepage section once, confirm no layout break. Reduces panic emails when they accidentally hide a section by toggling visibility wrong.

Continuous improvement from QA failures

Every hard fail becomes a prevention: missing presets added to Theme Check custom rule discussion; recurring shopify_attributes omission triggers converter template update; third mobile overflow triggers Figma export checklist update. QA is not gatekeeping — it is feedback loop to tooling and training. Converter evaluation criteria evolve from real QA failure data, not feature marketing.

QA timing in the sprint calendar

Block QA day before UAT on calendar — not Friday 4pm before Monday client demo. Developers need fix buffer; PM needs re-walk buffer. Integrated QA after content freeze, not before, catches real-world merchant mistakes. Two QA passes — post-dev and post-content — cost less than one emergency weekend when client publishes broken homepage before vacation.

Clients remember the first time they edited a section without calling you. QA is how you manufacture that moment.

Adopt the checklist on your next export

Copy the ten gates into your PR template today. Run Gate 1 and Gate 3 on the next section before asking for review. Pair with section workflow for process context and HTML to Liquid guide for conversion fundamentals. QA checklist is unglamorous — it is also why retainers renew. Merchants trust agencies that never make them the first testers of their own storefront.

Print the checklist summary table for your desk. Laminated, if you are old school. The physical reminder beats another Notion page nobody opens during crunch week. Quality is habitual — gates become fast when you have run them on four hundred sections.

Assign a QA champion per sprint — not always the same senior developer — so junior developers learn gates by executing them, not only reading about them. Rotating ownership spreads checklist muscle memory across the team and prevents single-point-of-failure when your usual QA person is on vacation during launch week.

The checklist is living documentation — update it when Shopify ships new schema types or when a new failure mode appears twice. Stale QA docs become shelfware; ours changed six times in 2025 as converter validation and theme editor behavior evolved. Treat updates as team investment, not documentation chore. A checklist that evolves is a checklist developers actually use under deadline pressure. Version the checklist in Git with a one-line changelog when gates change. Developers trust process they can see evolved deliberately, not mysteriously. Share changelog entries in sprint retros so the team knows why a gate was added and buys into the process fully on every client project we deliver now onward.