Shopify Theme Harness

An installable CLI that overlays an AI-native workflow onto a real Shopify theme project, then drives an agent to restore Figma designs one section at a time.

This repo is not a finished theme. It is a toolkit you install into a theme project; the agent then reads Figma, writes real theme code section by section, and verifies each section against its Figma measurements.

Architecture in plain language: docs/architecture-overview.md. Step-by-step developer flow and prompt templates: docs/ai/figma-agent-prompts.md.

Install

npm install -D shopify-theme-harness
npx shopify-theme-harness init .

init copies a fixed set of harness files (skills, scripts, contracts, configs, Kik scaffold) into the project and records what it wrote in .shopify-theme-harness/scaffold.json so a later upgrade won't clobber your edits.

By default, init also guides you through the required Shopify Admin token setup. It can read an existing shopify.theme.toml, ask for a store domain, write [environments.this].store when needed, run shopify store auth, and materialize the ignored server token file at harness/config/shopify-admin.local.json. Use --no-auth-token only when you intentionally want to install the harness without authorizing the store yet.

Local development against this repo:

npm install && npm link
shopify-theme-harness --help

The workflow

The agent never generates a whole page at once. The loop is:

1. Initialize — the agent reads desktop + mobile Figma links via Figma MCP and writes a thin figma/<page-key>/source-manifest.json (a page "table of contents": section order, ids, and which skill implements each). Uses skills/theme/workflows/initialize-page-from-figma/SKILL.md.
2. Implement, one section at a time — for each section the agent measures Figma, writes the section into the real theme files, and authors agent/sections/<page>.<section>.task.json + agent/results/<page>.<section>.result.json. Static vs. data-backed routing comes from the manifest's section.skillRouting.
3. Verify each section — make verify-section-preview-iterate for fast feedback while implementing, then make verify-section-preview once for acceptance. Each completed section keeps its own preview template (templates/index.kik-section-<page>-<section>.json).

Acceptance is section-scoped — it proves the section mounts, its measured regions land within tolerance of the Figma geometry, and the rendered structure matches coarsely. It is deliberately not pixel-1:1; the developer reviews the screenshots for the last mile. See docs/architecture-overview.md §4 for what's compared and why.

Section work is driven by machine-readable artifacts at the project root (agent/sections/*.task.json, agent/results/*.result.json) — agent-authored, not generated by any compiler. They are the stable file-based handoff surface; the real theme files stay project-owned.

Kik baseline

For projects on the Kik baseline:

make bootstrap-kik-theme STORE=<store-domain> [VARIABLES_TABLE_HTML=<path>] [STOREFRONT_PASSWORD=<password>]
make sync-kik-tokens            # after maintaining design-tokens/kik.tokens.css

bootstrap-kik-theme is one-time setup (Tailwind/Vite config, Kik asset entrypoints, browser-verification config, preview scaffold). sync-kik-tokens regenerates src/input.css and harness/generated/kik.tokens.json from design-tokens/kik.tokens.css. src/input.css builds to assets/kik-theme.css; run pnpm build before judging a section preview.

Static assets & the tool server

When a section needs durable image/icon files, a developer (not the agent) runs the Figma REST extractor, which writes design-assets/manifest.json for the agent to consume:

make figma-extract-assets PAGE=<page-key>

Section agents can also call an optional Shopify tool server for shop context and image upload. Configure it in harness/config/agent-tools.json (copy from harness/config/agent-tools.example.json); the server itself lives under server/. Agents authenticate to the tool server with the bearer token from the env var named by toolServer.auth.tokenEnv.

For customer theme projects, the server can use the local Shopify CLI-derived Admin token file created during init instead of a public app install. To rotate or create it later, run:

npx shopify-theme-harness auth-token --project-root .

The command reads or helps write shopify.theme.toml, runs shopify store auth for the narrow Admin scopes needed by the harness, and writes harness/config/shopify-admin.local.json. That file is added to .gitignore; it stores the CLI access token, refresh token, and expiry for the server only. Start the tool server with SHOPIFY_LOCAL_TOKEN_PATH=/absolute/path/to/harness/config/shopify-admin.local.json. When the access token is near expiry, the server refreshes it and rewrites the same ignored file. If refresh fails, rerun shopify-theme-harness auth-token.

Commands

make inspect-bootstrap                 # environment readiness gate
make inspect-project | inspect-harness # status / overlay + contract inspection
make verify-harness                    # overlay + contract sanity gate
make create-section-preview  PAGE=<k> SECTION=<s>
make verify-section-preview  PAGE=<k> SECTION=<s>   # acceptance
make verify-section-preview-iterate PAGE=<k> SECTION=<s>   # fast feedback
make verify-section-preview-offline PAGE=<k> SECTION=<s>   # offline triage
make notes-init PAGE=<k>               # bootstrap human-override notes
make figma-extract-assets PAGE=<k>     # developer-run asset extraction
make auth-token                         # materialize ignored Shopify Admin token file
make storefront-dev-start | -stop | -status
make bootstrap-kik-theme STORE=<domain>
make sync-kik-tokens [TOKENS=<path>]
make test

CLI commands: init, upgrade, status, inspect-harness, verify-harness, verify-section-preview-offline, notes-init, auth-token, bootstrap-kik-theme, sync-kik-tokens (all --project-root <dir> where applicable). init installs the harness layer and defaults into Admin token setup; pass --no-auth-token to skip that setup.

Upgrade safety

shopify-theme-harness upgrade refreshes harness-owned files that still match their last-installed hash, and skips any you've locally modified (reported in skippedModifiedFiles). Project-owned theme files are never touched. Skipped files need manual reconciliation if you want both your edit and the newer scaffold change.

Publish

The repo root is the npm package.

• npm run package:smoke — verify the packed tarball installs and init runs
• npm run release:check-versions — verify version state
• npm run release:publish-harness:dry-run / release:tag:dry-run — preview publish/tag

Details: scripts/release/README.md. Maintainer checklist: docs/release-checklist.md.

Where things live

Read first: AGENTS.md → docs/ai/README.md → docs/ai/agent-workflow.md → docs/ai/repo-map.md → docs/ai/figma-agent-prompts.md.

Skills:

• skills/theme/workflows/initialize-page-from-figma — Figma links → source-manifest.json
• skills/theme/workflows/implement-section-from-figma — implement one section
• skills/theme/workflows/implement-shopify-data-section-from-figma — product/collection/article/metaobject sections
• skills/theme/workflows/verify-section-preview — section preview evidence
• skills/theme/workflows/kik-shopify-theme-init — the Kik baseline
• skills/theme/project-conventions — local conventions; skills/theme/patterns/swiper-carousel for carousels

The repo ships no sample Figma input — the harness scans any figma/<page-key>/source-manifest.json matching the contract.