---
title: DESIGN.md
description: >-
  Learn how to use a theme-root DESIGN.md file to record the design intent that
  AI agents follow when they build on your theme.
source_url:
  html: 'https://shopify.dev/docs/storefronts/themes/agentic-workflows/design-md'
  md: 'https://shopify.dev/docs/storefronts/themes/agentic-workflows/design-md.md'
api_name: liquid
---

# 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](https://help.shopify.com/en/manual/shopify-admin/productivity-tools/sidekick) can extend the design consistently when they build something new on the theme, instead of falling back on generic defaults.

Where [`AGENTS.md`](https://shopify.dev/docs/storefronts/themes/agentic-workflows/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.

***

## Location

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

## Theme directory structure

```text
.
├── AGENTS.md
├── DESIGN.md
├── assets
├── blocks
├── config
├── layout
├── locales
├── sections
├── snippets
└── templates
```

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.

***

## Content

`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.

***

## Usage

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.

**Note:**

AI agents are non-deterministic. Agents follow the design intent in `DESIGN.md` most of the time, but they might sometimes take a different approach. Use the file to shape and guide an agent's reasoning, not as a guarantee that every decision is followed.

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](https://shopify.dev/docs/storefronts/themes/tools/github), and you can edit it in the [code editor](https://shopify.dev/docs/storefronts/themes/tools/code-editor). To learn about all the ways to work with theme context files, refer to [Agentic workflows](https://shopify.dev/docs/storefronts/themes/agentic-workflows#developer-tools-and-resources).

***