Skip to content
Shopify Theme Handbook

Design System & Configuration

TL;DR: How Figma design tokens become theme settings that are easy to maintain and easy for merchants to use.

Every theme has two different people who care about its design choices. There’s you, the developer who writes the CSS. And there’s the merchant, who uses Shopify’s theme editor to pick colors and fonts without touching any code.

This section is about the layer that serves both of you: the general design token model, and how a Figma token becomes a real theme setting.

Get this layer right, and both you and the merchant have a smooth experience. Get it wrong, and you end up with a settings panel that doesn’t match your CSS.

What’s on this page group

Section titled “What’s on this page group”

Why this is its own section

Section titled “Why this is its own section”

Scaffold Setup Guide walks you through building your first section and its settings. This section goes deeper into the same topic.

Here’s why it matters. A theme with 40 or more sections only works well if you plan its design tokens early. If you don’t plan ahead, things get messy section by section, and that mess is hard to clean up later.

Read this section fully before your theme grows past a handful of sections. Adding a token system to 20 sections that already hardcode their own values (write fixed values straight into the code instead of using a shared token) is a much bigger job than starting with a token system from day one.

Do / Don’t

Section titled “Do / Don’t”
✅ Do❌ Don’t
Design your token system before you write your first section’s CSS. Don’t wait until your third section has different, hardcoded values that don’t match.Building sections before you settle on a token system. You end up adding tokens later, on top of a growing pile of hardcoded values.
Treat every setting id you expose as a promise to merchants. See Config & Global Settings to learn what happens if you break that promise.—

Further reading

Section titled “Further reading”