Shopify theme workflow and validation

Use this guide before editing and again before returning theme code. Better Design serves the implementation knowledge through get-shopify-guide; no separate agent skill is required.

Inspect before changing files

1. Confirm the theme root and its package or build commands.
2. Read the relevant layout, template, section, block, snippet, locale, and asset files before deciding ownership.
3. Check whether the task affects an unpublished duplicate. Never push or publish to the live theme without explicit approval.
4. Call get-shopify-guide with the exact task or unfamiliar API. Use a topic for a complete guide and a query for focused retrieval.
5. Preserve merchant settings, app blocks, app embeds, analytics hooks, locale keys, and existing template assignments unless the request changes them.

Match the requested scope

Classify the request before editing: repair restores intended behavior, polish refines the current layout, and redesign changes the requested layout and components. Do not report repair or polish as a completed redesign. Preserve the selected design system and its assigned icon library and variant; use exact returned icon names and source.

For a redesign, inventory the baseline sections, components, states, and mobile layout. Plan the structural changes and map each requested pattern to real selected-system components before implementation. Record missing primitives rather than silently substituting them. Keep supplied content and unrelated behavior intact.

For a page-only test, withhold installation of the current full-storefront kit. Its global CSS and default templates are not page-scoped. A draft theme alone does not isolate its control pages. Report the missing page-scoped kit before writing.

Page-only work may proceed only with genuinely isolated files: uniquely named alternate page templates, sections, assets, and the required primitives. Load scoped styles from the test section. Do not add global html, body, or shared-control overrides or load the full kit in layout/theme.liquid. Renaming a CSS file does not scope its selectors. Confirm the unpublished theme ID and preserve the original/control page, shared sections, and global assignments.

Default index, product, collection, page, and other templates, header/footer groups, and global styles belong to a full-storefront request, not a page test. Publishing or changing live/global assignments is a separate authorized action.

Use Shopify CLI for local theme work

Shopify CLI is the supported local interface for authentication, development previews, theme downloads, pushes, listing themes, opening the editor, packaging, and Theme Check. Confirm the installed version with shopify version and read command help before any state-changing operation.

Common read or local-development commands include:

shopify theme dev --store <store>
shopify theme list --store <store>
shopify theme check --path <absolute-theme-path>
shopify theme package --path <absolute-theme-path>

The theme command surface includes theme init, dev, push, pull, list, info, publish, delete, rename, duplicate, check, console, profile, open, share, package, language-server, and metafields pull. Use shopify help <command> for the installed version's flags instead of relying on memorized options.

General CLI utilities include auth logout, commands, config autocorrect on|off|status, help, search, upgrade, and version. Common flags include --path, --verbose, --no-color, and --reset, but support varies by command.

Shopify CLI may collect anonymous usage statistics. If the user wants to opt out, confirm the current Shopify CLI privacy setting or environment variable in the installed version's documentation before changing their environment.

Commands such as theme push, theme publish, theme delete, sharing a development theme, or changing store state require explicit user approval and a resolved target. Do not infer the store or theme ID.

Validate every changed surface

Run the repository's own checks first, then run Shopify Theme Check at the theme root:

shopify theme check --path <absolute-theme-path>

If the project config enables stricter checks, keep them. Do not disable a rule merely to make the run green. Fix the Liquid, schema, translation, performance, accessibility, or deprecation issue at its source.

Also verify these deterministic conditions:

• Every JSON and {% schema %} body parses.
• Liquid tags and output delimiters are balanced.
• Every render, section, asset, and locale reference resolves to a real file or key.
• Every template section type exists, and each order entry names a section instance.
• New snippets include LiquidDoc contracts.
• Product forms submit variant IDs and prices use money filters.
• Images use current image filters, dimensions, and alt text.
• Customer-facing fixed copy uses locale keys.
• The theme works without JavaScript for essential navigation, product selection, add to cart, cart editing, and checkout handoff.

Preview the unpublished theme on mobile and desktop. For full-storefront changes, test home, product, collection, cart, search, page, and 404 templates. For page-only work, test the alternate page and verify the original/control remains unchanged. Test empty, loading, unavailable, sold-out, and long-content states relevant to the change.

For a redesign, compare before/after renders with the same content and states at matching desktop and mobile widths. Show which planned structural changes and component adoption are visible. Verify icons, hierarchy, spacing, and interactions, then run the review, comprehension, and measured spacing checks. Copy or accessibility fixes, generated files, and tool calls alone are not redesign evidence. If a baseline or rendered check is unavailable, name it and report the redesign as unverified.

Resolve failures with documentation

When Theme Check names an unfamiliar object, tag, filter, schema property, or deprecation:

1. Call get-shopify-guide({ query: "<exact error and API name>" }).
2. Open the linked Shopify primary reference when the returned guide says the API is version-sensitive.
3. Fix the smallest cause.
4. Rerun Theme Check.
5. Report any remaining warning and why it cannot be resolved safely.

Do not guess at valid Liquid and do not claim validation when Theme Check did not run.

Primary Shopify sources

• Shopify CLI for themes
• Theme Check
• Theme Check performance checks
• Tools for building themes