Theme editor settings on Shopify: design tokens merchants can edit

A merchant wants to experiment with design elements in the theme editor - button colors, font choices, border thickness, opacity. They're not comfortable editing Liquid code; they want to click, preview, save. The question for the developer: how do you expose the right knobs to the theme editor without giving merchants a way to break the theme?

The theme-editor control surface

Shopify themes have a specific file that controls which settings merchants see in the theme editor: config/settings_schema.json.

This schema defines:

• Theme settings - global controls (site typography, brand colors, button defaults)
• Section settings - per-section controls (image, heading, call-to-action per hero section)
• Block settings - nested controls within sections (individual feature blocks)

A well-designed settings schema gives merchants meaningful control without overwhelming them with technical knobs.

The file structure

config/settings_schema.json defines what the merchant sees:

config/settings_data.json holds the merchant's saved values. This file isn't edited by developers directly - it's updated every time the merchant saves settings in the theme editor.

Liquid templates consume the settings via settings.color_button_primary, settings.font_heading, etc.

The correct answer for "where to expose design tokens"

The file that controls merchant-editable design is config/settings_schema.json. Adding a new setting there makes it appear in the theme editor's global settings. Merchants click, preview, save; the change propagates across every section that references the setting.

This is distinct from:

• config/settings_data.json - the saved values, not the schema
• sections/*.liquid - per-section settings defined in schema tags at the bottom of each section file
• assets/*.css - compiled CSS, not editable through the editor
• templates/*.json - page template structure, edited through the theme editor's customization mode

Setting types that fit design tokens

Shopify's settings schema supports many types. For design tokens, the useful ones:

• color - hex color picker
• color_background - background with optional transparency
• color_scheme - references a color scheme defined elsewhere
• font_picker - select from Shopify's font library (Google Fonts + system fonts)
• range - numeric slider (for border thickness, opacity percentage, image border radius)
• select - dropdown (for size options like "small/medium/large")
• checkbox - boolean toggle
• text - short text input (for custom CSS class names, if you really must)

For the scenario at the top - button colors, fonts, border thickness, opacity - the right setting types are color, font_picker, and range respectively.

Consuming settings in Liquid and CSS

In Liquid, settings are accessed via the global settings variable:

For bulk CSS styling, many themes compile settings into CSS custom properties in the layout:

Then component CSS uses the custom properties:

This separation means design-system changes in the theme editor propagate everywhere in one place.

Color schemes for complex theming

Modern Shopify themes support color schemes - named combinations of background, text, button, and accent colors that apply to sections. A merchant can define "Light scheme" and "Dark scheme" and apply either to any section.

Color schemes live in the schema too but have their own structure:

This is the pattern Dawn and modern OS 2.0 themes use. Merchants pick a scheme per section; the theme renders with the scheme's colors consistently.

Font pickers and the font_url filter

For fonts, the font_picker setting type returns a font object with a family name and loading URL. Themes use the font_url filter to load the right stylesheet:

This emits the proper @font-face declaration for the chosen font. Merchants can pick any of Shopify's library fonts (Google Fonts + system) and the theme adapts automatically.

Settings organization for non-technical merchants

A well-organized settings schema:

• Groups related settings under headers ("Colors", "Typography", "Buttons")
• Uses clear labels ("Primary button color" not "color_button_primary")
• Includes help text explaining the effect
• Orders settings from most-impactful to least
• Provides sensible defaults

A schema with 100 ungrouped settings is unusable even by technical merchants. A schema with 15 well-organized settings lets non-technical merchants confidently experiment.

What to expose vs hide

Not every theme value belongs in the settings schema. Good candidates:

• Brand colors
• Typography choices
• Layout parameters (max content width, spacing scale)
• Button styles
• Section-level toggles (show/hide features)

Bad candidates:

• Things requiring CSS knowledge (box-shadow syntax, custom positioning)
• Things that would break layout at wrong values (minimum padding below which content overlaps)
• Implementation details (cache timeouts, third-party IDs)

The boundary: if a wrong value breaks the theme meaningfully, it doesn't belong in merchant-editable settings.

What ships with a well-designed theme settings schema

A theme that supports non-technical merchant self-service has:

• config/settings_schema.json with grouped, labeled, defaulted settings
• Design tokens consumed via CSS custom properties
• Settings exposed through the theme editor in an intuitive order
• Defaults that produce a usable theme without any customization
• Documentation (or help text in the editor) explaining what each setting does
• Versioning discipline - renaming a setting's ID in code breaks merchant's saved values

Merchants who can self-serve design tokens stay happier with their theme. The developer's work is making the right set of knobs available without offering footguns.