Theme architecture

A Shopify theme is a folder of files with very specific jobs. Understanding the distinction between a section, a block and a snippet is the difference between a ten-minute customisation and an afternoon of confusion.

Theme file structure — File structure of the VARAHI theme

The hierarchy

layout/theme.liquid          The one required file. Page shell, <head>, fonts, global scripts

|-- sections/                Reusable page modules. The unit merchants add and reorder.
|   |-- each has a {% schema %}  Declares the settings and blocks the editor exposes
|
|-- blocks/                  (not used) - VARAHI uses section-scoped blocks
|
|-- snippets/                Reusable Liquid partials. No schema. Not merchant-facing.
|
|-- templates/*.json         Page templates. A JSON list of which sections render, in order.
|
|-- config/
|   |-- settings_schema.json  Theme-wide settings (colors, favicon, social image)
|   `-- settings_data.json    The merchant's current values for those settings
|
|-- locales/*.json           Every user-facing string, translatable
|
`-- assets/                  CSS, JS, fonts, images. Never rendered directly.

Sections vs. blocks vs. snippets

Layer	What it is	Who controls it	Example
Section	A whole module of a page — hero, footer, collection grid	Merchant, via the theme editor	Hero Product
Block	A repeatable piece inside a section, with its own settings	Merchant, via the theme editor	A single “Highlight” card inside Hero Product
Snippet	Reusable Liquid that renders no settings of its own	Developer	product-card.liquid, facets.liquid
Template	Which sections appear on a page type, and in what order	Merchant, per template	templates/product.json

Rule of thumb. If a merchant would want to add, remove, reorder or duplicate it on a page, it is a section or a block. If it is an implementation detail, it is a snippet.

VARAHI’s section groups

The theme ships with 30 sections across the templates below.

Template	Sections available
Home	Hero Product, Bento Features, Acoustic architecture, Companion app, Comparison Table, Product Reviews, Rich Text, Image with Text, FAQ, Video, Featured product, Spacer, Custom Liquid
Product	Main product, Acoustic architecture, Comparison Table, Companion app, Product Reviews, Related products, Rich Text, FAQ, Spacer
Collection	Main Collection (with facets), Product Reviews, Rich Text, Spacer
Cart	Main Cart, Product Reviews, Rich Text, Spacer
Page / Blog / Article / Search / Contact	Main Page, Main Blog, Main Article, Main Search, Main Contact, Main List Collections, Rich Text, FAQ, Video, Spacer
Global	Header, Footer, Cart Drawer, Live Toast, Password, Main 404, Main Order

The design system

Every visual decision in the theme resolves to a CSS custom property defined in snippets/css-variables.liquid.

/* Colours — merchant-overridable, derived */
--color-primary-container: #00f0ff;   /* buttons, links, focus */
--color-secondary-container: #9b5de5; /* violet counterpoint */
--color-background: #05080d;          /* page canvas */

/* Type */
--font-display: "Inter", system-ui, sans-serif;
--font-label: "JetBrains Mono", Menlo, monospace;
--text-display-lg: 72px;
--text-body-md: 16px;

/* Space, radius, motion, depth */
--space-section-padding: 96px;
--radius-lg: 1rem;
--transition-base: .3s ease;
--z-drawer: 80;

Because every section consumes these variables rather than hard-coded values, changing one setting in the theme editor restyles the entire store consistently.

Merchant-overridable tokens are wrapped in Liquid ({{ settings.color_primary | default: "#00f0ff" }}). Fixed tokens — the deep surface ramp, the glass effects, the z-index scale — are constants you can still override in code if you need to.

JavaScript architecture

VARAHI ships two main script bundles, plus a few small conditional scripts.

Bundle	Contents	Loaded when	Size
`app.js`	Store API, cart API, scroll reveal, header + drawer behaviour	Every page	~21 KB
`motion.js`	GSAP, ScrollTrigger, VARAHI choreography	Desktop only, on idle	~134 KB

The motion bundle is skipped entirely below 1024px. This is a deliberate performance decision, not a bug. See Performance.

Which files can you edit?

File	Safe?	Notes
`snippets/css-variables.liquid`	— Yes	Add your own tokens here
`assets/custom.css` (create it)	— Yes	Keep custom CSS in one file
`assets/custom.js` (create it)	— Yes	Same reasoning
`snippets/*.liquid` (add new)	— Yes	New snippets never conflict
`sections/*.liquid` (add new)	— Yes	New sections never conflict
`sections/*.liquid` (edit existing)	Careful	This is what creates upgrade conflicts
`layout/theme.liquid`	Careful	One-line changes only; document them
`templates/*.json`	Careful	Rebuilding the section list can drop blocks
`config/settings_schema.json`	Careful	Removing a setting loses its value

Next: colours

The three settings that rebrand the whole theme.

Getting Started

Theme Configuration

Sections & Blocks

Features

Going Further

Resources

Theme architecture

Theme architecture

The hierarchy

Sections vs. blocks vs. snippets

VARAHI’s section groups

The design system

JavaScript architecture

Which files can you edit?

Next: colours

​Theme architecture

​The hierarchy

​Sections vs. blocks vs. snippets

​VARAHI’s section groups

​The design system

​JavaScript architecture

​Which files can you edit?

Next: colours

Theme architecture

The hierarchy

Sections vs. blocks vs. snippets

VARAHI’s section groups

The design system

JavaScript architecture

Which files can you edit?