> ## 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.

# Custom sections

> Build a new VARAHI section from scratch — schema, blocks, styles and the rules that keep it upgrade-safe.

# Custom sections

A new section is a new file in `sections/`. Shopify picks it up automatically — there
is no registration step.

***

## A minimal section

```liquid theme={"system"}
{%- comment -%} My Section {%- endcomment -%}

<section class="my-section" {{ section.shopify_attributes }}>
  <div class="container">
    {%- if section.settings.heading != blank -%}
      <h2 class="my-section__heading">{{ section.settings.heading }}</h2>
    {%- endif -%}

    {%- for block in section.blocks -%}
      <div class="my-section__item" {{ block.shopify_attributes }}>
        {{ block.settings.title }}
      </div>
    {%- endfor -%}
  </div>
</section>

{% schema %}
{
  "name": "My Section",
  "settings": [
    { "type": "text", "id": "heading", "label": "Heading", "default": "My heading" }
  ],
  "blocks": [
    {
      "type": "item",
      "name": "Item",
      "settings": [
        { "type": "text", "id": "title", "label": "Title", "default": "Item" }
      ]
    }
  ],
  "presets": [
    { "name": "My Section", "blocks": [{ "type": "item" }] }
  ]
}
{% endschema %}
```

***

## Rules

### Use the design tokens

```css theme={"system"}
.my-section {
  padding: var(--space-section-padding) 0;
  background: var(--color-surface-container-low);
  color: var(--color-on-surface);
  border-radius: var(--radius-lg);
  border: 1px solid var(--glass-border);
}
```

> [!WARNING]
>
> Never hard-code a colour. `background: #0b1119` will not follow the merchant's
> brand; `var(--color-surface-container-low)` will.

### Use the container class

The theme has a `.container` class that handles the max width and the responsive
gutters. Use it rather than rolling your own.

### Use `section.shopify_attributes`

On the section root element. It is what lets the theme editor and app extensions
target your section.

### Use `block.shopify_attributes`

On every block wrapper. Same reason.

### Scope your styles

```css theme={"system"}
.my-section { — }
.my-section__heading { — }
.my-section__item { — }
```

> [!WARNING]
>
> Do not write bare element selectors like `.container` or `h2` in a section's style
> block. Section styles are global once rendered — they will leak into every other
> section on the page. Always scope to your section's class.

### Put the styles in a `<style>` block

```liquid theme={"system"}
{% style %}
  .my-section { — }
{% endstyle %}
```

The `{% style %}` tag is Shopify's way of letting the theme editor move section CSS
into a global stylesheet. It is the correct choice for a section.

***

## Adding it to a template

Open the template in the theme editor and click **Add section**. Your new section
appears in the list automatically. You do not need to edit any JSON.

> [!NOTE]
>
> If you want the section available in a template by default, you can add it to
> `templates/*.json`. But be aware that rebuilding a template from JSON can drop
> blocks the merchant has configured. Prefer adding sections through the editor.

***

## Making it upgrade-safe

| Do | Don't |
| - | - |
| Add new files | Edit existing section files |
| Scope every selector | Use bare element selectors |
| Use design tokens | Hard-code colours and sizes |
| Put CSS in `{% style %}` | Put CSS in `assets/` for a section |
| Name classes `sectionname__element` | Reuse another section's class names |

> [!WARNING]
>
> VARAHI's own section files use the same conventions. If you follow them, a future
> theme update will not conflict with your code.

***

## A worked example

A "Press & awards" section with a logo row.

```liquid theme={"system"}
{%- comment -%} Press Logos {%- endcomment -%}

<section class="press" {{ section.shopify_attributes }}>
  <div class="container press__inner">
    {%- if section.settings.heading != blank -%}
      <p class="press__heading">{{ section.settings.heading }}</p>
    {%- endif -%}

    <ul class="press__list" role="list">
      {%- for block in section.blocks -%}
        <li class="press__item" {{ block.shopify_attributes }}>
          {%- if block.settings.logo != blank -%}
            <img
              src="{{ block.settings.logo | image_url: width: 200 }}"
              alt="{{ block.settings.alt | escape }}"
              width="120"
              height="40"
              loading="lazy"
            >
          {%- else -%}
            <span class="press__name">{{ block.settings.name }}</span>
          {%- endif -%}
        </li>
      {%- endfor -%}
    </ul>
  </div>
</section>

{% style %}
  .press { padding: var(--space-section-padding) 0; }
  .press__inner { text-align: center; }
  .press__heading {
    font-family: var(--font-label);
    font-size: var(--text-technical-sm);
    letter-spacing: var(--tracking-label);
    text-transform: uppercase;
    color: var(--color-on-surface-variant);
    margin-bottom: var(--space-base);
  }
  .press__list {
    display: flex; flex-wrap: wrap; gap: var(--space-grid-gutter);
    justify-content: center; list-style: none; padding: 0; margin: 0;
  }
  .press__item img { max-width: 120px; opacity: .55; transition: opacity var(--transition-fast); }
  .press__item:hover img { opacity: 1; }
{% endstyle %}

{% schema %}
{
  "name": "Press logos",
  "settings": [
    { "type": "text", "id": "heading", "label": "Heading", "default": "As featured in" }
  ],
  "blocks": [
    {
      "type": "logo",
      "name": "Logo",
      "settings": [
        { "type": "image_picker", "id": "logo", "label": "Image" },
        { "type": "text", "id": "name", "label": "Name", "default": "Publication" },
        { "type": "text", "id": "alt", "label": "Alt text" }
      ]
    }
  ],
  "presets": [{ "name": "Press logos" }]
}
{% endschema %}
```

***

> **[Code reference](https://varaahi.vritservicespro.com/going-further/code-reference.md)**
>
> The token system and the file map.

> **[Performance](https://varaahi.vritservicespro.com/going-further/performance.md)**
>
> The budgets your section has to fit inside.


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