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 responsibility | Evidence it can provide | What it cannot prove | |
|---|---|---|---|
| Approved upstream source | Defines 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.md | Explains 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 setting | Stores a theme-owned or merchant-configurable choice. | The value is configured for the recorded theme state. | That every intended section consumes it. |
| Implementation style | Maps 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 consumer | Uses 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 observation | Records 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. |
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.
| Class | Appropriate use | Boundary | |
|---|---|---|---|
| Current Shopify theme documentation | Current platform documentation | Use 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 system | Versioned upstream authority approved by the team | Use it when its recorded revision and scope govern the visual direction. | Its names and artifacts still require a deliberate Shopify mapping. |
| Reconstructed Shopify reference | Third-party interpretation | Use 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 package | Historical Shopify package | Use 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 recipe | React Native implementation route | Use it when maintaining the documented Restyle route. | It is not a default implementation recipe for a Liquid storefront theme. |
| General token guidance | Platform-neutral conceptual guidance | Use it for concepts such as semantic roles, aliases, and component layers. | It cannot decide which Shopify setting, style, or section owns a theme decision. |
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
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
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
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
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
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.
| Destination | Use it when | Avoid it when | |
|---|---|---|---|
| DESIGN.md | Written theme contract | The decision is explanatory, contextual, compositional, or a constraint an agent must understand. | The storefront needs the value at runtime. |
| Theme setting | Theme configuration | The 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 role | Shared implementation mapping | Several 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 contract | Consumer-owned structure and behavior | A named consumer owns structure, variants, states, or responsive behavior. | The same semantic decision should remain synchronized across unrelated consumers. |
| Unresolved decision | Explicit open state | Authority is missing, sources conflict, or the intended owner has not decided. | A developer merely wants to avoid an empty field. |
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 changesStart 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 renderAmbient Sage's actual tokens — the same values its exports use.
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 intake | Proposed Shopify destination | Current evidence state | |
|---|---|---|---|
| Background role | Ambient 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 roles | Ambient 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 role | Ambient 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 typography | Plus 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 typography | JetBrains 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 rounding | The 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. |
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 result | Evidence to collect | Initial status | |
|---|---|---|---|
| Navigation | Navigation 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 card | Card 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 action | Default, 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 state | Input 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 surface | Adjacent 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 change | Changing 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 layout | The 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 |
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
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
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
Check the theme setting
Confirm that the intended destination exists, holds the recorded value, and belongs to the expected merchant or theme authority.
- 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
Check the Liquid or section consumer
Confirm that the named consumer references the mapped role or setting for the relevant variant and state.
- 6
Check local overrides
Inspect section-specific styles, inline values, wrappers, breakpoint rules, and approved exceptions that may replace the shared mapping.
- 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
- DESIGN.md - Shopify Dev Docs: Shopify defines DESIGN.md as a theme-root record of design intent, while theme settings and styles in the config directory define what the storefront renders.
- Shopify Design System, Tokens and DESIGN.md | DesignMD: DesignMD presents its Shopify material as an inspired interpretation and offers token previews and exports, so those values require separate provenance and adoption checks.
- Design tokens for Polaris, Shopify's design system - GitHub: The Polaris token repository documents historical package and distribution routes but is archived, making it a legacy source rather than default current storefront-theme guidance.
- Getting Setup With the Shopify Design System | Restyle: The Restyle guide imports Polaris tokens into a React Native theme, demonstrating a separate implementation route rather than a Shopify storefront-theme contract.
- Ambient Sage Design Kit: The public Ambient Sage kit supplies a DESIGN.md, 28 semantic light and dark token roles, Plus Jakarta Sans and JetBrains Mono typography, and portable implementation artifacts.