Theme Developer

The theme-developer agent carries all conventions for building Shopify Online Store 2.0 themes using Liquid, JSON templates, and the Shopify CLI. Activate it at the start of every theme project session.

activate_agent("theme-developer")

What It Covers

Component taxonomy: Snippets, blocks, sections, templates — with creation rules, {% doc %} headers, {% schema %} patterns, and code examples
Build order: Tokens, snippets (atomic), snippets (composite), blocks, sections, templates
Token system: CSS custom properties in assets/tokens.css with RGB channel format for alpha support
CSS rules: BEM-lite naming, mobile-first, component-scoped via {% stylesheet %}
JavaScript rules: {% javascript %} tags, native browser APIs, data- attributes for hooks
Translation rules: {{ 'key' | t }}, t: prefix for schema labels, locales/en.default.json
Validation: validate_theme from Shopify Dev MCP, per-type checklists
Performance patterns: render vs include, all_products avoidance, capture memoisation, section.index
Figma config: clientLanguages: "html,css,liquid", clientFrameworks: "shopify"

Directory Structure

.
├── theme/
│   ├── assets/         # CSS, JS, SVGs, images, tokens.css
│   ├── blocks/         # Editor-configurable block components
│   ├── config/         # settings_schema.json, settings_data.json
│   ├── layout/         # theme.liquid, password.liquid
│   ├── locales/        # Translation JSON files
│   ├── sections/       # Full-width page sections
│   ├── snippets/       # Reusable Liquid primitives
│   └── templates/      # Page templates (JSON format)
├── .mcp.json
├── CONVENTIONS.md
├── INSTRUCTIONS.md
├── shopify.theme.toml
└── package.json

Component Types

Type	Purpose	Location	Has Schema
Snippet	Reusable UI primitive	`snippets/{name}.liquid`	No
Block	Editor-configurable component	`blocks/{name}.liquid`	Yes
Section	Full-width page module	`sections/{name}.liquid`	Yes
Template	Page layout (JSON)	`templates/{name}.json`	No

Commands

Task	Command
Set up or onboard a project	`setup`
Extract tokens, icons, logos from Figma	`design-system`
Build snippets, blocks, sections, templates	`build`
Visual QA against Figma	`refine`
Accessibility audit	`accessibility`
Performance optimisation	`performance`
SEO audit	`seo`
Code audit	`audit`
Commit changes	`commit`

Session Init

Before writing any code, the agent instructs:

Load get_conventions for universal rules and MCP toolchain
Read the project’s CONVENTIONS.md for tokens, component APIs, overrides
Call learn_shopify_api from Shopify Dev MCP (once per session)
Call get_project_context for project memory