Get started

Shopify theme design tokens: map DESIGN.md to settings and styles

In a Shopify theme, DESIGN.md records design intent, but it doesn't control the rendered storefront. Theme settings and styles implement those decisions, storefront sections consume them, and a browser observation shows whether the chain worked. Trace one semantic role through those layers before expanding the system.

Updated November 20, 2026

Keep intent, configuration, consumption, and observation separate

Shopify's current theme documentation draws the controlling boundary: DESIGN.md records the decisions behind a theme's look and feel, while theme settings and styles define what the storefront renders. DESIGN.md can guide a person or coding agent, but it isn't a runtime token store and doesn't prove that any section follows its rules.

A dependable workflow separates six responsibilities. The approved upstream source establishes the design decision. DESIGN.md explains its meaning, permitted use, and constraints. A theme setting stores a theme-owned or merchant-configurable choice, while styles translate reusable roles into implementation values. Liquid sections, snippets, and other storefront code consume those settings and styles. An observation then records what a named storefront surface rendered under stated conditions.

Primary responsibilityEvidence it can provideWhat it cannot prove
Approved upstream sourceDefines the accepted role, value, relationship, or rule at a recorded revision.The decision existed and was approved at that revision.That the Shopify theme mapped or rendered it.
DESIGN.mdExplains intent, composition, usage, constraints, and named theme concepts.An agent or developer has a current design contract to follow.That runtime settings or styles match the contract.
Theme settingStores a theme-owned or merchant-configurable choice.The value is configured for the recorded theme state.That every intended section consumes it.
Implementation styleMaps a reusable role to CSS or another theme implementation artifact.The project can resolve the intended style rule.That local overrides do not replace it.
Storefront consumerUses the setting or style in a named section, snippet, or component.The implementation is connected at that consumer.That the browser produced the expected result.
Rendered observationRecords the visible and computed outcome under stated conditions.What happened in the tested theme, page, viewport, state, and revision.What happens in untested consumers or after a relevant change.
Responsibility map for a Shopify theme token

Availability is not adoption

A value can be available in an export, documented in DESIGN.md, configured in a theme, or consumed by a section. Each is a different evidence state. Don't collapse them into one done flag.

Choose the source from the correct product surface and era

Several artifacts use Shopify's name, but they answer different questions. As observed on November 20, 2026, Shopify's current DESIGN.md documentation governs the theme contract discussed here. A reconstructed commercial reference offers candidate values and convenient exports. The archived Polaris token repository documents a historical package route, while the Restyle guide applies Polaris tokens to React Native. General token guides explain useful concepts, but they don't assign responsibility inside a Shopify theme.

ClassAppropriate useBoundary
Current Shopify theme documentationCurrent platform documentationUse it to establish what DESIGN.md means in a Shopify theme and how it relates to settings and styles.It does not provide a complete source-to-render acceptance record for your theme.
Approved external design systemVersioned upstream authority approved by the teamUse it when its recorded revision and scope govern the visual direction.Its names and artifacts still require a deliberate Shopify mapping.
Reconstructed Shopify referenceThird-party interpretationUse it for research or as a candidate direction requiring approval.A preview or export does not establish current Shopify provenance or theme adoption.
Archived Polaris token packageHistorical Shopify packageUse it to investigate history or maintain an existing dependency that deliberately retains it.Archive visibility and former package formats do not make it current storefront guidance.
Restyle and Polaris recipeReact Native implementation routeUse it when maintaining the documented Restyle route.It is not a default implementation recipe for a Liquid storefront theme.
General token guidancePlatform-neutral conceptual guidanceUse it for concepts such as semantic roles, aliases, and component layers.It cannot decide which Shopify setting, style, or section owns a theme decision.
Authority and era map observed November 20, 2026

Follow one precedence rule. Preserve an explicit, current, theme-owned decision unless its authorized owner approves a replacement. If an approved external system governs the visual direction, translate it role by role instead of importing names blindly. Reconstructed values are candidates. When sources conflict, record the conflict and its owner rather than choosing the more convenient value. If the source has no answer, leave the field unresolved instead of inferring a permanent token from a screenshot.

  1. 1

    Freeze the source revision

    Record the source name, version or date, relevant mode, and approval scope. A changing URL without a captured revision is weak authority.

  2. 2

    Classify its authority

    Mark the source as theme-owned, approved external, reconstructed, historical, or general guidance. The class determines what may be adopted without another decision.

  3. 3

    Check for a current theme decision

    Inspect the named theme setting, existing style role, and consumer before proposing a replacement. Preserve merchant-configurable behavior unless the requirement explicitly changes it.

  4. 4

    Resolve conflicts through ownership

    When sources disagree, name the decision owner and leave implementation pending. Don't let file order or an agent's preference become the conflict rule.

  5. 5

    Leave unknown values open

    Use an explicit unresolved state with an owner and decision trigger. A missing value is safer than a plausible reconstruction presented as canonical.

Write DESIGN.md as the reasoned contract

A Shopify theme DESIGN.md should make the theme legible to an agent without pretending to be executable configuration. Name semantic roles and theme settings instead of repeating raw values wherever possible. Explain the visual intent, typography roles, composition rules, component treatments, responsive principles, and constraints that should survive implementation changes.

For each important rule, state when it applies and what would violate it. A useful color rule names a role, its permitted surfaces, its foreground relationship, and any mode or merchant-control boundary. A typography rule names the role and hierarchy, not merely a font family. Composition guidance explains section rhythm, alignment, and density. Component guidance should identify supported treatments and states without claiming behavior that the theme hasn't implemented.

  • Purpose and visual direction: the experience the theme should preserve.
  • Named roles and settings: the vocabulary agents should use instead of raw values.
  • Typography: heading, body, utility, and technical roles, including available weights when approved.
  • Composition: section rhythm, containers, alignment, responsive intent, and image treatment.
  • Component rules: actions, cards, forms, navigation, product information, and their required states.
  • Explicit constraints: forbidden substitutions, hardcoding rules, merchant-control boundaries, and unresolved decisions.
  • Generated-section markers: how generated work should identify its scope when the theme workflow requires it.
  • Maintenance instructions: when DESIGN.md must change and how repository-level agent instructions point agents to it.

Name the decision, not only the value

A rule such as "primary actions use the theme's primary-action role" survives a palette change. Telling every agent to use one hex value bypasses merchant settings and makes the documentation stale sooner.

Map roles into theme-owned settings and styles

The frozen evidence doesn't establish a universal Shopify token taxonomy that applies to every theme. Start with the actual theme. Inventory its current settings, reusable style roles, and representative consumers. Then decide where each upstream role belongs based on who should control it and how broadly it should change.

Put a decision in a merchant-configurable theme setting when a merchant is expected to change it through supported controls. Use styles for a reusable implementation role when several consumers should resolve the same decision. Keep contextual structure or behavior with the section or component that owns it. DESIGN.md holds the rationale, usage boundaries, and instructions an agent needs but the runtime can't enforce.

DestinationUse it whenAvoid it when
DESIGN.mdWritten theme contractThe decision is explanatory, contextual, compositional, or a constraint an agent must understand.The storefront needs the value at runtime.
Theme settingTheme configurationThe theme intentionally exposes the choice to merchants or stores it as theme configuration.The value is fixed implementation detail or the theme has no supported control for it.
Reusable style roleShared implementation mappingSeveral consumers should share a semantic decision such as a surface, text, border, action, or spacing role.The rule belongs only to one component or depends on local structure.
Section or component contractConsumer-owned structure and behaviorA named consumer owns structure, variants, states, or responsive behavior.The same semantic decision should remain synchronized across unrelated consumers.
Unresolved decisionExplicit open stateAuthority is missing, sources conflict, or the intended owner has not decided.A developer merely wants to avoid an empty field.
Placement test for an approved design decision

Don't bypass a merchant choice by hardcoding the upstream value in a section. If a theme setting already owns the decision, map the approved role to that setting and have the consumer use it. Introducing or changing a setting is a theme design decision that needs its own approval and verification. This guide doesn't claim a universal settings_schema field or provide a drop-in schema patch.

record_id: shopify-role-primary-action
source:
  name: Approved brand system
  revision: 2026-11-20
  authority_class: approved_external
  decision: Primary action background and paired foreground
mapping:
  semantic_role: primary-action
  shopify_destination: Existing merchant-configurable primary action setting
  implementation_artifact: Theme-owned semantic style role
  consumer: Featured product section, add-to-cart action
acceptance:
  condition: Published test theme, product available, default state, 1280px viewport
  expected: Action resolves the configured background and paired foreground without a local raw-color override
  observed: Not run
  first_divergence: Not assessed
ownership:
  mapping_owner: Theme team
  observation_owner: Storefront reviewer
  retest_trigger: Source revision, setting definition, style mapping, consumer markup, or relevant section override changes
A complete source-to-storefront record. Duplicate it for one real role and replace every field with project evidence.

Start from a complete upstream system

If your Shopify mapping lacks named semantic roles, typography, spacing, layout rules, or DESIGN.md guidance, inspect a public Identity Forge kit before deciding the theme destinations. The kit is upstream input, not a Shopify importer.

Keep archived Polaris routes outside the default storefront path

The Polaris token repository remains easy to find because it documents npm, Ruby, CSS, and other former distribution routes. The repository is archived. Its historical usefulness doesn't make it the current authority for a storefront theme's DESIGN.md, merchant settings, or Liquid consumers.

The Restyle guide is useful, but it covers a separate route. It imports Polaris tokens and transforms them into a React Native theme. That procedure may matter to a mobile codebase that deliberately uses Restyle. It doesn't establish how a Shopify storefront theme should map design decisions into its settings, styles, and sections.

A package can remain real after its default route expires

Archived material may still explain an existing dependency. Record the package version, consumer, and reason for retaining it. The mistake is treating historical availability as current authority for a different product surface.

Worked intake: Ambient Sage into a Shopify theme

Ambient Sage provides a concrete upstream source without implying that anyone has tested a Shopify integration. Its public v1 record was updated on July 30, 2026. The kit includes 28 semantic roles in light and dark, a compact-product typography scale, DESIGN.md, and portable token artifacts. Plus Jakarta Sans fills heading and body roles at weights 400, 500, 600, and 700. JetBrains Mono fills the mono role at weights 400, 500, and 700.

Token specimen · real values

Ambient Sage

Live render

Ambient Sage's actual tokens — the same values its exports use.

Color tokensSemantic roles with HEX / HSL / CMYK

Color tokens

Ambient Sage
light · HEX · HSL · CMYK

Core

#F3F4EF

background

H 72 · C0, 0, 2, 4

#1A1C17

foreground

H 84 · C7, 0, 18, 89

#E5E6E0

card

H 70 · C0, 0, 3, 10

#ECEEE8

muted

H 80 · C1, 0, 3, 7

#D8D9D2

border

H 68.57 · C0, 0, 3, 15

Brand

#FEE951

primary

H 52.72 · C0, 8, 68, 0

#1A1C17

primary-fg

H 84 · C7, 0, 18, 89

#E5E6E0

secondary

H 70 · C0, 0, 3, 10

#F7E464

accent

H 52.24 · C0, 8, 60, 3

#FEE951

ring

H 52.72 · C0, 8, 68, 0

Semantic

#C0392B

destructive

H 5.64 · C0, 70, 78, 25

#FFFFFF

destructive-fg

H 0 · C0, 0, 0, 0

#2D7238

success

H 129.57 · C61, 0, 51, 55

#C97D12

warning

H 35.08 · C0, 38, 91, 21

#545651

muted-fg

H 84 · C2, 0, 6, 66

Charts

#FEE951

chart-1

H 52.72 · C0, 8, 68, 0

#4A8FD4

chart-2

H 210 · C65, 33, 0, 17

#6BBF8A

chart-3

H 142.14 · C44, 0, 28, 25

#E07498

chart-4

H 340 · C0, 48, 32, 12

#E8A24B

chart-5

H 33.25 · C0, 30, 68, 9

Type scaleHeading, body, and mono in the kit's fonts

Typography

Ambient Sage

Scale: compact-product

Density: balanced

Heading · Plus Jakarta Sans · 1.875rem

Ship beautiful product faster

Subheading · Plus Jakarta Sans · 1.375rem

A warm-sage neutral-surface mobile kit with a single vivid yellow accent, flat tonal cards, and oversized display numerals.

Body · Plus Jakarta Sans · 1rem

Ambient Sage uses a near-white warm-sage canvas (#f3f4ef) with card panels distinguished only by a tonal shift to #e5e6e0, never by shadows or borders. A single vivid yellow (#fee951) is the only saturated color and appears sparingly at component scale as orbs, button fills, and focus rings. Primary data values render as oversized bold hero numerals with a small superscript unit. Typography is a friendly rounded geometric (Plus Jakarta Sans) with no uppercase and no tight tracking, while JetBrains Mono is reserved for hex codes and technical strings. Generous rounding and luminance-only contrast give the whole system a calm, minimal feel.

Mono · JetBrains Mono · 0.8125rem

npx shadcn add ambientsage.json

Aa

Plus Jakarta Sans · Heading

400500600700

Aa

Plus Jakarta Sans · Body

400500600700

ABCDEFGHIJKLM NOPQRSTUVWXYZ

abcdefghijklmnopqrstuvwxyz

0123456789 & @ # % →

Radius & spacingCorner radius, elevation, and spacing steps

Tokens

Ambient Sage primitives
density: balanced

Radius scale

sm · 0.375rem
md · 0.75rem
lg · 1.25rem
xl · 1.75rem

Component radius

button
card
input

Elevation

level 1
level 2
level 3
level 4

Spacing · base 4px

1x
2x
3x
4x
6x
8x
Ambient Sage shows the upstream roles and scale being considered. It does not show a verified Shopify mapping.

A proposed mapping might connect Ambient Sage's background role to an existing theme canvas setting, its primary role and paired foreground to the theme's primary action settings, its card role to a reusable product-card surface style, and its body typography role to the theme's supported body-font configuration. These are proposals only. The destination identifiers, available font route, merchant controls, section consumers, and rendered results all remain open until someone inspects them in a named theme.

Verified upstream intakeProposed Shopify destinationCurrent evidence state
Background roleAmbient Sage includes a semantic background role for its light system.Existing theme canvas or page-background setting, if that setting owns the decision.Shopify mapping not inspected; render not run.
Primary and foreground rolesAmbient Sage includes paired semantic action roles.Existing merchant-configurable primary action background and foreground settings.Shopify mapping not inspected; state coverage not run.
Card or elevated surface roleAmbient Sage defines differentiated semantic surfaces.Reusable product-card or section-surface style using a theme-owned mapping.Consumer and local overrides not inspected.
Body and heading typographyPlus Jakarta Sans is assigned to body and heading roles at recorded weights.Theme-supported typography settings and font-loading implementation.Font availability, loading, fallback, and storefront rendering not verified.
Mono typographyJetBrains Mono is reserved for technical strings in the upstream kit.Only a named storefront use that genuinely needs a technical text role.No Shopify consumer selected.
Compact spacing and roundingThe kit publishes a compact-product scale and generous rounding.Theme-owned spacing and radius roles where the current theme supports equivalent decisions.No equivalence or responsive behavior verified.
Unexecuted Ambient Sage mapping record

No direct Shopify compatibility claim

Identity Forge supplies upstream DESIGN.md, semantic tokens, typography, spacing, layout guidance, and portable exports. This example doesn't claim a Shopify importer, automatic theme mapping, or tested compatibility with a named theme.

Write expectations before inspecting the storefront

An acceptance matrix should define what the representative consumer must do before anyone inspects the result. Otherwise, a polished screenshot can quietly redefine the requirement. Keep the matrix bounded. Choose cases that exercise shared roles, merchant control, states, composition, and responsive behavior without claiming full-theme coverage.

Expected resultEvidence to collectInitial status
NavigationNavigation uses the approved surface and text roles, preserves readable active and focus states, and contains no accidental raw-color override.Theme revision, active settings, consumer reference, computed styles, keyboard state, viewport, and capture.Not run
Product cardCard surface, text hierarchy, price treatment, image relationship, and spacing resolve through the intended theme mappings.Named section and card consumer, product content condition, computed values, narrow and wide captures.Not run
Primary actionDefault, hover, focus, and disabled appearances use the mapped primary and paired foreground roles.Setting values, style declarations, state selectors, computed styles, and captures for each required state.Not run
Form stateInput surface, border, focus, error, and supporting text remain distinguishable and use their assigned roles.Named form, validation condition, keyboard path, computed styles, and state captures.Not run
Section surfaceAdjacent sections preserve the documented surface hierarchy without a local value breaking the relationship.Section settings, wrappers, local overrides, computed backgrounds, and page capture.Not run
Merchant changeChanging the supported theme setting reaches every intended consumer and leaves unrelated roles unchanged.Before and after setting values, affected-consumer list, protected-consumer list, and matched captures.Not run
Narrow and wide layoutThe same semantic roles remain intact while the documented composition adapts at representative narrow and wide widths.Exact viewports, content fixture, section structure, computed roles, wrapping, and captures.Not run
Expectation-first matrix. Every initial status is deliberately unexecuted.

Passing one row proves only that row under its recorded conditions. It doesn't approve the whole theme, every template, every product state, or every merchant configuration. Expand coverage according to the mapping's reach. A shared action role deserves more representative consumers than a rule confined to one promotional section.

Find the first divergent layer

When the storefront differs from the expectation, start at the source and stop at the first mismatch. This keeps you from patching a downstream symptom in the wrong layer. A local CSS override may be the visible cause, but it may also compensate for an incorrect theme mapping. Record what each layer contains before changing anything.

  1. 1

    Check the upstream decision

    Confirm the source revision, role, mode, value or reference, usage rule, and approval scope. If the decision is absent or contested, return it to the source owner.

  2. 2

    Check the DESIGN.md statement

    Confirm that the theme contract names the same role, purpose, constraints, and merchant-control boundary. Correct stale intent before asking an agent to follow it.

  3. 3

    Check the theme setting

    Confirm that the intended destination exists, holds the recorded value, and belongs to the expected merchant or theme authority.

  4. 4

    Check the generated or authored style

    Confirm that the semantic role resolves to the intended implementation value under the tested mode and condition.

  5. 5

    Check the Liquid or section consumer

    Confirm that the named consumer references the mapped role or setting for the relevant variant and state.

  6. 6

    Check local overrides

    Inspect section-specific styles, inline values, wrappers, breakpoint rules, and approved exceptions that may replace the shared mapping.

  7. 7

    Check the rendered storefront

    Record computed values and visible behavior for the named page, content, state, viewport, theme revision, and merchant configuration.

Assign the correction to the owner of the first divergent layer. Don't rewrite the upstream system because one section contains a local override, and don't patch the section when the theme setting maps the wrong role. After the correction, rerun the failed case and any protected cases the change could reach.

Map one representative section before scaling the contract

Begin with one section that exercises several important decisions, such as a featured product section with a surface, heading, body text, price, primary action, image, and responsive layout. Complete the source-to-storefront record, run the relevant acceptance rows, and resolve the first divergence. Only then should you extend the same contract to more sections.

This narrow start reveals the theme's real ownership model without suggesting that a successful export or one clean screenshot proves adoption. Choose one semantic role in one representative section, complete the record, and leave the observed result as not run until someone inspects the rendered storefront.

Sources