Range inputs with step 2 and sensible min/max stopped merchant emails about broken spacing on my Shopify theme.
Conditional blocks plus block-level max settings keep the Shopify OS2 customizer clean when a section grows past six options.
Metaobject picker types and color_scheme with four presets ended the hex code copy-paste dance merchants used to hate.
Presets bundled with real default values let merchants one-click a finished section instead of staring at an empty shell.
Shopify section schema is where theme developers usually lose merchants. A good section schema turns the Shopify OS2 customizer into a room someone wants to spend time in. A bad one sends the merchant back to email asking why the hero looks broken again. I run the raxxo.shop theme myself on Shopify, and these four patterns are the ones I keep coming back to.
Range inputs beat text boxes every time
Merchants stopped emailing me about broken spacing the week I switched every numeric setting from text to range. Text inputs are an invitation to type 32px into a field that expects a raw number, or paste 1.5rem into something that becomes NaN downstream. Range inputs with a sensible step, min, and max make it physically impossible to break the layout.
I set step to match the nearest value on my spacing scale. For padding I use step 4 with min 0 and max 64. For font size I use step 2 with min 12 and max 48. The customizer shows a slider and a number, the merchant drags, the section updates live, nobody types a string where a number should be.
{
"type": "range",
"id": "section_padding_top",
"min": 0,
"max": 64,
"step": 4,
"unit": "px",
"label": "Top padding",
"default": 32
}
The unit property is the small detail that sells it. Merchants see "32 px" next to the slider, not a naked number they have to interpret. For line-height I use step 0.1 with min 1 and max 2, and for border-radius step 2 with min 0 and max 20, which matches my token scale exactly.
The trap I fell into early: wide ranges. Don't let padding go from 0 to 200. The merchant will find 180 and ship it. Clamp the range to values that can't break the design, then let them play freely inside that box. Think of the range as a guardrail, not a toy.
One more habit. I never use range for anything that should be a fixed choice. Aspect ratio is a select with four options. Columns is a select with 1, 2, 3, 4. Numeric doesn't mean range, it means "what are the valid numbers here", and if the answer is "three of them", select wins.
Conditional blocks and block-level max settings
The moment a section grows past six options, the schema needs structure. Blocks are the answer, but raw blocks with no constraints turn into a mess. Two settings fix that: max_blocks at the section level, and the visible_if property on individual settings inside a block.
max_blocks is the one setting that saves merchants from themselves. A testimonial carousel with no max will eventually hold 47 testimonials, all of which will load on mobile, all of which will make the slider janky. I cap testimonials at 8, feature columns at 6, hero slides at 4. If the merchant wants more, they can ask why.
visible_if is the 2025 addition that changed how I write schemas. Instead of showing 12 fields and hoping the merchant ignores the ones that don't apply, I hide them until they become relevant.
{
"type": "select",
"id": "media_type",
"label": "Media type",
"options": [
{ "value": "image", "label": "Image" },
{ "value": "video", "label": "Video" }
],
"default": "image"
},
{
"type": "video",
"id": "video",
"label": "Video file",
"visible_if": "{{ block.settings.media_type == 'video' }}"
}
The video picker only appears when the merchant picks video. The image picker only appears when they pick image. The panel is half the length it used to be, and the merchant never sees a setting that doesn't apply to what they're building.
I also use info text above groups of related settings. It's a one-line description that sits above the first field, no heading required, no extra clicks. For a layout group I might write "Controls how the section sits on the page." Short, specific, merchant language. Not "Configure the layout container parameters."
Metaobject pickers and color_scheme type
Two schema types did more for merchant happiness than any other change I made in 2025 and 2026: metaobject and color_scheme. Both existed in some form before, but the tooling finally caught up.
Metaobject pickers let me reference structured content the merchant defined in Shopify admin. For raxxo.shop I have a "team member" metaobject with fields for name, role, photo, and bio. Before metaobject pickers, a team grid section meant 24 separate settings per block. Now it's one picker.
{
"type": "metaobject",
"id": "team_member",
"metaobject_type": "team_member",
"label": "Team member"
}
The merchant picks a team member from a dropdown. The section pulls name, photo, role, and bio automatically. Editing the metaobject once updates every section that references it. The schema goes from 24 fields to 1, and the section stays in sync across the whole theme.
color_scheme is the other one. Before, every section had a "Background color" picker, a "Text color" picker, and a "Button color" picker, and merchants picked random hex values that didn't match anything else on the site. Now I define 4 schemes at the theme level (background, accent, inverse, feature), and every section takes a single color_scheme setting.
{
"type": "color_scheme",
"id": "color_scheme",
"label": "Color scheme",
"default": "background-1"
}
The merchant picks "Accent" from a dropdown. The section inherits background, text, border, and button colors that were defined centrally. If I change the accent scheme once, every section using it updates. No hex copy-paste, no accidental contrast failures, no mismatched buttons on different pages.
Defaults and presets that actually look good
A section with no defaults is a section the merchant never uses. They drop it onto the page, see an empty shell, and drop it right back off. The fix is defaults that produce a finished result the moment the section is added, plus named presets for the common variants.
Every field that can have a default, should. Image fields point to a placeholder that matches the brand. Heading defaults say "Your headline here, keep it short" not "Heading text". Button labels say "Shop now" not "Button". Padding defaults match whatever padding looks good on desktop right out of the gate.
Then I add presets. A preset is a pre-configured block of settings that appears as a named option when the merchant adds the section. For a hero I might ship three presets: "Image left, text right", "Full-bleed video", "Centered text only". Same section, three one-click starting points.
{
"presets": [
{
"name": "Image left, text right",
"settings": {
"layout": "split",
"image_position": "left",
"heading": "Built for people who ship",
"button_label": "See how"
}
},
{
"name": "Full-bleed video",
"settings": {
"layout": "fullwidth",
"media_type": "video"
}
}
]
}
Presets are the single highest-impact thing I've added to my schemas. Merchants stop asking "how do I make it look like the homepage", because the preset is literally called "Homepage layout". They click it, it looks right, they tweak two fields, they ship.
One rule I follow: if a preset needs more than five custom settings to look good, the section is probably doing too much. Split it into two sections. A section that tries to be a hero, a banner, a feature row, and a testimonial all at once will have a schema nobody can navigate, and presets won't save it.
Bottom Line
Schema is UX. Every setting you add is a decision the merchant has to make, and every decision you remove by using a smart type, a good default, or a preset, is one less reason they email you. Range over text. Conditional visibility over giant panels. Metaobject pickers over duplicate fields. Color schemes over hex pickers. Presets over empty shells.
I keep sections at around 12 settings total, and if I cross that line I either split the section or hide half the fields behind visible_if. The merchants who run stores on my themes don't think about schema, which is the point. They pick a preset, tweak the heading, pick a color scheme, and the section ships looking like it belongs to the rest of the site.
If you want the whole starter kit I use on Shopify themes, the Claude Blueprint covers the workflow end to end. Schema is the part merchants touch every day. Treat it like product.
Top comments (0)