folder 01
/templates
JSON files defining page structure for product, collection, page, blog, article, customer, search, cart, 404, gift_card, password.
§
§ · journal
Custom Shopify theme development.
A working developer's guide for 2026 - Liquid, Online Store 2.0, sections + blocks, performance budgets, and the build-vs-customize-vs-buy decision tree we run with clients.
§ 01 · TL;DR
Liquid + JSON + JS. Six weeks. A real theme.
Custom Shopify theme development in 2026 means writing Liquid templates, JSON section schemas, JavaScript modules, and CSS against Shopify's Online Store 2.0 architecture - then connecting that codebase to a Shopify store via the Shopify CLI or a GitHub integration. The work involves information architecture, Liquid rendering against the product and cart object models, JSON-driven sections so merchandisers can rearrange the page without engineering help, performance budgets (LCP under 2.5 seconds, INP under 200 milliseconds, CLS under 0.1), accessibility compliance to WCAG 2.1 AA, and deployment workflows. A clean custom-theme build runs 6-10 weeks at $15K-$40K for a mid-market scope; light customization of an existing theme runs 2-4 weeks at $5K-$15K. Three honest paths exist: build custom, customize existing, or buy a premium theme. Pick by reading your brief, your timeline, and your maintenance budget against the decision tree below. We're a Premier Shopify Plus partner with 2,000-plus stores shipped since 2017 across 50-plus markets; Trustpilot 4.9; New York and Delhi HQ.
§ 02 · what theme development is
Templates. Sections. Blocks. A theme is a folder.
A Shopify theme is a folder of files. The folder lives in the merchant's Shopify admin under Online Store > Themes; developers work on a local mirror via the Shopify CLI, push changes to a development theme on the live store, and then publish to production once approved. Each theme has a strict directory structure that Shopify's theme documentation defines.
The file types matter. Liquid (.liquid) files are the rendering layer - Shopify's templating language that turns objects (product, collection, cart, customer) into HTML. JSON (.json) files describe section schemas - the configuration knobs that show up in the theme editor for merchandisers. JavaScript (.js) and CSS (.css) handle interactivity and styling. Locale files (.json under /locales) handle translation strings. Asset files (images, fonts, icons) live under /assets. The full theme architecture reference is the source of truth for what goes where.
Online Store 2.0 - Shopify's theme architecture since 2021 - introduced four new patterns that shape every modern theme. One: JSON templates instead of Liquid templates for the page-level structure. Two: sections everywhere, meaning sections can be added to product, collection, cart, blog, and page templates rather than just the homepage. Three: app blocks, which let third-party apps inject UI into theme sections without theme code modification. Four: theme settings expressed as JSON schema so merchandisers can configure colors, typography, and section content from the theme editor. All five free Shopify themes (Dawn, Studio, Sense, Refresh, Spotlight) are 2.0; Dawn's GitHub repo is the reference implementation.
folder 02
/sections
Liquid + JSON section files. Each section is a self-contained UI unit (hero, product card grid, cart drawer) with editor schema.
folder 03
/snippets
Reusable Liquid partials. Things like price-display, image-card, or icon imports that get included across multiple sections.
folder 04
/assets, /config, /layout, /locales
Static assets, theme settings JSON, theme.liquid wrapper, translation strings. The supporting cast every theme needs.
§ 03 · build vs customize vs buy
Three paths. One brief. Pick honestly.
The wrong path costs $25K and three months. Read the criteria below before scoping anything.
path 01
Buy a premium theme
Cost: $150-$350 one-time
Time: 1-2 weeks setup
Best for: first-time merchants, tight budgets, brands with a designer-merchandiser who customizes via theme editor.
Premium themes from the Shopify Theme Store (Impulse, Prestige, Empire, Ella, Be Yours) ship with 50-100 sections, multiple homepage demos, and merchandising flexibility built in. The catch: they are designed to look different to many brands at once, which means yours will look like several others. Acceptable for sub-$50K/yr revenue; risky if brand differentiation matters.
path 02
Customize an existing theme
Cost: $5K-$25K
Time: 2-6 weeks
Best for: the 80/20 case - the theme has 80 percent of what you need and you customize the missing 20 percent.
Start from Dawn or a premium theme. Add a custom hero section, override the product page layout, swap typography, build 2-4 brand-specific sections, and tighten performance. The right answer for most $1M-$10M DTC brands. Warning: if customization runs past $25K, you should be in path 03 instead.
path 03
Build a custom theme
Cost: $25K-$80K
Time: 6-12 weeks
Best for: brands where the visual brief cannot be matched in any existing theme. Most $5M-plus DTC and B2B brands.
Full custom Liquid theme against a Figma design. New section library, custom JavaScript modules, brand-specific commerce mechanics (subscription UI, bundle builder, B2B portal). Highest control, highest cost, highest brand specificity. The right answer when brand differentiation drives conversion - which it does past a certain revenue tier.
§ 04 · the liquid template language
Tags, filters, objects. A small language with a long shadow.
Liquid is the templating language Shopify uses to render dynamic data into HTML. It was open-sourced by Shopify in 2006 and has been refined steadily since; the full Liquid reference on shopify.dev is the canonical source. Liquid has three primary constructs: tags, filters, and objects.
Objects are the data Shopify passes into a theme. The big ones are product, collection, cart, customer, shop, and request. Each object has properties (product.title, cart.items, customer.first_name) that you reference inside Liquid. Object access uses dot notation or bracket notation, and Shopify auto-escapes string output by default which removes a class of XSS bugs you would otherwise have to handle manually.
Tags are control-flow primitives: {% if %}, {% for %}, {% case %}, {% assign %}, {% capture %}, {% include %}, {% render %}, {% section %}. Use {% render %} over the older {% include %} for snippet inclusion - it scopes variables cleanly and is the Shopify-recommended pattern.
Filters transform output: {{ product.price | money }}, {{ image | image_url: width: 800 }}, {{ 'now' | date: '%Y-%m-%d' }}. Filters chain with the pipe character, run left-to-right, and produce the final HTML output. The image_url filter combined with image_tag is how modern Shopify themes serve responsive images at the right size for the right viewport.
worked example · product card
{% for product in collection.products limit: 12 %}
<article class="product-card">
<a href="{{ product.url }}">
{{ product.featured_image | image_url: width: 600 | image_tag: loading: 'lazy' }}
<h3>{{ product.title }}</h3>
<p>{{ product.price | money }}</p>
</a>
</article>
{% endfor %}Twelve lines render an entire product grid. Liquid auto-handles the loop boundary, escapes strings, generates responsive image markup, and formats currency to the store's locale. The same logic in raw JavaScript against the Storefront API is roughly 60 lines.
§ 05 · sections, blocks, templates
Sections compose templates. Blocks compose sections.
Sections are the unit of composition in Online Store 2.0. A section is a Liquid file with an embedded JSON schema that declares its settings (color, typography, content fields) and the blocks it accepts. Merchandisers add, remove, and reorder sections in the theme editor without touching code. A typical custom theme has 30-60 sections covering hero, product cards, testimonial blocks, image-with-text, video, FAQ, newsletter, marquee, before-and-after, ingredient lists, and so on.
Blocks are the unit of composition inside sections. A "Featured Collection" section accepts product blocks; a "FAQ" section accepts question blocks; a "Testimonials" section accepts review blocks. Each block has its own schema and merchandiser can add or remove individual blocks within a section. App blocks - introduced in Online Store 2.0 - let third-party apps inject blocks into your sections, so a reviews app or a subscription app can appear inline without theme-code modification.
Templates are the page-level structure. Each template type (product, collection, page, blog, article, customer/account, search, cart, gift_card, password, 404) can have a .json default version plus alternate .json templates the merchandiser assigns to specific products or collections. Templates are JSON arrays of section IDs - the actual rendering happens inside each section's Liquid file.
The mental model: templates choose which sections appear, sections render content from their blocks, blocks store the merchandiser's data. The theme editor reads all three layers and writes back to the JSON files when the merchandiser saves changes. The dev-time round-trip is JSON-templates <-> section-Liquid <-> block-data, with Liquid as the rendering bridge.
Practical implication for theme developers: design sections as small, composable units rather than monolithic page-builders. A "hero with image" section, an "image-with-text" section, and a "rich text" section that compose into a homepage is a stronger design than a single "homepage layout" section that bundles everything. The first pattern is what Dawn does; the second is what most premium themes did before 2.0 and is the reason vintage themes feel cramped to merchandisers in 2026.
§ 06 · performance budgets
LCP 2.5. INP 200. CLS 0.1. Field data, 75th percentile.
Custom Shopify themes ship with one performance bar: pass Core Web Vitals at the 75th percentile of real-user field data. The current thresholds: Largest Contentful Paint under 2.5 seconds, Interaction to Next Paint under 200 milliseconds, Cumulative Layout Shift under 0.1. Themes that miss these thresholds rank lower in Google search and convert lower in checkout - the relationship is well-documented in Shopify's own internal data.
Image strategy. Use Shopify's image_url filter to serve responsive images at exact widths. Add loading="lazy" to images below the fold. Add explicit width and height attributes to prevent layout shift. For above-the-fold hero images, preload via <link rel="preload"> in the layout file. Most LCP failures on Shopify themes are unsized hero images.
JavaScript strategy. Defer non-critical JS with defer attributes. Avoid render-blocking JavaScript above the fold. Modern Shopify themes use ES modules with import-on-interaction patterns - cart drawer code only loads when the user clicks the cart, not on initial page load. Dawn's source code is the reference for this pattern.
CSS strategy. Inline critical CSS for above-the-fold content, defer the rest. Most themes ship a single global stylesheet - acceptable up to about 100KB compressed. Past that, split per-section stylesheets and load each section's CSS only when the section renders. The 100KB rule is rough but useful as a budget anchor.
Font strategy. Subset custom fonts to only the characters and weights you need - usually 30-60KB per family per weight. Use font-display: swap to avoid invisible text during font load. Self-host fonts when possible; third-party font services add a DNS lookup and a TLS handshake to every page load.
Dawn ships with a 95-plus Lighthouse performance score on a fresh install precisely because Shopify's theme team wrote it as the reference implementation. Custom themes that drop below 80 on Lighthouse usually have an unsized hero image, an unminified JavaScript bundle, or a synchronous third-party script in the head.
§ 07 · a11y, responsive, i18n
WCAG 2.1 AA. Mobile-first. hreflang for every region.
Accessibility. Custom themes must pass WCAG 2.1 AA at minimum. The big-six checks: color contrast 4.5:1 on body text and 3:1 on large text, keyboard navigation through every interactive control, alt text on every meaningful image, ARIA labels on every icon-only button, focus rings visible on every focusable element, and form labels associated with their inputs. Run an automated pass with axe DevTools or the Shopify Theme Inspector, then run a manual keyboard-only test and a screen-reader test (VoiceOver on Mac, NVDA on Windows).
Responsive design. Mobile-first is non-negotiable. Roughly 70-80 percent of Shopify storefront traffic is mobile in 2026. Design at 375px width first, then scale up to 768px (tablet) and 1280px (desktop). Use CSS Grid and Flexbox for layout, not floats. Avoid fixed pixel widths on containers; use max-width with auto margins. Test on real devices, not just Chrome devtools - the difference between iOS Safari and Chrome desktop on touch interactions is meaningful.
Internationalization. Shopify supports multi-language storefronts via the Shopify Markets feature plus theme locale files. Each locale gets a JSON file under /locales/ (en.default.json, fr.json, de.json) with translation strings. The theme references those strings via the {{ 'cart.add_to_cart' | t }} filter pattern. Multi-region storefronts also need hreflang tags on every page to tell Google which version serves which locale - typically en-US, en-GB, en-IN, and an x-default fallback. The hreflang tags go in theme.liquid using Shopify's localization objects.
§ 08 · the DH custom theme workflow
Discover. Design. Build. Launch. Optimize.
Six weeks for a mid-market scope. The week-by-week cadence below is what we run with clients; agencies that cannot describe their cadence at this level are usually winging it.
Week 1 - Discover. Information architecture workshop, KPI definition, integration audit, content inventory, performance baseline. Output: a written scope document with named team, weekly cadence, and acceptance criteria per phase.
Weeks 2-3 - Design. Figma file with home, product, collection, cart, account, blog, article, page, and search layouts at mobile and desktop breakpoints. Section library defined with 25-40 reusable sections. Design tokens (color, typography, spacing) documented.
Weeks 4-6 - Build. Liquid theme assembled against the Figma file using the Shopify CLI. Sections written first, templates composed from sections, custom JavaScript modules added for cart drawer, mini-cart, and any custom interactions. Version-controlled in GitHub with branch-per-feature; Vercel preview deploys for stakeholder review.
Week 7 - QA. Theme check (Shopify's official linter), accessibility audit (axe DevTools + manual screen-reader pass), Core Web Vitals audit (Lighthouse + PageSpeed Insights field data once enough traffic exists), cross-browser test (Chrome, Safari, Firefox, Edge), cross-device test (iOS Safari, Android Chrome on real hardware). Sign-off checklist with named approver per category.
Week 8 - Launch. Final content load, redirect map application if migrating from another platform, payment-gateway switchover, DNS cutover, smoke test, monitoring stand-up. Shopify support on standby for any platform-side issues.
Weeks 9-12 - Optimize. Post-launch retainer: A/B testing infrastructure stand-up, conversion-rate optimization sprints, bug fixes, feature releases. Most engagements transition into an ongoing engineering retainer at this point - $5K-$25K/month depending on scope.
The named tools per phase are non-negotiable. Shopify CLI for local development. Theme Check for linting. GitHub for version control. Vercel preview deploys for stakeholder review. Linear for issue tracking. The shopify.dev documentation as the reference for every Liquid object, JSON schema field, and CLI command.
§ 09 · questions buyers ask
Six honest answers.
What does custom Shopify theme development actually involve?
Custom Shopify theme development means writing Liquid templates, JSON section schemas, JavaScript, and CSS against Shopify's theme architecture - then connecting that codebase to a Shopify store via the Shopify CLI or GitHub integration. The work spans information architecture (which templates, sections, and blocks the store needs), Liquid rendering of product, collection, cart, and checkout-extensions data, JSON section configuration so merchandisers can re-arrange the page in the theme editor without engineering involvement, performance budgets (deferred JavaScript, lazy-loaded images, font subsetting), accessibility compliance, internationalization with hreflang and currency switching, and the deployment workflow against Shopify's theme store or the merchant's own GitHub repo. A real custom theme is roughly 8,000-25,000 lines of code across 80-200 files. It is not the same as theme settings inside a free theme.
How long does custom Shopify theme development take?
A discovery-design-build-launch cadence for a custom Shopify theme on a single-region store with 5-15 templates runs 6-10 weeks end to end. Roughly: 1 week discovery and IA, 2 weeks design in Figma, 3-5 weeks engineering against the design, 1 week QA and accessibility audit, 1 week launch and post-launch tuning. Custom themes that require multi-region storefronts, B2B catalog views, or extensive third-party integrations push the timeline to 10-16 weeks. Headless storefronts on Hydrogen or Next.js with the Storefront API are a separate workflow that typically runs 16-26 weeks. The week-by-week cadence matters more than the headline number; ask any agency on your shortlist for the full week-by-week breakdown of their build schedule.
How much does custom Shopify theme development cost?
Custom Shopify theme development in 2026 runs $5,000 to $80,000 depending on scope. Light customization of an existing free or paid theme: $5,000-$15,000. Mid-market custom theme on a single-region Shopify store with subscription, bundles, or basic B2B: $15,000-$40,000. Enterprise custom theme on Shopify Plus with multi-region, advanced B2B, custom checkout extensibility, or headless components: $40,000-$80,000. Headless Hydrogen or Next.js storefront on top of Shopify Plus runs $80,000-$300,000 separately. These are honest mid-points; freelancer collectives quote 30-50 percent lower with higher variance, while enterprise systems integrators quote 2-3x higher with more political overhead. Most healthy DTC and B2B brands at $5M-$100M revenue land in the $25K-$60K band.
Can I build a Shopify theme without coding?
Partly. Online Store 2.0 themes expose enough customization through the theme editor that a non-developer can rearrange sections, swap colors, change typography, edit content, and reorder blocks without touching code. That is not the same as building a custom theme. Building a theme - new layouts, new sections, custom Liquid logic, custom JavaScript behavior - requires Liquid plus JavaScript plus CSS knowledge or hiring a developer. The workable middle path for non-developers is to pick a theme with a strong section library (Dawn, Impulse, Prestige, Empire, or Ella are typical picks), customize via theme editor, install 2-4 carefully chosen apps for missing functionality, and accept that you will not match the visual specificity of a custom theme. Shopify's theme architecture documentation is honest about which work needs code and which does not.
What is the difference between Online Store 2.0 themes and vintage themes?
Online Store 2.0 (announced June 2021, default by 2024) is the modern Shopify theme architecture built around JSON templates, sections everywhere, app blocks, and theme-editor-driven content. Vintage themes are the pre-2021 architecture: Liquid templates with hardcoded sections, a fixed page structure, and limited theme-editor customization. The visible difference for merchants: 2.0 themes let you add, remove, and reorder sections on every template (product, collection, cart, blog, page); vintage themes only allowed that on the homepage. The visible difference for developers: 2.0 uses JSON for templates and section schemas while keeping Liquid for rendering, and 2.0 supports app blocks that let third-party apps inject UI directly into theme sections without code modification. All actively maintained themes in the Shopify Theme Store in 2026 are 2.0; vintage themes still work but are no longer accepted for new submissions.
Should I customize an existing theme or build a custom one from scratch?
Customize when 80 percent of the brief is already in a free or paid theme and you want to ship in 2-4 weeks at $5K-$15K. Build custom when the brief includes brand-specific layouts, custom interactions, or commerce mechanics that no off-the-shelf theme covers (subscriptions with custom UI, bundles with custom logic, B2B portals, multi-step product configurators). Build custom when the brand needs visual specificity that a templated theme cannot deliver. Buy a premium theme ($150-$350) when you want a polished starting point and have a designer who can customize via theme editor without touching code. The wrong-answer pattern is buying a premium theme and then paying $25K of customization on top of it - at that point a custom theme would have been cheaper and more maintainable. The honest decision tree comes down to: how specific is your brand brief, how much time do you have, and what is your ongoing maintenance budget.
§ 10 · the next step
Six-week build. Named lead. Written scope.
A 30-minute custom-theme discovery call. Named lead engineer on the call, not a sales rep. Written scope plus rate card returned within two business days. 2,000-plus stores shipped since 2017; Trustpilot 4.9 across 70-plus reviews; Premier Shopify Plus partner; UN Global Marketplace Tier 1; New York and Delhi HQ.