120+ Shopify Sections Later: What We Learned Building Stores

Section eighty-one was not interesting. Section eighty-one was the fiftieth time block.shopify_attributes was missing on one FAQ row, breaking theme editor selection. Field notes from 120+ custom sections across supplements, furniture, B2B wholesale, and DTC — architecture, merchant behavior, and mistakes that still appear on rescue projects.

The patterns below span architecture, merchant behavior, performance traps, and rescue-project déjà vu — field notes from years of client development, cross-linked to section workflow and scoped CSS rules when you need implementation depth.

Section architecture that survives merchant editing

A section file is three contracts at once: Liquid that renders, schema that defines editable fields, and CSS that must not poison the parent theme. Architecture starts with filename and type stability — sections/hero-split.liquid becomes type hero-split in every JSON template reference. Rename after launch and you migrate merchant JSON or wipe settings. We keep a module inventory on every project mapping Figma frame names to filenames before code exists. Inside the file, we separate layout shell (section wrapper, grid containers) from content loops (blocks) from shared logic (snippets). Icons, star ratings, and product card markup render via snippets — not duplicated across five section files with slightly different class names.

A furniture client homepage mapped thirty-one modules in that spreadsheet — each row noted block versus flat and which index.json key would host the section. That discipline prevents the classic bug where the file exists in sections/ but never appears in order, so merchants swear the homepage module vanished after migration.

Flat versus block — the decision we make at intake, not at QA

The flat-versus-block decision is the highest-leverage architecture choice on any module. Get it wrong and merchants either drown in twenty flat settings for a logo strip, or they cannot add a FAQ row without a developer. Our rule is boring and effective: repeatable rows equal blocks. We document the framework in Dynamic Shopify Blocks Guide and enforce it at Figma intake — if design shows six identical testimonial cards, the spreadsheet says blocks before HTML exists. Flat heroes with eyebrow, heading, copy, CTA, and background media stay flat — seven settings, one preset, done. Comparison tables with static rows that never change stay flat with headers grouping columns. Everything else earns blocks.

Merchant requirements we underestimated early

Merchants do not read schema ids. They read labels, see defaults, and infer whether a section is broken when fields look empty. Early builds used developer labels — field_3, Subheading 2, Btn URL — and generated support noise unrelated to actual bugs. Now every section passes merchant-friendly schema patterns review: plain language labels, header settings grouping Advanced layout, realistic defaults seeded from approved Figma copy, image pickers with placeholders that do not render broken icons. Merchants also reorder blocks more than we expected — especially FAQ, testimonial, and press logo sections after PR cycles. Missing block.shopify_attributes means clicks in the theme editor highlight the wrong row or nothing at all. That is not a cosmetic issue; it is an architecture bug.

• Labels in merchant vocabulary — Main headline not Heading line 1.
• Defaults that match approved design — empty sections look broken in client demos.
• Header settings to hide advanced toggles — Layout, Colors, Visibility groupings.
• Presets with at least two block rows for repeatables — merchants must see the pattern.
• Collection and product pickers instead of hardcoded handles — merchandising renames break handles.

Common mistakes we still fix on client stores

Rescue work keeps us humble. After 120+ sections we still open themes where another team shipped fast and skipped fundamentals. Global CSS leaks from custom sections. Product templates reference section keys that do not match filenames. FAQ modules hardcode twelve questions. JSON templates list sections in an order marketing never approved. Liquid uses deprecated include instead of render. These are not junior-only mistakes — they are deadline mistakes, and deadlines are universal. We maintain a living audit list aligned with Liquid mistakes we still see on client stores because Liquid errors and section schema errors compound on product and collection templates where nobody looked during homepage UAT.

The Prestige fork with circular product thumbnails

Last year a client hired us after launch week. Homepage testimonials looked great — circular avatars, star SVGs, smooth carousel. Collection pages showed round product images because the testimonial section CSS used img { border-radius: 50% } without scoping under section.id. Theme Check passed. Merchants were furious. Fix took twenty minutes; trust took longer. Now scoped CSS under #shopify-section-{{ section.id }} or {% stylesheet %} with explicit prefixes is a merge blocker — not a nice-to-have. We teach the pattern in every internal review and write it into rescue SOWs when we inherit unscoped legacy sections.

Performance lessons from section-heavy homepages

Sections are not free. Each section adds Liquid execution, DOM nodes, CSS bytes, and often JavaScript if developers attach behaviors per module. A homepage with twenty-eight sections sounds impressive in a sales deck and terrifying in PageSpeed. We budget section weight per template: heroes and first-fold content get priority; below-fold video backgrounds lazy-load; carousels share one intersection observer snippet instead of five copy-pasted scripts. Product.json is tighter — six to ten sections typical, with main-product carrying most block weight. When marketing asks for twelve modules on PDP, we show mobile filmstrips where the buy box disappears. Performance is a merchant requirement even when they do not name it.

{%- comment -%} Lazy video pattern we reuse in media-heavy sections {%- endcomment -%}

Client experiences that changed how we quote section work

Case studies in client case studies are sanitized, but the shapes repeat. Supplement brands need ingredient grids, subscription callouts, and compliance FAQ sections updated seasonally — block architecture is mandatory. Furniture clients need room-set heroes, dimension accordions, and delivery FAQ modules with richtext legal copy. B2B wholesale portals need application forms, MOQ tables, and collection-gated messaging — flat settings for global toggles, blocks for FAQ and feature rows. Luxury apparel wants editorial lookbooks with minimal theme editor clutter — fewer settings, deliberate locked copy in snippets. Quotes improved when we categorized modules by archetype instead of treating every Figma frame as a unique snowflake.

Black Friday launches and the FAQ surge

Every Q4, merchants add FAQ rows — shipping cutoffs, gift card rules, return extensions. Sections without blocks become emergency developer tickets on Thanksgiving week. We now refuse flat FAQ modules on retainer clients. Presets seed two items; blocks use richtext answers; theme editor training shows Add block before November. Sounds procedural; saves marriages. Wholesale clients add FAQ rows for credit applications and tax exemption steps — same architecture, different copy. The lesson is not about FAQ trivia; it is that merchant timelines follow retail calendars, not sprint planning, and section architecture must anticipate edits you will not be online to make.

Dawn forks and third-party themes — section portability

Most sections we ship target Dawn-derived CSS variables or Prestige spacing rhythms — not abstract perfection. Porting a section between themes is rarely copy-paste: color_scheme integration, typography tokens, and cart drawer z-index conflicts differ. We document parent theme assumptions in section README notes — Uses Dawn color_scheme tokens; do not port to Narrative without refactor. JSON template keys are theme-specific even when section files copy cleanly. Our development experience pages list theme families we quote confidently versus themes where we charge discovery for unknown CSS coupling.

JSON templates — order is part of the architecture

Sections do not appear on the storefront because the file exists. templates/index.json order arrays are the homepage narrative marketing approved in Figma. Developers who reorder to test without syncing design create launch arguments. We map order keys to Figma frame numbers in internal docs. When merchants reorder in the theme editor after handoff, that is fine — it is their store. When developers shuffle during build without sign-off, it is a process failure. Section architecture includes where the module lives in JSON, not only what is inside the Liquid file.

Theme editor QA — scripts that scale past section thirty

QA scripts matter more as section count grows. Per section: highlight in editor, reorder blocks, toggle checkboxes, upload image, clear text field, add block, delete block, duplicate section instance. Per template: test collection and product pages for CSS bleed. Per deploy: Theme Check CLI, preview on duplicate theme, mobile width first. We log failures in GitHub issues tagged theme-editor before client UAT. Merchants paste Word HTML into richtext fields; teenagers test on phones with cracked screens. Your QA should assume chaos. Section one hundred twenty-one fails the same way section four does if presets are missing — the difference is you are tired when you catch it.

Section presets and the Add section panel — invisible work

Presets are not a nice-to-have checkbox in schema JSON. They are how merchants discover custom work after launch when marketing wants a second testimonial band on a landing page. We have lost count of rescue tickets where the section file existed, rendered fine when hardcoded on index.json, but never appeared in Add section because presets was an empty array. After section sixty we made presets a merge blocker — same severity as missing block.shopify_attributes on FAQ rows. Preset names use merchant language: Homepage FAQ not Custom section 4. Seed two blocks on repeatables so the pattern is obvious. When a wholesale client asks for a duplicate press grid on a B2B landing page, they should not need a developer to edit JSON templates.

App blocks versus theme sections on product templates

Section one hundred taught us product.json is a negotiation between theme sections and app blocks — reviews, subscriptions, back-in-stock, UGC widgets. Merchants experience both as draggable rows, but developers own only theme sections. We document which product page real estate is app-owned so we do not build custom review carousels that fight Yotpo or Judge.me blocks. Theme sections handle editorial bands, comparison tables, and brand FAQ modules; apps handle dynamic inventory of third-party data. Misassignment wastes build budget and creates z-index wars on mobile PDP filmstrips.

Figma handoffs that reduce section rework

Design exports determine how painful section forty-two becomes. We ask designers to name Figma frames with final section filenames when possible — hero-split not Frame 218. Mobile frames must exist before development starts; retrofitting responsive CSS after flat desktop export costs more than the section quote. Repeatable rows should share component structures so block inference or manual conversion recognizes patterns. When a furniture client exported twelve slightly different testimonial cards, we forced a component refactor in Figma before Liquid — the alternative was twelve block types or one block type with ugly edge-case settings. Section architecture starts in design ops, not only in VS Code.

What we would tell an agency shipping their fiftieth section

Standardize before you optimize. One block loop skeleton for FAQs. One hero scaffolding pattern. One snippet library for cards and stars. Run merchant-friendly schema review on every merge, not only client-facing launches. Read common Liquid mistakes before code review. Scope CSS like your collection pages depend on it — they do. Document handoffs like you will be on vacation when the merchant edits — you will be. The fiftieth section feels routine; that is when you skip presets and ship a invisible module. Stay boring.

After 120 sections, the hard part is not writing Liquid. It is predicting how merchants and retail calendars will stress your architecture six months after launch.

Patterns we reuse on every new client

• Module inventory spreadsheet before filenames exist.
• Block loops for FAQ, logos, testimonials, icon grids, press mentions.
• Scoped CSS merge blocker — no bare img or h2 selectors at root.
• Presets always — section must appear in Add section on JSON templates.
• Fifteen-minute Loom handoff per complex module — PDFs do not get watched.
• Duplicate theme only — never section development on published live theme.

Closing field notes

One hundred twenty-plus sections did not make us poets. They made us consistent. The merchants who trust us do not care about our block loop elegance; they care that FAQ row thirteen publishes before Black Friday without a support ticket. Architecture serves that outcome. If you are mid-build on a section-heavy theme, audit one module against this list before starting the next. If you inherit a rescue project, read case studies and blocks guide before quoting fix time. The sections blend together; the mistakes repeat; the merchants deserve presets that work. That is what 120 modules taught us.

Retainer clients and the section backlog that never ends

Retainer relationships reveal section architecture stress over quarters, not sprints. A supplement client adds seasonal ingredient callouts; a wholesale portal adds tax FAQ rows after regulatory updates; a luxury brand requests editorial bands for each capsule drop. Retainers work when sections are block-first, presets are seeded, and handoff Looms stay findable in Notion. We review schema patterns on retainer tickets the same way we review new builds — because a rushed FAQ edit on month nine erodes the same trust as a launch-week bug. Section one hundred twenty-two is still a section; it still needs scoped CSS and non-empty presets. The architecture decisions you make on section ten compound on section one hundred ten when nobody remembers why the logo marquee is flat instead of blocks.