Shopify color_palette setting: replace color schemes (2026)

On June 17 2026, as part of the Spring '26 Edition, Shopify shipped a new theme setting type: color_palette. It's a flat, named set of colors that a merchant edits in one grid, and every color setting in the theme can point at it. More importantly, Shopify now recommends it over color schemes as the way to model a theme's color system for new themes. If you've spent the last few years wiring up color_scheme_group and role maps, this is a meaningful simplification.

This post covers what the setting is, the exact schema it expects, how to reference palette colors as defaults from individual settings, what changes for merchants, and when (and when not) to migrate an existing theme. For the wider context of what else shipped, see our Spring '26 Edition rundown for developers.

What is the color_palette setting in Shopify?

A color_palette is a global set of named colors defined once in settings_schema.json. Merchants see those colors as a grid in the theme editor and pick from them whenever they adjust any color or color_background setting. You can define between 2 and 20 colors. There can be only one palette per theme, and it must live in settings_schema.json.

The schema is short. Unlike most input settings, color_palette supports only the id attribute (required) plus a default object: label, info, and visible_if are not supported. The default object holds the starting palette as key-value pairs.

1{2  "type": "color_palette",3  "id": "colors",4  "default": {5    "primary": "#121212",6    "secondary": "#FFFFFF",7    "accent": "#FF4416"8  }9}

The rules on those keys and values are strict, and worth getting right the first time: keys must start with a letter and can contain letters, digits, and underscores. Values must be valid hex colors without an alpha channel (for example #FFF or #FF4416). Eight-digit hex values with alpha are not supported. At least two entries are required, up to a maximum of twenty.

How to access palette colors in Liquid

Each palette color is returned as a full color object, not a plain string, so you get the usual color filters (color_to_rgb, color_mix, color_modify, and so on). You access an individual color by its key through settings.<id>.<key>, where <id> is the palette's id.

1{{ settings.colors.primary }}2 3{% for color in settings.colors %}4  {{ color }}5{% endfor %}

One thing to know about iteration: looping over the palette yields each color as a color object in JSON-key order, but the keys themselves are not available during iteration, only the values. So a {% for %} is fine for rendering swatches or generating a row of variables, but if you need to address a specific color, reach for it by key.

Using a palette color as a setting default

This is the part that makes palettes worth adopting. A color or color_background setting can use a palette color as its default, by setting the default to a Liquid output tag that references a palette key. When the merchant later edits that palette color, every setting whose default points at it updates automatically.

1{2  "type": "color",3  "id": "heading_color",4  "label": "Heading color",5  "default": "{{ settings.colors.primary }}"6}

The same works for color_background, and palette references can be embedded inside a gradient string:

1{2  "type": "color_background",3  "id": "hero_gradient",4  "label": "Hero gradient",5  "default": "linear-gradient(180deg, {{ settings.colors.primary }}, {{ settings.colors.secondary }} 100%)"6}

color_palette vs color schemes: what changed

Color schemes (the color_scheme_group setting that defined named groups like background-1 with a role map, plus the color_scheme setting sections used to pick one) are now deprecated. Shopify's docs are explicit: the color_scheme and color_scheme_group types have been replaced by color_palette, and new themes should use the palette.

The mental-model difference: a scheme bundled a set of related colors (background, text, button, border) that had to move together, and you mapped them to semantic roles. A palette is flatter. It's a bag of named brand colors, and you compose the relationships yourself by pointing section and block settings at palette keys. For most themes that's less ceremony and a clearer story for the merchant: one place to manage brand colors, no need to understand grouped role relationships.

• Local overrides replace per-scheme tweaks. A color setting with no default lets a merchant set a one-off color on a single section or block. Unset, it returns blank in Liquid and the editor shows a Clear option, so your CSS handles the fallback. Pair palettes (the baseline) with local overrides (targeted exceptions).
• Theme updates merge cleanly. When a theme update adds new keys to the palette default, those keys appear automatically in the merchant's palette. Values the merchant already customised are preserved and take precedence.
• Deleting a color is safe. When a merchant deletes a palette color in the editor, Shopify asks them to pick a replacement and stores the deleted color as a reference to that replacement. Existing references keep working without you touching every template.

How to migrate from color schemes to color_palette

There is no automatic converter, and the two models don't map one-to-one (schemes group colors, a palette flattens them). If you're rebuilding, the practical path is:

1. List the distinct brand colors your schemes actually used, the unique hex values across every scheme, not every role in every scheme.
2. Define one color_palette in settings_schema.json with those colors, named by role (primary, accent, text, surface).
3. For each section and block that previously read a scheme role, replace it with a color setting whose default references the right palette key, and add no-default overrides where merchants need per-section control.
4. Remove the color_scheme_group and color_scheme settings, and update the CSS custom properties your sections emit to read the new settings.

If you want to see the pattern in a real, current theme rather than a toy example, the latest Horizon release uses the palette system throughout. Sections and blocks are composed from palette-referencing color settings rather than scheme roles. For how those sections and blocks fit together in Horizon generally, see Shopify sections, blocks and theme blocks explained.

What AI tools get wrong here

This feature is new enough that most models' training data predates it, which produces two failure modes worth watching for when you review AI-generated theme code.

• It reaches for color schemes by reflex. Ask for "a theme color system" and you'll often get color_scheme_group with a full role map, because that's what the bulk of the training corpus shows. That code still runs, but it's the deprecated approach. For a new theme, ask explicitly for color_palette.
• It invents palette attributes. A palette supports only id and default. If you see a generated palette with label, info, or per-color objects with metadata, that's hallucinated. The default is a flat key-to-hex map, nothing more.
• It forgets the alpha rule. Eight-digit hex with an alpha channel is not allowed in a palette default. A generated #FF441680 will be rejected. Catch it in review.

The durable skill here isn't memorising the schema, it's knowing the difference between "compiles" and "is the current recommended pattern," and checking new platform features against Shopify's docs rather than trusting a model's recall. That's exactly the judgement we build in the curriculum.

Want the deeper version of brand tokens (colors, fonts, radius) and theme-wide settings? The Module 3 lessons take you from a single palette through dark-mode and section-level overrides on a production-shaped theme.