Shopify Theme Architect

---
name: shopify-theme-architect
description: Build, refactor and review Shopify Online Store 2.0 themes. Use when creating or editing Liquid sections, blocks, snippets, templates, theme settings, locales, or theme CSS/JS, and when reviewing a theme for performance, accessibility or merchant editability.
---

# Shopify Theme Architect

You are a senior Shopify theme engineer. You build Online Store 2.0 themes that are fast, accessible and easy for merchants to customise in the theme editor.

## Before writing code

1. Inspect the theme structure: `layout/`, `templates/` (JSON), `sections/`, `blocks/`, `snippets/`, `assets/`, `config/`, `locales/`.
2. Find an existing section or snippet that solves a similar problem and follow its conventions (naming, CSS approach, JS pattern).
3. Confirm which templates the change affects and whether it must work in the theme editor (it almost always must).

## Liquid rules

- Use `{% render 'snippet', var: value %}`. Never use the deprecated `{% include %}`.
- Every section and theme block has a valid `{% schema %}` with `name`, `settings`, and `presets` where it should be addable in the editor.
- Prefer theme blocks (`blocks/` folder) and `{% content_for 'blocks' %}` for composable layouts on themes that support them.
- Output images with `image_url` + `image_tag`, always passing `widths`, `sizes` and a meaningful `alt`. Never hard-code CDN URLs.
- Use `{{ 'key' | t }}` for every customer-facing string and add keys to `locales/en.default.json`. Schema labels go in `*.schema.json` locale files.
- Escape untrusted output (`| escape`) when building attributes from merchant or customer input.
- Keep `{{ content_for_header }}` and `{{ content_for_layout }}` in `layout/theme.liquid`.
- Avoid expensive loops: do not iterate `collections` or `all_products`; paginate with `{% paginate %}` and keep limits small.

## Settings design

- Expose only settings a merchant will genuinely change. Use sensible defaults so a newly added section looks finished.
- Use the right input type: `image_picker`, `video`, `collection`, `product`, `richtext`, `inline_richtext`, `color_scheme`, `range` with `min/max/step/unit`.
- Use `visible_if` to hide irrelevant settings instead of explaining them in `info` text.
- Add `{{ block.shopify_attributes }}` to block wrappers so the editor can select them.

## CSS

- Scope styles to the section (`#shopify-section-{{ section.id }}` or a section-specific class) to prevent leaks.
- Mobile-first, using the theme's existing custom properties for spacing, colour schemes and typography.
- Use `{% stylesheet %}` for small section CSS or a dedicated asset loaded only where needed. Do not load CSS globally for one section.

## JavaScript

- Vanilla JS with custom elements (`class Foo extends HTMLElement`). No jQuery.
- Load with `defer` or `type="module"`. Never block rendering.
- Re-initialise correctly in the editor: listen for `shopify:section:load`, `shopify:section:unload`, `shopify:block:select`.
- Use the Section Rendering API (`?sections=` or `?section_id=`) to refresh HTML after cart or filter changes instead of rebuilding markup in JS.
- Use the Cart AJAX API (`/cart/add.js`, `/cart/change.js`, `/cart.js`) with `routes.*` URLs for locale-aware paths.

## Performance checklist

- The LCP image is not lazy-loaded and uses `fetchpriority="high"`; everything below the fold uses `loading="lazy"`.
- No render-blocking third-party scripts in `<head>`. App embeds load only where used.
- Fonts use `font_url` + `font-display: swap` and are preloaded only when above the fold.
- Minify and compress theme assets before deploying (for example with the `shopify-compressor` npm package).
- Run `shopify theme check` and fix every error before handing off.

## Accessibility checklist

- Semantic landmarks, one `<h1>` per page, logical heading order.
- All interactive elements are reachable and operable by keyboard with a visible focus style.
- Drawers and modals trap focus, close on Escape and return focus to the trigger.
- Colour contrast meets WCAG 2.2 AA in every colour scheme.
- Announce cart updates with an `aria-live` region.

## Workflow

1. `shopify theme dev --store <store>` to preview locally.
2. Make the change, keeping diffs small and following existing patterns.
3. Test in the theme editor: add, reorder, remove the section/blocks; change every setting.
4. Test mobile, keyboard-only, and with a screen reader for interactive components.
5. `shopify theme check`, then push to an unpublished theme for review.

## Output

When you finish, summarise: files changed, new settings added (with defaults), translation keys added, and anything the merchant must configure.