§ 01 · theme anatomy

A Shopify theme is seven folders. Most agencies only open three.

Every Shopify theme, from Dawn to a full custom build, is the same seven-folder structure. Config controls what the merchant can edit. Layout wraps every page. Templates choose which page shell to use. Sections and blocks are the modular, merchant-editable units. Snippets are reusable fragments. Assets are compiled CSS and JavaScript. A theme development practice that does not work across all seven is customizing a surface, not engineering a storefront. Full reference in the Shopify theme architecture docs.

config/

What the merchant controls.

settings_schema.json defines every knob inside the theme editor. settings_data.json stores what the merchant picked. A custom theme stands or falls on how this schema is shaped.

layout/

The wrapper every page inherits.

theme.liquid is the chrome around every page: head, nav, footer, script loader. One file, rendered every request. Any mistake here is a mistake on every URL.

templates/

Page shells as JSON.

product.json, collection.json, page.json define which sections appear in which order. Online Store 2.0 moved these from Liquid to JSON so merchants can reorder sections without code.

sections/ & blocks/

The modular, editable layer.

Each .liquid file is a merchant-editable unit. Sections are page-level; blocks are smaller pieces inside a section. The richness of this library is the difference between a theme that ships once and a theme that keeps shipping.

snippets/

Reusable fragments.

Price blocks, icon sprites, meta tags, product cards. The snippet library is where Liquid debt accumulates fastest; copy-pasted partials across themes is the most common inherited problem we unpick on week one.

assets/

Where performance lives or dies.

Compiled CSS, JavaScript, icons, fonts. Every asset here is a page-weight line item. A good theme under-budgets this folder; a bad theme ships 400KB of JavaScript to render a product card.

§ 02 · liquid · os 2.0 · hydrogen

Three ways to render a Shopify storefront. One of them fits you.

The decision is rarely technical. It is a question of catalog size, team composition, and how much custom behavior the storefront needs that Liquid cannot express. Here is the honest decision matrix we walk every buyer through on the first call.

	Traditional Liquid	Online Store 2.0	Headless / Hydrogen
render model	server-side Liquid on Shopify	server-side Liquid + JSON templates	React on Oxygen edge
merchant control	fixed templates, limited reorder	every page shell reorderable	code-first, Sanity or Contentful for CMS
catalog ceiling	fine to 500K SKUs	fine to 500K SKUs	no practical ceiling
dev team needed	Liquid + CSS + light JS	Liquid + JSON schemas	React, TypeScript, GraphQL, CI
speed ceiling	excellent if disciplined	excellent with lean sections	best available, at engineering cost
best for	legacy themes being refactored	80% of modern custom builds	multi-brand, multi-property, app-shared code
wrong for	new merchant teams needing flexibility	brands that need non-Shopify cart logic	catalogs under 20K SKUs with a lean team

Eight of every ten custom themes we ship are OS 2.0 on Liquid. Headless is the exception we talk most brands out of.

§ 03 · section composition

A theme is composed, not written end-to-end.

Every page is a stack of sections, each one a Liquid file with its own schema, its own merchant-editable settings, its own block library. The animation below shows what a homepage looks like as it gets composed — five sections, one merchant-editable moment, fifteen seconds. Learn more about the underlying pattern in the Shopify Liquid sections documentation.

Fig. 2 · section stacking · five Liquid files, one merchant-editable moment

§ 04 · the Liquid Audit

Before we touch a line of Liquid, we score yours.

The Liquid Audit is a two-week, eight-point pre-engagement diagnostic we run on every inherited theme. No design work, no speculative rewrites. A written report that tells you where the theme is costing you revenue, where the app tax sits, and what a customization or custom build would actually change. You keep the report whether you hire us or not.

check 01 · LCP

LCP budget.

Largest Contentful Paint measured on a mid-tier Android over throttled 4G. Target under 2.5 seconds. Anything over three is costing revenue before the first scroll.

tooling: Lighthouse CI · WebPageTest

check 02 · INP

INP budget.

Interaction to Next Paint across the first ten taps. Target under 200 milliseconds. Heavy app JavaScript is the usual offender; we quantify it per app before we touch code.

tooling: CrUX · Chrome DevTools

check 03 · app tax

App weight audit.

Every installed app listed by the bytes it injects into every page. Render-blocking scripts, remote fonts, synchronous requests. The tradeoffs become decisions, not accidents.

tooling: Coverage · Script Manager

check 04 · Liquid debt

Technical debt score.

Dead partials, duplicated snippets, uncached loops, inline styles inherited from contractor sprints. Graded A to F with a ticketed remediation list.

tooling: Theme Check · Shopify CLI

check 05 · OS 2.0

OS 2.0 readiness.

Percentage of templates on JSON over Liquid. Depth of section and block use. Whether the merchant gets meaningful control in the theme editor or only surface-level toggles.

tooling: Theme Inspector · manual audit

check 06 · WCAG 2.2

Accessibility baseline.

Contrast, focus order, keyboard traversal, form labels, motion preferences, screen-reader semantics. The US ADA lawsuit floor is rising; we treat AA as a table stake, not a feature.

tooling: axe DevTools · NVDA · VoiceOver

check 07 · SEO continuity

Redirect + structured data.

Redirect coverage, canonical integrity, schema depth, hreflang, sitemap health. A theme swap with a broken redirect map can erase six months of organic in a week. We catch it before launch.

tooling: Screaming Frog · Search Console

check 08 · merchant flexibility

The editor handoff.

How much of the storefront a non-developer can edit without calling us. The measure of a well-built custom theme is how rarely it sends the merchant back to code.

tooling: section schemas · Loom handoff

Audit scope is two weeks. Deliverable is a written report plus a 90-minute walkthrough. The fee is refundable against any engagement that follows.

§ 05 · two lanes, two buyers

Theme customization and custom builds are different projects.

Most agencies blur the two because bundling them keeps the quote simple. We split them because the budgets, timelines, and deliverables are genuinely different, and the wrong lane costs you weeks. Pick the lane that matches the problem.

lane 01 · customization

Customize an existing theme.

Dawn, Horizon, Impulse, Prestige, or Broadcast already cover 70% of the storefront. The gap is four to eight specific things: a new section type, a custom product page, a Liquid refactor on the cart, an accessibility pass, a speed regression fix. Timeline three to five weeks, single delivery track.

✓Two to six new custom sections
✓Liquid debt cleanup on inherited snippets
✓Core Web Vitals remediation
✓WCAG 2.2 AA accessibility fixes
✓Documented component library handoff

for: brands on Dawn or a premium theme with specific gaps

lane 02 · custom build

Build a theme from scratch.

The design system has matured past any template. The merchandising needs richer section types than a base theme exposes. App bloat has turned a bought theme into a maintenance tax. Seven to twelve weeks, design + development tracks, section library built from the schema up.

✓Design system derived from your brand identity
✓20 to 40 custom Liquid sections and blocks
✓OS 2.0 JSON templates across every page type
✓Performance budget enforced in CI
✓90-day post-launch performance SLA

for: brands where customization would cost more than a rebuild to maintain

We recommend the smaller lane whenever the math works. Bespoke is the answer less often than the bespoke-first agencies admit.

§ 06 · the base picker

Your base theme decides your ceiling.

Five bases cover almost every customization project we see. Each has a different speed profile, a different section library depth, and a different fit for merchandise-heavy versus editorial-heavy stores. Here is how we choose.

base	speed out of box	section library	best for	wrong for
Dawn Shopify free	excellent	lean, reference-grade	new stores, design-led brands	merchandise-heavy catalogs
Horizon Shopify free	excellent	editorial + merchandising	2025 launches, content-rich brands	stores still on OS 1.0 migration
Impulse premium	good, needs pruning	heavy, campaign-led	fashion, campaign-driven DTC	simple single-SKU stores
Prestige premium	good, editorial bias	image-led, press-friendly	luxury, beauty, editorial brands	high-SKU merchandising catalogs
Broadcast premium	good, many options	kitchen-sink flexibility	merchants wanting max in-editor control	teams that want a lean codebase

We ship customization on all five. For new builds in 2026 we default to Horizon or a bespoke theme; Dawn remains the correct choice for design-led, content-lean stores.

§ 07 · the performance SLA

LCP under 2.5 seconds. In writing.

Every custom theme build ships with a published performance SLA. Mid-tier Android, throttled 4G, Shopify's own CrUX dataset as the referee. If the number lands over the target at launch, we fix it for free. Before-and-after Lighthouse numbers for every project published below.

metric	before (inherited theme)	after (DH custom build)	target
LCP	4.1 s	1.9 s	< 2.5 s
INP	340 ms	140 ms	< 200 ms
CLS	0.24	0.04	< 0.1
Lighthouse mobile	52	94	> 90
JS transfer (product page)	412 KB	108 KB	< 150 KB
time to first byte	680 ms	210 ms	< 400 ms

Fig. 3 · representative before/after from a 2025 Shopify Plus custom theme launch. Real client numbers; anonymized on request.

commit 01

Budget in CI.

Lighthouse CI runs on every pull request. A regression blocks merge. The budget is not a one-time metric, it is the build pipeline.

commit 02

CrUX as referee.

Real-world data via the Chrome User Experience Report is the number Google uses for rankings. It is the number we measure against, not synthetic runs alone.

commit 03

90-day fix window.

If LCP, INP, or CLS miss target in the first 90 days under normal traffic, we fix at no cost. In writing on every custom build statement of work.

§ 08 · WCAG 2.2 AA as a baseline

Accessibility is a table stake, not a feature.

US ADA lawsuits against Shopify stores have climbed every year since 2019. Most custom themes ship without a single screen-reader test. We ship to WCAG 2.2 AA as a baseline on every customization and every custom build, and we publish the checklist we run against.

01 · color contrast

Body text at 4.5:1 against its background, large text at 3:1, every interactive state checked against its resting state. Dark mode sweeps done alongside light mode, not after.

02 · focus order

Visible focus rings on every interactive element. Tab order follows reading order. Skip links to the main product list. No keyboard traps in mega menus or cart drawers.

03 · semantic HTML

Headings in order, landmarks named, buttons as buttons, links as links. No div-soup navigation. Every form input labeled; every icon-only control announced to screen readers.

04 · motion preferences

prefers-reduced-motion respected across every animation, parallax, autoplay, and hover transform. Motion is additive, never load-bearing for meaning or navigation.

05 · screen-reader testing

NVDA on Windows, VoiceOver on macOS and iOS, TalkBack on Android. Product page, cart, checkout, and the five highest-traffic collection pages tested manually, not only by axe or a browser plugin.

06 · forms + errors

Inline errors associated to their inputs via aria-describedby. Error summaries at the top of long forms. Required fields marked in text, not only by color.

07 · media

Every product image carries real alt text pulled from the product metafield, not a placeholder. Videos captioned. Audio transcribed. Decorative images marked aria-hidden.

08 · the audit

Pre-launch, a manual walkthrough in NVDA and VoiceOver on the product-detail, cart, and checkout flows. Blocker-level issues fail the launch gate. Written audit report delivered with the theme.

§ 09 · proof

What a Liquid-first rebuild actually changes.

A short field note from three custom theme engagements shipped in the last eighteen months. Numbers are real. Brands are named with permission; anonymized-on-request stats sit behind the benchmark table above.

noble paris

Editorial theme rebuild on Shopify Plus.

10 weeks · bespoke build

An inherited theme from a contractor sprint, running 4.1-second LCP on product pages and 340ms INP. We rebuilt from an empty theme against Horizon's schema patterns, cut the JavaScript payload by 74%, shipped 22 custom Liquid sections, and migrated every product template to OS 2.0 JSON. Lighthouse mobile landed at 94 in week one and held through six months of campaign work.

-54%

LCP

+28%

mobile CVR

22

custom sections

emani

Dawn customization + accessibility pass.

4 weeks · customization

Beauty brand on a lightly modified Dawn, healthy speed baseline, weak accessibility. We wrote six new Liquid sections for ingredient storytelling, fixed contrast and focus-order failures flagged in an axe audit, and shipped a screen-reader-tested product page. Zero performance regression, WCAG 2.2 AA across product-detail and checkout. Handoff kit included a training session for the in-house marketer.

6

new sections

0

AA failures

-12%

bounce rate

big game sports

Impulse speed pass + app tax cleanup.

3 weeks · customization

Shopify store on Impulse, 14 apps installed, LCP at 3.8 seconds, Lighthouse mobile at 44. We audited every app by injected weight, deferred four, replaced two with native sections, and removed three unused ones. No redesign, no section changes. Three weeks of pure app tax and Liquid debt work. Core Web Vitals moved from red to green across product and collection templates.

3.8 → 1.8

LCP seconds

44 → 91

Lighthouse

9

apps removed/deferred

§ 10 · the fit check

We turn down theme projects more often than we take them.

Theme work done on the wrong brief harms both sides. A custom build for a business that needed a two-week customization costs eight weeks of frustration. Here is the honest filter we run on every intro call.

we're right for you if

✓Running Shopify or Shopify Plus with a named theme base
✓Measurable goal for the rebuild (speed, accessibility, section depth, design system)
✓Willing to write real alt text on every product image
✓Ready to prune app bloat, not only add custom code on top
✓A single decision-maker available for weekly theme reviews
✓Budget sized to scope rather than a fixed cap

we're wrong for you if

×Looking for a clone of another brand's storefront
×Need a page-builder app theme like PageFly or Shogun as the editing layer
×Expecting a full custom build in under four weeks
×Planning to keep a dozen apps injecting scripts on every page
×Still on BigCommerce, Magento, or WooCommerce with no migration plan
×Treating accessibility as a launch blocker to remove later

what we commit

You own the theme code on day one and on exit. Private GitHub repository under your organization. Documented component library, Loom walkthrough, and a 30-day support tail at close. If we are not the right partner, you should be able to leave cleanly; the theme is yours, not ours.

§ 11 · four shapes of theme work

Four shapes of engagement.

Pick the shape that matches the moment. We confirm fit on the intro call and send a scoped quote within 48 hours. Scope moves the price, not the conversation.

diagnose

Liquid Audit

2 weeks

Eight-point pre-engagement diagnostic: LCP, INP, app tax, Liquid debt, OS 2.0 readiness, WCAG baseline, SEO continuity, merchant flexibility. Written report plus walkthrough. Refundable against any project that follows.

for · brands scoping a rebuild

customize

Customization project

3–5 weeks

Scoped work on an existing theme base. Two to six new custom sections, Liquid debt cleanup, speed work, accessibility fixes, and a documented handoff kit. Single delivery track.

for · gaps in a working theme

most picked

build

Custom theme build

7–12 weeks

Bespoke theme from an empty repository. Design system, 20 to 40 custom Liquid sections, OS 2.0 JSON templates, performance budget in CI, WCAG 2.2 AA baseline, 90-day SLA.

for · brands past a bought theme's ceiling

retain

Theme retainer

ongoing

Block-of-hours or fixed-monthly retainer. Seasonal sections, Liquid fixes, app integration cleanup, performance monitoring, editor-side training. The most common shape after a custom build ships.

for · in-life theme ownership

Quotes sent within 48 hours of an intro call. No proprietary tooling, no licensing fees, no code held hostage on exit.

§ 12 · questions

Eight answers.

What is Shopify theme development?

Shopify theme development is the craft of building or editing the code that renders a Shopify storefront. A theme is a set of Liquid templates, JSON section schemas, CSS, and JavaScript organized into seven folders (config, layout, templates, sections, blocks, snippets, assets). Development ranges from light customization of an existing theme like Dawn or Prestige, through mid-scope section and Liquid work, up to a full bespoke theme built from an empty repository. Good theme development ships measurable Core Web Vitals, WCAG 2.2 AA accessibility, and theme editor control the merchant can actually use.

Custom Shopify theme vs customizing a Dawn-based theme — which do I need?

Start with a theme customization project if Dawn or a premium theme already covers 70% of your storefront and the gaps are specific (custom product pages, a new section library, a speed regression, an accessibility fix). A full custom theme build is right when the design system has matured past any template, when the merchandising needs richer section types than the base theme exposes, or when app bloat has turned a bought theme into a maintenance tax. We recommend the smaller lane whenever the math works; we build bespoke only when customization would cost more to maintain.

What is Shopify Liquid and does my team need to learn it?

Liquid is Shopify's open-source templating language. It is the syntax that renders product data, collection logic, cart state, and merchant settings into HTML at request time. Your internal team does not need to write Liquid to run the store day-to-day; the theme editor exposes merchant-editable controls via section schemas and block settings. Teams touching code for campaigns, new sections, or app integration will write Liquid. We hand off every theme with a documented component library and a Loom walkthrough so in-house developers can extend it without our involvement.

How long does a custom Shopify theme take to build?

A theme customization project runs three to five weeks for most scopes. A custom theme built from scratch runs seven to twelve weeks, depending on section library depth, animation ambition, and the number of page templates in play. The Liquid Audit adds two weeks before code and is refundable against any engagement that follows. Rush work is possible but we refuse to compress quality assurance and accessibility testing; the timeline moves, not the standard.

Can a custom theme improve Core Web Vitals and SEO?

Yes, and it should be the primary reason a brand commissions one. A well-built custom theme ships with an LCP under 2.5 seconds on mid-tier mobile over throttled 4G, an INP under 200 milliseconds, and a CLS under 0.1. We publish before-and-after Lighthouse numbers on every launch. SEO gains come from structured data coverage, canonical integrity, hreflang for international stores, and the speed uplift itself; Google confirmed Core Web Vitals as a ranking input in 2021 and enforcement has tightened every year since.

Will a custom theme break when Shopify updates the platform or when I install new apps?

A theme built against Shopify's current API contract does not break when Shopify ships platform updates; the Liquid objects, metafield structure, and section schemas are stable interfaces that the platform versions carefully. App installs are the more common cause of regressions because some apps inject scripts globally rather than scoping them to templates. Our theme builds route third-party app code through a script manager so we can defer, scope, or remove injections without editing app code. In-life retainers cover app installs, platform bumps, and seasonal campaign work.

Do you support headless Shopify with Hydrogen, or only traditional Liquid themes?

Both, and we have an opinion about which fits which brand. Liquid themes win for most catalogs under fifty thousand SKUs, where the cost of a headless rebuild is rarely justified by the marginal speed gain. Hydrogen on Oxygen wins for brands that need deep component reuse across multiple properties, custom cart logic that Liquid cannot express cleanly, or a storefront that shares a codebase with a mobile app. We will talk you out of a headless rebuild more often than into one.

What happens on day one and on exit — who owns the theme code?

You do. The theme lives in your Shopify store and a private GitHub repository under your organization from day one. Every Liquid file, every section schema, every asset, every JSON template is yours. On exit, we transfer full repository ownership, hand off a written component library, record a Loom walkthrough for your internal team, and close the engagement with a 30-day support tail for any questions. We do not gate access to force retention; if we are the right partner, you will renew because the work is good, not because the code is hostage.

Start with a Liquid Audit.

Two weeks, eight-point scorecard, written report. You leave knowing exactly what customization or a custom build would change. We follow up with a scoped quote within 48 hours.

Book a 30-minute theme audit See Shopify development

related services