Flat vs Block Sections: Our Developer Decision Framework

Choosing flat settings when merchants need reorderable rows costs more to fix mid-sprint than an hour of schema debate upfront. This framework is the five-question inventory Dhruv and Nishad run before conversion — mark F or B in writing, reference it in the PR, and avoid retrofitting block loops under deadline pressure. Implementation detail lives in Dynamic Shopify Blocks Guide.

The flat-vs-block decision is the highest-leverage schema choice on a Shopify section. Get it wrong and merchants either cannot add rows without agency help, or they drown in empty block UI on a simple hero. We still inherit rescue themes with faq_question_7 text settings and no presets. This framework is what we teach in week one and enforce in PR review — decision first, markup second, converter mode third. It extends Flat vs Block Sections with client-project edge cases and accountability checks, not theory alone.

Definitions: flat settings, blocks, and hybrids

Flat settings live in section.settings — one value per field for the whole section instance. Blocks live in section.blocks — zero to max_blocks rows merchants add, remove, reorder. Hybrids combine section-level layout controls with block loops for content rows — the default for FAQs, feature grids, sliders. Pure flat means no blocks array in schema. Pure block-only sections are rare — usually a gallery with only images and no section heading. Know which pattern you are shipping before Figma sign-off so PMs do not promise reordering on a flat build.

Decision question 1: Will merchants add or remove rows?

If yes — blocks. No exceptions for "but Figma only shows three rows." Merchants interpret three as minimum, not maximum. FAQs, logos, testimonials, timeline milestones, comparison columns, collection tabs — all blocks. If no — flat. Single hero, one background video, one CTA pair. When PM says "they will never add more," ask if they said that about homepage banners last quarter. Presets seed block count but do not replace block architecture.

Decision question 2: Does row order matter to merchandising?

Reorderable content requires blocks with block.shopify_attributes on wrappers. Flat settings cannot reorder — you would need separate setting groups faq_1, faq_2 with no drag handle. Marketing teams live in drag-and-drop; denying reorder guarantees Slack messages. For fixed legal disclaimers where order is legally sequenced, flat might be intentional — document immutability in handoff.

Decision question 3: Do row types differ?

Multiple block types in one section — testimonial_video vs testimonial_quote — need distinct block types in schema with limits per type if required. Flat settings cannot express heterogeneous rows without boolean spaghetti show_video_3. Use blocks when row shapes diverge. Dynamic Blocks Guide shows multi-type loops.

"blocks": [
  { "type": "quote", "name": "Quote", "settings": [...] },
  { "type": "video", "name": "Video", "settings": [...] }
]

Decision question 4: Is content product-specific via metafields?

If product metafields drive repeating data — ingredients, specs — blocks may be wrong layer; metafield loops in Liquid suffice on PDP. If merchants author rows in theme editor without touching admin product sidebar, blocks. If data must sync across product cards and PDP, metafields plus snippet — see Metafields Liquid Patterns. Do not duplicate metafield-driven lists into blocks merchants must manually sync.

Decision question 5: What is the setting count ceiling?

More than twelve top-level flat settings without headers confuses merchants. More than eight similar text fields strongly signals missing blocks. We group flat settings with header settings — Content, Layout, Advanced — per Section Schema Explained. Block sections cap visible section settings to layout and heading; row content lives in blocks.

The matrix we whiteboard with PMs

• Flat — hero, announcement bar, single image banner, newsletter, simple rich-text band
• Blocks — FAQ, logos, features, sliders, tabs, team grid, press quotes
• Hybrid — heading + background flat; rows as blocks
• Metafield loop — product-specific repeating specs on PDP
• Metaobject — structured rows shared across templates and admin

Edge case: exactly two items — still blocks?

Yes if merchants might add third. No only when design contract fixes pair — two-column USP with exactly two icons and legal copy forbids changes. Even then we often use blocks with max_blocks: 2 for flexibility. Cheap insurance. Split hero with left/right columns as two fixed settings is flat hybrid — not block — when columns are not repeatable rows.

Edge case: tabs and nested navigation

Each tab is a block; tab panel content inside block settings or nested blocks if Shopify schema allows one level of block types only — usually one block type tab with title + richtext. Avoid simulating tabs with six flat visibility checkboxes show_tab_3.

Edge case: sliders vs CSS scroll snap

Horizontal logo strip with six logos — blocks. Static marquee CSS with infinite scroll duplicating same four brand assets — still blocks if logos change seasonally. Pure CSS decorative motion without merchant-editable cells — flat image picker array is wrong; use blocks.

Converter and export mode alignment

Run converter Block mode when HTML repeats structurally — identical class patterns, sibling nodes. Flat mode for hero exports. If converter suggests blocks and PM signed flat-only scope, escalate — scope is wrong, not tool. Post-export, delete spurious blocks inferred from navigation chrome mistaken as repeatables. Human review stays mandatory.

{% for block in section.blocks %}
  {% case block.type %}
    {% when 'feature' %}
      

        {{ block.settings.title }}
      
  {% endcase %}
{% endfor %}

Schema consequences of wrong choice

Flat wrong → agency tickets for "add another row." Blocks wrong → merchants confused by empty block list on simple banner. Migration cost flat to blocks post-launch: new schema, lost setting id mapping, content re-entry. Decide at intake. Section Workflow phase one inventory marks F vs B per module.

max_blocks, presets, and limits

Set max_blocks realistically — 12 FAQ, 24 logos. presets seed two blocks minimum. limits on block types when design allows max one video block. Merchants hitting max_blocks is rarer than hitting confusion — document limits in paragraph settings.

Performance: blocks are not free but cheaper than hacks

Fifty blocks in one section slows editor drag; cap sensibly. Still better than fifty flat settings keys bloating JSON. Liquid for loop cost is trivial versus broken UX. Performance Tips for collection loops — different problem.

PR review: flat-vs-block checklist

1. Module inventory marked B actually uses {% for block in section.blocks %}
2. block.shopify_attributes present on row wrapper
3. No faq_text_9-style setting ids
4. Flat heroes have no empty blocks array confusing editor
5. Presets match architecture — blocks seeded for B modules
6. Handoff doc states reorderable vs fixed

Stakeholder worksheet: five questions on every module row

We add columns to module inventory: Add rows? Reorder? Row types differ? Metafield-driven? Setting count? Answers must be yes/no, not "maybe later." PM signs inventory before dev sprint. Prevents "we assumed flat" disputes in UAT. Worksheet lives in same doc as Figma links — single source of truth.

Block limits when marketing wants unlimited logos

max_blocks: 24 satisfies most logo walls; "unlimited" hurts editor performance. Offer metafield-driven logo list on PDP for data-heavy cases; blocks for marketing-curated homepage subset. Explain tradeoff in kickoff — unlimited is not free in UX or render cost.

Repeating settings smell test in code review

Grep schema for _1, _2, _3 suffixes on setting ids — automatic fail. Grep for question_4, slide_5, column_6. Refactor to blocks before merge. Senior developers catch this; linters do not. Include smell test in PR template checkbox list.

Flat sections that look like blocks in Figma

Designers draw three columns as three frames — developers must interpret intent. Ask: are columns reorderable content or fixed layout grid? Fixed three-column USP with one icon each can be flat settings icon_1, icon_2, icon_3 only when order never changes. When in doubt, blocks. Schema Generator block mode prototypes decision before full build.

Dynamic blocks and app block slots

Product sections mixing native blocks and @app blocks are hybrid architecture — not flat. Merchants reorder native blocks; apps inject own block types. Do not flatten app-dependent layout into settings apps cannot hook into. App Blocks Guide for slot planning.

Post-launch migration: flat to blocks playbook

When rescue required: ship new block-based section type, migrate content manually in theme editor or script JSON transform mapping old setting ids to block settings, deprecate old section, remove from templates after content move. Budget half day per complex section. Prevention beats migration — run framework at intake.

Internationalization and block content

Markets with translated content may duplicate section instances per locale or use Translate & Adapt on block settings. Flat settings with twelve fields multiply translation burden versus blocks merchants add per locale. Architecture choice affects localization cost — flag to client before committing flat FAQ with eight hardcoded questions.

Case study: FAQ flat rescue to blocks

Supplement client had faq_question_1 through faq_question_12 flat settings — marketing could not reorder for compliance review order. We shipped faq-accordion-v2 with blocks, migrated twelve questions in forty-five minutes in editor, swapped section type in page.json, removed legacy section from schema registry. Client self-served four new questions within week one. Flat architecture would have cost agency hour per new row forever.

Case study: hero correctly flat

Luxury watch client hero — single cinematic video, one headline, one CTA, no reordering ever. Flat settings with eight fields, strong presets, color_scheme integration. Blocks would have confused merchants with empty Add block. Framework said flat; launch tickets zero. Counterexample proves framework is not "always blocks."

Converter false positives on navigation menus

HTML nav with repeated li elements triggers block inference incorrectly. Human review removes spurious blocks before merge. Mark nav exports as flat in inventory before paste into converter. Automated detection accelerates work; framework decision prevents wrong automation acceptance.

Block type naming for merchant clarity

Block type ids are developer-facing but name field is merchant-facing — "Press mention" not "logo_block_type_b." Consistent naming across sections reduces training — same block name "Feature" in multiple sections if structure matches. Avoid reusing same type id for different schemas in different section files — confusing in JSON debugging.

Framework summary card for desk

1. Merchants add/remove rows → blocks
2. Merchants reorder rows → blocks
3. Row shapes differ → multi-type blocks
4. Data syncs from product admin → metafields
5. Singleton promo → flat settings
6. Twelve similar text fields → you missed blocks

Teaching clients the vocabulary

Merchants do not say blocks — they say rows, slides, questions. Handoff uses merchant words mapped to editor UI: "Click Add block to add a FAQ row." Reduces training friction. Loom shows one flat section and one block section side by side.

When we deliberately ship flat despite repeat-looking Figma

Rare: legal module with exactly four required disclosures order fixed by compliance — flat with header settings per disclosure and no reorder. Document signed by client stakeholder. Do not guess compliance — ask. Another case: section is pure decoration with no merchant edit plan — still questionable; presets with defaults often enough.

Inventory spreadsheet template

Columns: Figma frame name, section filename, F/B decision, reorderable Y/N, max blocks, templates enabled, preset name, owner developer. PM fills first four columns before sprint; dev fills rest at merge. Spreadsheet exports to PDF in client handoff appendix. Single row per module prevents duplicate section files with different architecture choices.

When PM overrides framework toward flat for budget

Budget cuts sometimes push flat FAQ to save block loop hours — we document risk in writing: "Merchant cannot add rows without agency." Client signature on that line prevents post-launch blame. Offer phased approach: flat for MVP launch, blocks in phase two before holiday season. Honest tradeoffs beat silent debt.

Junior developer mentoring on flat vs block

Week one exercise: given three HTML exports, mark F or B with justification before opening converter. Review as team. Wrong answers are learning — hero marked blocks, FAQ marked flat. Repeat until inventory matches senior consensus without debate. Framework becomes culture when juniors challenge PM scope with five questions politely.

If the merchant might add a fourth row next month, it is a block today — not a flat field faq_four.

Sprint planning: estimate block sections higher

Block sections cost more than flat in estimates — loop markup, shopify_attributes, presets with seeded rows, max_blocks tuning. Flat hero quotes 1.5 hours; block FAQ quotes 2.5 hours in our tracker. Accurate estimates require framework classification at scoping call, not at sprint planning when numbers are already promised to client.

Auditing rescue themes for flat-vs-block debt

Grep schema for setting id patterns question_, slide_, column_, item_. Score debt by count. Present remediation roadmap to client with ticket history if available — "twelve section edits last quarter were add row requests." Data sells block migration better than architecture sermon alone.

Framework poster for team wiki

Print five questions as internal wiki poster linked from Slack onboarding. Link to Flat vs Block Sections for merchant-facing summary and this article for developer enforcement. Framework only works if PM and dev read same doc — not parallel verbal rules that diverge by sprint.

Annual framework review with client success team

Support tags mentioning cannot add row or section looks empty feed back into framework training. If tags cluster on one section type, architecture was wrong — flat when blocks needed. Quarterly review with account managers turns tickets into framework improvements and preset fixes, not blame on merchants. Living framework beats static wiki page from 2023.

Closing the loop with converter Block mode defaults

When framework says blocks, run converter Block mode before writing schema by hand — saves twenty minutes and prevents forgotten shopify_attributes. Framework decision drives tooling mode, not reverse. Seniors review converter block inference against five questions; juniors do not accept Block output on hero because converter guessed wrong.

Framework sign-off in sprint kickoff

First five minutes of section sprint: PM reads inventory F/B column aloud; dev lead confirms or challenges one row. Disagreements resolved before code, not in PR comments. Sign-off screenshot in Slack thread becomes reference when scope creep adds "just one more FAQ field" without blocks.

Pin the framework summary card in your team Slack channel during onboarding week — passive exposure beats one-time wiki link. When a rescue project starts, run the inventory worksheet before writing any schema — retrofitting flat to blocks mid-sprint doubles estimate. Add the framework summary card to your internal Notion or wiki homepage — not buried in a drive folder nobody opens. Visibility beats documentation nobody reads. Run the five decision questions on every module in the inventory before conversion. Mark F or B in writing; reference this framework in PR template. Wrong architecture costs more than an hour of schema debate upfront. How to Build Dynamic Blocks is implementation; this framework is the gate.