Shopify theme settings and settings_schema.json

Theme settings are the controls a merchant sees under Theme settings in the editor — typography, colours, layout defaults, social links, cart behaviour. They're defined in config/settings_schema.json and their values are stored in config/settings_data.json.

Most themes get the JSON right and the design wrong, because the JSON is documented and the design isn't.

The schema

settings_schema.json is an array. The first entry is metadata about the theme; every entry after that is a group of settings that appears as a panel.

``json [ { "name": "theme_info", "theme_name": "Example", "theme_version": "1.0.0", "theme_author": "Studio", "theme_documentation_url": "https://example.com/docs" }, { "name": "Typography", "settings": [ { "type": "header", "content": "Headings" }, { "type": "font_picker", "id": "heading_font", "label": "Heading font", "default": "assistant_n4" }, { "type": "range", "id": "heading_scale", "label": "Heading size", "min": 90, "max": 130, "step": 5, "unit": "%", "default": 100 }, { "type": "paragraph", "content": "Applies to all headings across the store." } ] } ] ``

Access values in Liquid as {{ settings.heading_font }}.

Input types worth knowing

Colour schemes instead of colour pickers

The old pattern was a dozen individual colour settings — background, text, button, button text, border — repeated for each area of the site. Merchants would change one and break the contrast of another.

Colour schemes group related colours into a named set, and sections then choose a scheme rather than individual colours. A merchant picks "Scheme 2" for a section and everything inside it is coherent — including contrast, which is much harder to guarantee with loose pickers. It's fewer decisions for them and far fewer accessibility disasters for you.

If you're building a new theme, use schemes. If you're maintaining an old one, migrating to them is one of the highest-value refactors available.

settings_data.json is not yours

It holds the merchant's chosen values. Pushing your local copy over it resets their theme to your defaults — the same hazard as JSON templates, and the same fix: exclude it from pushes, or pull before you push.

Designing settings people can use

The technical part is easy. These are the decisions that matter:

• Expose what varies, hide what doesn't. Every setting is a decision you're delegating, and delegating a decision the merchant doesn't want costs them time.
• Bound everything. range, not a number field. select, not free text. Unbounded settings produce broken layouts and then a support email.
• Name things in their language. "Space above sections", not "Section vertical rhythm multiplier".
• Group in the order someone works. Typography, colour, layout, then the odds and ends.
• Use paragraph to explain non-obvious settings rather than assuming the label carries it.
• Set defaults that look right. A fresh install of the theme should be presentable before anyone touches a setting.

The test: hand the theme to someone who has never seen it and ask them to change the button colour and the heading font. Watch where they hesitate. That's your redesign list.

Global setting or section setting?

Global if it applies across the store — brand fonts, colour schemes, cart behaviour. Section setting if it applies to one instance — this section's heading, this section's image.

The failure mode is putting section-level content in global settings, which produces a Theme settings panel with forty entries and sections that can't be reused. Sections and blocks is where most configuration should live.

Theme settings are a small API with one user who has never read documentation and is in a hurry. Design for that person.