Shopify Color Palettes: Build the New Theme-Wide Color System

Shopify added a new color_palette input setting on June 17, 2026. A palette gives merchants one grid of named colors to edit, then lets ordinary color and color_background settings inherit from those theme-wide values.

This creates a useful balance: a merchant can update the brand palette once, while a section or block can still override a color locally when the design genuinely needs it.

Color schemes continue to work. Shopify does not require existing themes or new Theme Store submissions to migrate, but it recommends palettes for new themes and says future development will focus on them.

Define the palette globally

A theme can have only one color_palette, and it must live in config/settings_schema.json. Unlike most settings, it supports an id and required default object but not label, info, or visible_if.

Add it inside an appropriate settings group:

[
  {
    "name": "Theme colors",
    "settings": [
      {
        "type": "color_palette",
        "id": "colors",
        "default": {
          "primary": "#171717",
          "secondary": "#FFFFFF",
          "accent": "#2563EB",
          "muted": "#F5F5F5"
        }
      }
    ]
  }
]

The palette must contain between 2 and 20 colors. Each key must begin with a letter and contain only letters, numbers, or underscores. Values must be valid hex colors without an alpha channel.

Choose semantic keys that describe a role, such as primary, surface, or accent, rather than a temporary appearance such as blue or light_gray. A merchant can change accent from blue to orange; a setting named blue becomes misleading when they do.

Access a palette color in Liquid

Read a named entry through the palette setting ID:

{{ settings.colors.primary }}

Each entry is a Shopify color object, so color properties and filters remain available:

{% assign accent_soft = settings.colors.accent | color_modify: 'alpha', 0.12 %}

<style>
  :root {
    --color-primary: {{ settings.colors.primary }};
    --color-accent: {{ settings.colors.accent }};
    --color-accent-soft: {{ accent_soft }};
  }
</style>

You can iterate over settings.colors, but Shopify returns values in JSON order without exposing their keys inside the loop. Direct access is clearer when a design depends on a named role.

Use palette entries as section defaults

The strongest feature is the cross-setting reference. A normal color setting can inherit a palette value by using a Liquid output expression as its schema default:

{
  "type": "color",
  "id": "heading_color",
  "label": "Heading color",
  "default": "{{ settings.colors.primary }}"
}

A color_background default can include multiple palette references:

{
  "type": "color_background",
  "id": "hero_background",
  "label": "Hero background",
  "default": "linear-gradient(180deg, {{ settings.colors.secondary }}, {{ settings.colors.muted }} 100%)"
}

These dynamic defaults are supported specifically for color_palette access paths. Do not generalize the pattern to arbitrary settings.

The merchant sees a useful inheritance model:

1. The palette supplies the theme-wide starting color.
2. A section's setting points at that named color by default.
3. The merchant can override the individual section setting.
4. Editing the shared palette updates every setting that still references it.

Render section colors predictably

Use the section settings to expose CSS custom properties at the component boundary:

<section
  class="promo-banner"
  style="--promo-heading: {{ section.settings.heading_color }}; --promo-bg: {{ section.settings.hero_background }};"
>
  <h2>{{ section.settings.heading }}</h2>
</section>

{% stylesheet %}
  .promo-banner {
    color: var(--promo-heading);
    background: var(--promo-bg);
  }
{% endstylesheet %}

This keeps static layout rules in {% stylesheet %} while passing merchant-selected values through custom properties. It also fits Shopify's CSS subsetting model, where component-owned stylesheet rules travel with the Liquid file that renders the component.

What happens during theme updates

If a later theme version adds a new key to the palette's default object, Shopify adds it to the merchant's palette while preserving customized values. That makes it safer to evolve semantic color roles in theme updates.

When a merchant deletes a palette entry in the editor, Shopify asks for a replacement and stores a reference to that replacement. Existing section references therefore keep working without manually editing every setting.

Even with those safeguards, avoid renaming or deleting keys casually. Treat palette keys like a public component contract: document them, reuse them consistently, and test upgrades with real settings_data.json from a customized store.

Palettes versus color schemes

Color palettes	Color schemes
A global grid of named color values	Bundles several role-specific colors into selectable schemes
Individual settings can inherit palette values	A section typically selects one complete scheme
Merchants can override a single local setting	Merchants switch a coordinated group at once
Recommended direction for new theme systems	Still supported; no forced migration

You do not need to remove color schemes from a mature theme merely because palettes exist. For a new design system, evaluate whether palette references give merchants the control you want. For an existing design, migrate only when the editing experience and maintenance benefits justify the change.

Migration checklist

1. Inventory global color roles and section-level overrides.
2. Choose stable semantic names for 2–20 palette entries.
3. Add one color_palette to settings_schema.json.
4. Point new color and color_background defaults at palette entries.
5. Preserve existing merchant values while testing settings_data.json upgrades.
6. Verify contrast in every default and overridden combination.
7. Test sections, blocks, app blocks, and dynamic rendering paths.
8. Document which roles are global and which controls are intentionally local.

Never assume a palette guarantees accessibility. Merchants can change colors, so pair important combinations with clear guidance and test the defaults against your contrast requirements.

Shopify's color palette announcement explains the direction, while the color_palette input-setting reference defines placement, key, value, and reference rules.

Use the Schema Builder for the surrounding section settings and the complete schema reference when integrating those settings into reusable sections and blocks.