> ## Documentation Index
> Fetch the complete documentation index at: https://varaahi.vritservicespro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Theme architecture

> How VARAHI is organised — sections, blocks, snippets, templates and assets — and which files you can safely edit.

# 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](https://mintlify.s3.us-west-1.amazonaws.com/vr-it-services-pro-c6bfa2fc/images/placeholder/theme-file-structure.png)

File structure of the VARAHI theme

***

## The hierarchy

```text theme={"system"}
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 |

> [!NOTE]
>
> **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`.

```css theme={"system"}
/* 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.

> [!NOTE]
>
> 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 |

> [!WARNING]
>
> The motion bundle is **skipped entirely below 1024px**. This is a deliberate
> performance decision, not a bug. See
> [Performance](https://varaahi.vritservicespro.com/going-further/performance.md#mobile-has-no-motion).

***

## 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](https://varaahi.vritservicespro.com/settings/colors.md)**
>
> The three settings that rebrand the whole theme.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.