Shopify Section Client Handoff Checklist We Use After Every Build

The best handoffs feel boring: merchants edit copy confidently, tickets stay rare, and the agency moves to the next build. Boring handoffs are earned — usually after a merchant reordered FAQ blocks at 11pm before a sale and discovered half the settings did nothing. This checklist is the gate we run before any client sees the theme editor.

Developers celebrate when sections render correctly in preview. Then the client logs into the theme editor, adds a fourth instance of the hero, deletes the wrong block, and emails that "the site broke." The code was fine—the handoff was not. After years of agency work, we treat section delivery like product launch: QA checklist, documentation, training, and explicit ownership boundaries. This is the exact checklist we run before closing Shopify section projects, whether the sections came from our converter or hand-written Liquid over two weeks.

Phase 1: Technical QA on sections

Before a merchant touches anything, every custom section file gets a technical pass in isolation and in context on real templates. Isolation means adding the section to a blank JSON template in dev—verify presets appear, defaults render, empty states do not collapse layout. In context means the homepage, product, and collection templates the client actually uses, with real products, sold-out variants, long titles, and missing images. We keep a "stress test" product in dev stores: no image, 200-character title, zero inventory, three option dimensions. Sections that only look good on the demo SKU are not done.

Schema validation items

• JSON in {% schema %} parses—no trailing commas, no duplicate ids
• Every setting id referenced in Liquid exists in schema
• presets array is non-empty for sections merchants should add dynamically
• Block types in presets exist in blocks definition
• max_blocks set on repeatables that could explode (logos, testimonials)
• Labels are merchant language, not dev jargon—Heading not hero_h1_text
• Header settings group fields into Content, Layout, Colors

We run schema through Schema Generator mental model—if a field is not obvious to a non-developer, rename it. Cross-reference Schema Guide for setting types; using text where richtext is needed creates support debt when merchants paste paragraphs.

Liquid and markup checks

{%- comment -%} Every block in a loop needs shopify_attributes {%- endcomment -%}
{% for block in section.blocks %}
  

    {{ block.settings.title | escape }}
  
{% endfor %}

Missing block.shopify_attributes is the top reason merchants say "I can't click the right thing in the editor." Images need width parameters—image_url: width: 1200—not full-resolution uploads that crush mobile. Use escape on plain text; use rte wrappers on richtext. Link fields should handle blank—{% if section.settings.button_link != blank %}—so merchants can hide CTAs without a code deploy.

Phase 2: CSS and theme integration

Handoff is not the time to discover global CSS bleed. Confirm every selector is scoped under #shopify-section-{{ section.id }} or lives in {% stylesheet %} tags Shopify scopes automatically. Compare heading fonts against the parent theme—Dawn, Prestige, and custom builds use different tokens. If you hardcoded font-family: Helvetica because Figma said so, fix it before handoff or document the intentional deviation. Test with theme color schemes if the client uses them; dark mode surprises kill trust.

Responsive breakpoints merchants will hit

Test at 320px, 375px, 768px, and 1440px minimum. Merchants preview on iPhones; developers build on 27-inch monitors. Collapsed navigation overlapping hero CTAs is the most common mobile defect we catch in handoff QA. Document any section that intentionally hides content on mobile via CSS so merchants do not think images "disappeared." Video backgrounds need poster images and reduced-motion fallbacks—accessibility and bandwidth matter for luxury clients too.

Third-party font and script conflicts

Before handoff, load the client's actual marketing stack—Klaviyo forms, Gorgias chat, heatmap snippets. Sections with z-index stacking contexts can hide chat widgets or cookie banners. Fix or document. Do not assume a clean dev store represents production. If a section uses external libraries, confirm they are not duplicated when merchants install apps that ship the same dependency.

Phase 3: Presets and default content

Presets are onboarding. A preset named "Custom section 1" tells the merchant nothing. Name presets after use cases—"Homepage hero", "Sale banner", "About FAQ". Seed realistic copy, not lorem ipsum, unless the client is a content agency that explicitly wants placeholders. Include two block rows on FAQ presets so merchants see repetition work. Image pickers should default to theme-appropriate placeholders or leave empty with a visible gray box—not broken image icons. This is where merchant-friendly schema thinking pays off.

"presets": [
  {
    "name": "Homepage FAQ",
    "settings": { "heading": "Common questions" },
    "blocks": [
      { "type": "faq_row", "settings": { "question": "Shipping time?", "answer": "
3–5 business days domestically.
" } },
      { "type": "faq_row", "settings": { "question": "Returns?", "answer": "
30-day returns on unworn items.
" } }
    ]
  }
]

Phase 4: Template map documentation

Merchants do not think in filenames—they think in pages. Deliver a template map: Homepage uses index.json with these sections in recommended order; Product uses these; Collection uses these. Note which sections are required for layout integrity—e.g. main-product should not be removed—and which are optional marketing bands. Flag app blocks separately: "Reviews slot—install Judge.me before expecting content here." Link internally to app blocks vs sections for technical clients.

Phase 5: Merchant training session

Live 45-minute Zoom, recorded. Agenda: navigate theme editor, add section from preset, edit settings, reorder blocks, duplicate section, hide versus delete. Show one intentional mistake and fix it—delete a block, undo, restore preset. Merchants remember recovery, not happy paths. Assign homework: "Change homepage hero headline before go-live." Homework surfaces confusion while you still have retainer hours.

What we explicitly tell merchants not to do

• Edit code or JSON templates without developer approval
• Install random apps without checking product page block slots
• Duplicate main-product section—use blocks inside one product section
• Upload unoptimized 5MB PNGs into image_picker fields
• Remove sold-out badges or inventory messaging without legal/compliance sign-off

Phase 6: Performance and accessibility sign-off

Run Lighthouse on templates with custom sections enabled. Check CLS when hero images load—use aspect-ratio CSS and width/height on images. Keyboard-test accordions and sliders; merchants will not, but lawsuits and SEO matter. Alt text: document that image_picker alt fields must be filled—empty alts are a handoff failure if your schema exposes alt settings. Tie to our launch performance checklist.

Phase 7: Git, versioning, and support boundaries

Tag the theme release v1.0-handoff in Git with a changelog listing new section files and template diffs. Tell the client: editor changes live in theme JSON backups; code changes need agency hours. If you use Shopify GitHub integration, document branch workflow—merchants sometimes enable "edit code" and fork reality. Define response time for "section bug" versus "how do I change text"—only one is a bug.

Handoff packet deliverables

1. PDF or Notion: template map with screenshots
2. Recorded training video links
3. Section catalog: name, purpose, recommended templates
4. App dependency list
5. Known limitations—e.g. max 6 logo blocks
6. Emergency rollback: duplicate theme name, date
7. Contact matrix: agency vs Shopify Plus support vs app vendors

Editor permissions and staff accounts

Before training, confirm which staff accounts can edit themes. Merchants with full permissions will edit code; restrict theme code access when possible and route content edits through the customizer. Document who is allowed to publish themes versus preview only. We have seen junior marketers publish DEBUG duplicates because the theme list was never explained. Create a short internal SOP for the client: duplicate before big edits, never delete the live theme, name duplicates with dates.

Content governance after handoff

Brand teams want seasonal homepage rotations—BFCM, Valentine's, summer sale. Presets make rotation fast if you seeded variants: "Homepage hero — sale" preset beside default hero. Without governance, merchants clone sections endlessly and wonder why mobile performance collapsed. Set a soft cap in documentation: homepage should stay under N sections; retire old bands instead of stacking. Offer quarterly section audits as paid maintenance rather than free cleanup.

Converter-to-production handoff specifics

When sections originate from HTML to Liquid conversion, extra steps apply. Re-read exported schema labels—they may still say "Text field 3." Rename to merchant language. Re-scan HTML class names for Tailwind leftovers that conflict with theme CSS. Re-test block detection: converters infer repeatables; verify FAQ rows became blocks, not flattened settings. Our Figma-to-section workflow ends with this handoff phase, not at export.

Sign-off meeting agenda (copy-paste for agencies)

1. Walk template map: homepage, product, collection, cart
2. Live demo: add section from preset, edit text, reorder block, undo mistake
3. Show app dependencies and empty states when apps missing
4. Review performance and image upload guidelines
5. Confirm backup theme name and publish procedure
6. Assign homework: one content edit before go-live
7. Share support tiers and contact emails

Record the session. Merchants forget; video saves retainers. Send follow-up email with links within twenty-four hours while enthusiasm is high. Include cheat sheet for technical liaisons only—overwhelming store operators with Liquid docs backfires.

A section export is a draft. Handoff-ready means a merchant can use it without calling you—test that by letting a non-developer on your team configure the homepage cold.

Localization and markets handoff

If the client uses Shopify Markets or multiple languages, handoff must cover which strings live in theme locale files versus section settings. Merchants often edit English in the editor while French stays stale in JSON. Document the translation workflow: theme content, Translate & Adapt app, or agency-managed locale files. Test one non-default language on homepage and product templates before sign-off. Currency formatting on section settings that display prices must use money filters, not hardcoded dollar signs—international launches expose that gap instantly.

Analytics and tracking after launch

Custom sections frequently contain CTAs merchants want tracked. Add data attributes or documented CSS hooks for GTM teams—do not hardcode GA snippets inside section Liquid unless the client explicitly owns that debt. Hero buttons should use url settings so swapped links do not break event bindings tied to href. We provide a one-page "tracking hooks" appendix listing section ids and recommended data-layer events for common interactions: hero CTA click, FAQ expand, video play.

Retainer-friendly support tiers

Define three support tiers in writing before handoff completes. Tier one: merchant self-serve via training and docs—text edits, image swaps, reordering blocks. Tier two: agency small tasks under retainer—new preset, label tweak, one additional block type. Tier three: paid change request—new section from Figma, template restructure, app migration. Without tiers, every "can you move the logo left" email erodes margin. Link clients to Liquid for Beginners only for technical stakeholders, not store operators.

Regression testing before every section deploy

Even small section updates can break cart icons or header overlap. Our regression mini-suite on each deploy: homepage hero loads, product add-to-cart works, collection pagination loads, mobile menu opens, footer newsletter submits. Takes ten minutes, prevents emergency rollbacks. Automate what you can with theme-check and Playwright on staging duplicates for larger clients. Store screenshots of known-good editor state so you can tell merchant edits from deploy regressions when triaging tickets.

Post-handoff: 30-day check-in

Schedule a 30-day review. Pull theme editor history if Plus, or ask what they changed. Fix confusion patterns in schema—if three clients miss the same setting, add a paragraph info setting in schema explaining it. Aggregate support tickets; recurring themes mean bad labels or missing presets, not stupid users.

Turning support tickets into schema improvements

Ticket themes reveal handoff gaps. "I cannot find the button text" means label or grouping failure. "The mobile layout broke" means missing responsive QA documentation. "Which section is the homepage slider?" means template map was not read. Batch quarterly schema tweaks across clients—add info settings, rename labels, split crowded headers—and handoff quality compounds. Merchants rarely ask for developer empathy; they ask for obvious editor UX. Deliver obvious.

FAQ

When should handoff happen?

After QA on a duplicate theme, before publish. Train on duplicate; publish when checklist is green and client homework is done.

How many presets per section?

Minimum one well-named preset. Two if layout variants help discovery—image left/right, compact/expanded.

Next steps

Pair this checklist with our section workflow, reusable sections guide, and Liquid cheat sheet. Build sections faster with the converter; hand them off slower and deliberately— that is what keeps retainers friendly instead of resentful.

The best handoffs feel boring: merchants edit copy confidently, tickets stay rare, and your team moves to the next build. That boredom is earned by checklists like this one, not by assuming smart clients will figure out the theme editor alone.