DESIGN.md

DESIGN.md is a Markdown file at the root of a theme that records the theme's design intent: the decisions behind the theme's look and feel, and the reasons for them. The theme's settings and styles in the config directory define what the storefront renders. DESIGN.md explains why, so AI agents like Sidekick can extend the design consistently when they build something new on the theme, instead of falling back on generic defaults.

Where AGENTS.md explains how the theme is built, DESIGN.md explains how the store looks and feels. It's the store's design contract, and it grows as the store's design direction develops.

Anchor to LocationLocation

DESIGN.md lives at the root of the theme, outside the theme's directories:

The file name is case-sensitive, so name the file exactly DESIGN.md. The file can be up to 50 KB. Every theme supports DESIGN.md, and the file is optional.

Anchor to ContentContent

DESIGN.md is free-form Markdown. There's no required format or outline, so structure the file in whatever way works best for your theme. Write down the decisions that an agent needs to make a new design feel like it belongs to the store.

A DESIGN.md file commonly covers the following topics:

• Brand overview: What the store sells, who it sells to, and how the store should make people feel.
• Design thesis: One sentence that connects the brand to the visual system.
• Colors: Each color's name, value, design token, and role.
• Typography: Font families, weights, sizes, line heights, letter spacing, and the role of each style.
• Spacing and composition: Rules for spacing, border radius, shadows, and layout, such as the page's maximum width.
• Components: How repeated components look, such as buttons, product cards, headers, footers, and form fields.
• Dos and don'ts: Explicit rules to follow and patterns to avoid.
• Motion: The animation and interaction patterns that define the theme.

The base theme that Canvas uses to create new themes includes a DESIGN.md that starts with a generated index of the theme's design tokens and component classes, followed by the theme's design position, styling system, constraints, and component recipes. If your theme generates part of its DESIGN.md with tooling, then mark that part clearly so agents know to preserve it, and tell agents in AGENTS.md how to keep it up to date.

When you write the file, keep the following in mind:

• Name the tokens: Refer to your theme's design tokens and settings rather than raw values, so agents apply the merchant's choices instead of hardcoding them.
• Be explicit: A rule that an agent can check, such as "don't use more than two font families", works better than a general direction, such as "keep it simple".
• Record decisions, not code: Keep implementation details in your theme code and in AGENTS.md. Use DESIGN.md for the design decisions that the code expresses.

Anchor to UsageUsage

Agents read DESIGN.md before design and styling work, and follow it when they create or change parts of the theme:

• Sidekick in Canvas: Sidekick reads DESIGN.md before it changes the theme's design or styling. When a merchant asks for stylistic changes, such as a new color palette or typography, Sidekick updates DESIGN.md so later changes follow the new direction. If a theme doesn't have a DESIGN.md when a merchant asks Sidekick to redesign the store, then Sidekick can create one.
• Your local agent: Coding agents read DESIGN.md from your local theme directory. Most agents don't read DESIGN.md automatically, so tell them to read it in your theme's AGENTS.md or as part of your agent's skills.

Because Sidekick can update DESIGN.md, pull the theme before you start local work so your agent follows the store's latest design decisions. Shopify CLI 4.8.4 and higher includes DESIGN.md when you run shopify theme pull, shopify theme push, and shopify theme package. The file also syncs through the GitHub integration, and you can edit it in the code editor. To learn about all the ways to work with theme context files, refer to Agentic workflows.