How We Use AI to Maintain Our Themes (Practitioner Log)

We maintain a portfolio of Shopify OS 2.0 themes and companion Figma UI kits, and AI has become a real part of how we keep both in sync without a maintenance team the size of a platform vendor's. The short version: AI does not design or ship our themes unsupervised. It reviews diffs, drafts changelogs, flags visual and accessibility regressions, and cross-checks that a Figma component and its Shopify section still describe the same thing after either one changes. A person signs off on every release. This post is a practitioner log of that workflow, including where it broke.

Why Theme Maintenance Is Harder Than Theme Building

Building a theme once is the easy part. Keeping five or six themes current — through Shopify platform updates, Liquid deprecations, new section-schema conventions, browser rendering changes, and the slow drift between a Figma source file and the code that was supposed to match it — is where most small theme shops quietly fall behind. Shopify ships changes to the Online Store 2.0 framework on its own schedule. A schema attribute that worked last quarter gets a deprecation notice. A section block that rendered fine in one theme editor version renders with a layout shift in the next. None of this is dramatic on its own, but across a multi-theme, multi-kit portfolio it adds up to a constant low hum of small regressions that are easy to miss and expensive to find manually.

The other half of the problem is specific to selling both a Figma kit and a Shopify theme for the same product line, like our Optics eyewear kit and its Shopify theme counterpart. Those two artifacts are maintained in different tools, by people (and now AI assistants) working on different timelines, and they need to keep telling the truth about each other. If the Shopify theme's product gallery gets a new zoom interaction, the Figma kit's product-page frame should reflect that, or a buyer who purchases the kit expecting parity with the live theme gets a bait-and-switch experience. This is the maintenance problem AI has actually helped us with the most, and it is the one most write-ups about "AI and design tools" skip past in favor of generation demos.

The Workflow, Stage by Stage

1. Diff-first, not prompt-first

Every maintenance pass starts from a real diff — a Liquid section change, a schema.json edit, a token update in a Figma library — never from an open-ended prompt like "improve this theme." Open-ended prompts are where AI-assisted maintenance goes wrong: the model has no anchor for what "improve" means, so it invents scope. Anchoring to an actual diff keeps the review bounded to what changed and why, which is also how we'd want a human reviewer to work.

2. Automated checks run before any model sees the diff

Deterministic tooling goes first: Liquid and JSON linting, a schema-name collision check (the same discipline we apply to backend migrations — never trust a tool's summary output over the actual state), theme-check for Shopify-specific deprecations, and a visual diff pass across a fixed set of breakpoints and sample products. AI is expensive to run and imprecise compared to a linter; anything a deterministic tool can catch, it should catch, so the AI review budget is spent on judgment calls, not syntax.

3. AI reviews the diff for behavioral and cross-artifact drift

This is the stage that actually earns its keep. We ask a model to review a theme diff against three questions: does this change alter behavior a merchant would notice (not just code shape), does it introduce an accessibility regression (contrast, focus order, alt-text handling, keyboard traps in a new interaction), and does it leave the paired Figma kit out of date. The model is given the relevant Figma component's exported spec (spacing, states, copy) alongside the Liquid section it corresponds to, and asked to flag mismatches in plain language rather than silently "fixing" either side. It writes a short structured note — what changed, what to check, what to update — that a maintainer reads before touching anything.

4. A human makes every merge and release decision

The model's output is a review, not an approval. Every release still goes through a person who reads the AI's notes, checks the visual diffs, and decides what ships. We treat AI review the way we'd treat a very fast, very literal junior reviewer: good at noticing that something changed, not authoritative on whether the change is acceptable. This distinction matters enough that it's worth restating: nothing in this workflow auto-merges based on a model's judgment alone.

5. Changelog and migration-note drafting

Once a change is approved, drafting the customer-facing changelog entry and any "if you're on version X, do Y" migration note is a genuinely good AI task — it's summarization grounded in a diff a human already reviewed, with low cost if the first draft needs editing. We still edit every entry; a changelog that oversells or undersells a change erodes trust with people who bought a theme expecting stability.

Where This Broke, and What We Changed

Two failures were worth internalizing. First, early on we let a model "fix" a schema attribute it flagged as deprecated without cross-referencing which Shopify theme-editor versions actually dropped support for it — the fix was premature and briefly broke the section on stores still on an older editor path. The lesson was procedural: any AI-suggested fix to platform-facing code needs a citation to the actual deprecation notice or changelog, not a plausible-sounding guess, before a human accepts it. We now require the model to quote its source or say it isn't sure, and "not sure" gets escalated rather than merged.

Second, cross-checking Figma against Shopify code sounds simple until you notice the two don't share a canonical name for the same thing — a Figma component called "Product Gallery — Zoom" might correspond to a Liquid section called product-media-gallery. Without an explicit mapping table, the model would occasionally compare the wrong pair of artifacts and confidently report they matched, which is worse than reporting nothing. We fixed this by maintaining a small, explicit mapping file (kit component name to theme section name) as ground truth the model is required to consult rather than infer, which is the same principle as pinning a source of truth before automating around any tool.

What We Deliberately Don't Automate

• Design decisions. Whether a new interaction pattern belongs in a theme is a product call, not a linting task. AI can describe the tradeoff; it doesn't get a vote.
• Release timing. Merchants running live stores don't want surprise updates. A human decides when a change goes out and how it's communicated, independent of how ready the code looks.
• Anything touching checkout or payment-adjacent code. The review bar there is stricter than general theme maintenance, and AI-suggested changes in that surface get the slowest, most manual review in the whole pipeline.
• Final accessibility sign-off. Automated contrast and focus-order checks catch a lot, but a manual pass with a screen reader on the actual rendered page still catches things static analysis misses.

Why We're Writing This Publicly

We sell Figma UI kits and Shopify themes today, and we're building toward more code-native, AI-assisted commerce tooling — the kind of thing where a well-structured design system and a disciplined maintenance workflow become the actual product, not just internal process. Headless commerce, component libraries, and AI-assisted design-to-code tooling are all heading toward a world where the artifact that matters is a well-maintained system, not a one-time delivery. The practices in this log — diff-first review, deterministic checks before AI checks, explicit ground-truth mappings instead of model guesses, and a human gate on every release — are the parts of that world we've already had to get right for our current product line, and they're the parts we'd recommend to any team putting AI into a maintenance loop rather than a generation demo.

If you're evaluating a Figma-to-Shopify workflow of your own, our Figma kits and Shopify themes are built with this same source-of-truth discipline between design and code, which is part of why we can maintain them this way. And if this kind of practitioner detail is useful, we write more of it on the Polo Themes blog.

Frequently Asked Questions

Does AI write your Shopify theme code?

AI assists with drafting and review, but it does not ship unreviewed code. Every diff that touches a live theme goes through deterministic checks first, then an AI review pass focused on behavior and cross-artifact drift, then a human who makes the actual merge and release decision.

How do you keep a Figma kit in sync with its Shopify theme?

We maintain an explicit mapping between Figma component names and Shopify section names as ground truth, rather than letting a model infer the correspondence. When either side changes, the mapping is what a reviewer (human or AI) checks against, which avoids the false-confidence failure mode of comparing the wrong pair of artifacts.

What's the biggest risk of using AI for code maintenance?

Confident, ungrounded fixes. A model that "fixes" a deprecated attribute without citing the actual deprecation notice can introduce a regression that looks like an improvement. Requiring a cited source (or an explicit "not sure") before accepting any AI-suggested fix is the single highest-leverage guardrail we've added.

Will this workflow extend to headless or Next.js–based themes?

The same principles — diff-first review, deterministic checks before AI judgment, explicit ground truth over model inference, human sign-off on release — apply regardless of stack. We don't currently sell a Next.js starter or headless product, but the maintenance discipline described here is exactly what we'd carry into that direction.