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

# Architecture Overview

> Understanding the Horizon Shopify theme architecture and design principles

## Introduction

Horizon is Shopify's flagship theme that showcases the latest **Liquid Storefronts** features, including the revolutionary **theme blocks** architecture. Built with modern web standards and performance at its core, Horizon represents a new generation of first-party Shopify themes.

## Core Philosophy

Horizon is built on four foundational principles:

<AccordionGroup>
  <Accordion title="Web-native in its purest form">
    Themes run on the [evergreen web](https://www.w3.org/2001/tag/doc/evergreen-web/). Horizon leverages the latest web browsers to their fullest, while maintaining support for older browsers through progressive enhancement—not polyfills.
  </Accordion>

  <Accordion title="Lean, fast, and reliable">
    Functionality and design defaults to "no" until it meets this requirement. Code ships on quality. Themes must be built with purpose and shouldn't support every feature in Shopify unnecessarily.
  </Accordion>

  <Accordion title="Server-rendered">
    HTML must be rendered by Shopify servers using Liquid. Business logic and platform primitives such as translations and money formatting don't belong on the client. Async and on-demand rendering of parts of the page is OK, but used sparingly as progressive enhancement.
  </Accordion>

  <Accordion title="Functional, not pixel-perfect">
    The Web doesn't require each page to be rendered pixel-perfect by each browser engine. Using semantic markup, progressive enhancement, and clever design ensures themes remain functional regardless of the browser.
  </Accordion>
</AccordionGroup>

## Directory Structure

Horizon follows the standard Shopify theme structure with enhanced organization:

```
source/
├── assets/          # CSS, JavaScript, and static assets
├── blocks/          # Theme blocks (94 files)
├── config/          # Theme settings and configuration
├── layout/          # Layout templates (theme.liquid, password.liquid)
├── locales/         # Translation files
├── sections/        # Section files (41 files)
├── snippets/        # Reusable Liquid snippets (93 files)
└── templates/       # Page templates (JSON format)
```

<Note>
  Horizon contains **94 theme blocks**, **41 sections**, and **93 snippets**, making it one of the most comprehensive Shopify themes available.
</Note>

## Key Components

### Sections

Sections are the building blocks of Shopify pages. Horizon includes both static and dynamic sections:

<CardGroup cols={2}>
  <Card title="Layout Sections" icon="grip">
    * `_blocks.liquid` - Universal block container
    * `hero.liquid` - Hero banners with media
    * `carousel.liquid` - Product/content carousels
  </Card>

  <Card title="Content Sections" icon="newspaper">
    * `featured-product.liquid` - Product showcases
    * `collection-list.liquid` - Collection grids
    * `media-with-content.liquid` - Rich media sections
  </Card>

  <Card title="Header/Footer" icon="window">
    * `header-group.json` - Header section group
    * `footer-group.json` - Footer section group
    * `header-announcements.liquid` - Announcement bars
  </Card>

  <Card title="Page-Specific" icon="file">
    * `main-product.liquid` - Product page
    * `main-collection.liquid` - Collection page
    * `main-blog.liquid` - Blog listing
  </Card>
</CardGroup>

### Blocks

Theme blocks (prefixed with `_`) are reusable components that can be added to sections:

```liquid blocks/_heading.liquid theme={null}
{%- doc -%}
  Renders a heading block.

  @param {string} text
{%- enddoc -%}

{% render 'text', width: '100%', block: block, fallback_text: text %}

{% schema %}
{
  "name": "t:names.heading",
  "tag": null,
  "settings": [
    {
      "type": "select",
      "id": "type_preset",
      "label": "t:settings.preset",
      "options": [
        { "value": "h1", "label": "t:options.h1" },
        { "value": "h2", "label": "t:options.h2" },
        // ... more options
      ]
    }
  ]
}
{% endschema %}
```

### Snippets

Snippets are reusable Liquid templates for common functionality:

* `section.liquid` - Universal section wrapper
* `group.liquid` - Block group container
* `bento-grid.liquid` - Advanced grid layouts
* `background-media.liquid` - Media background handler
* `cart-products.liquid` - Cart product rendering

### Templates

Horizon uses **JSON templates** exclusively for maximum flexibility:

```json templates/index.json theme={null}
{
  "sections": {
    "hero_jVaWmY": {
      "type": "hero",
      "blocks": {
        "text_YLPk4p": {
          "type": "text",
          "settings": {
            "text": "<p>Browse our latest products</p>"
          }
        }
      }
    }
  },
  "order": ["hero_jVaWmY", "product_list_fa6P9H"]
}
```

## Rendering Architecture

### Section Rendering Flow

Horizon uses a sophisticated rendering pattern:

<Steps>
  <Step title="Section Definition">
    Sections define their schema, blocks, and settings in `{% schema %}` tags
  </Step>

  <Step title="Content Capture">
    Block content is captured using `{% content_for 'blocks' %}`
  </Step>

  <Step title="Snippet Rendering">
    Captured content is passed to reusable snippets: `{% render 'section', section: section, children: children %}`
  </Step>

  <Step title="Final Output">
    Snippets apply styling, structure, and output the final HTML
  </Step>
</Steps>

### Example: Blocks Section

```liquid sections/_blocks.liquid theme={null}
{% capture children %}
  {% content_for 'blocks' %}
{% endcapture %}

{% render 'section', section: section, children: children %}

{% schema %}
{
  "name": "t:names.section",
  "class": "section-wrapper",
  "blocks": [
    { "type": "@theme" },
    { "type": "@app" },
    { "type": "_divider" }
  ],
  "settings": [...]
}
{% endschema %}
```

## Layout System

### Main Layout

The `theme.liquid` layout file provides the HTML structure:

```liquid layout/theme.liquid theme={null}
<!doctype html>
<html lang="{{ request.locale.iso_code }}">
  <head>
    {%- render 'meta-tags' -%}
    {%- render 'stylesheets' -%}
    {%- render 'fonts' -%}
    {%- render 'scripts' -%}
    {%- render 'theme-styles-variables' -%}
    {%- render 'color-schemes' -%}
    {{ content_for_header }}
  </head>

  <body>
    <div id="header-group">
      {% sections 'header-group' %}
    </div>

    <main id="MainContent" role="main">
      {{ content_for_layout }}
    </main>

    <footer>
      {% sections 'footer-group' %}
    </footer>
  </body>
</html>
```

<Note>
  The `{% sections 'header-group' %}` and `{% sections 'footer-group' %}` tags enable section groups, a powerful Liquid Storefronts feature.
</Note>

## Asset Management

Horizon uses a modular asset architecture:

<Tabs>
  <Tab title="CSS">
    * `base.css` - Core styles and CSS variables
    * Component-specific stylesheets loaded per section
    * Scoped styles using `{% stylesheet %}` tags in snippets
  </Tab>

  <Tab title="JavaScript">
    * `component.js` - Base component class
    * `events.js` - Custom event system
    * Web components for interactive elements
    * Progressive enhancement approach
  </Tab>

  <Tab title="Images">
    * Lazy loading with `loading="lazy"`
    * Responsive images using `image_url` filters
    * WebP format support
  </Tab>
</Tabs>

## Performance Optimizations

### Server-Side Rendering

All HTML is rendered server-side using Liquid, ensuring:

* Fast initial page loads
* SEO-friendly content
* No client-side hydration overhead

### Progressive Enhancement

```javascript theme={null}
// Inline critical header calculations
(function setHeaderHeighCustomProperties() {
  const header = document.querySelector('header-component');
  const headerHeight = header.offsetHeight;
  document.body.style.setProperty('--header-height', `${headerHeight}px`);
})();
```

### Minimal JavaScript

JavaScript is used sparingly:

* Web Components for complex interactions
* Native browser APIs over libraries
* Vanilla JS, no framework dependencies

## Next Steps

<CardGroup cols={2}>
  <Card title="Theme Structure" icon="folder-tree" href="/architecture/theme-structure">
    Explore sections, blocks, snippets, and templates in detail
  </Card>

  <Card title="Liquid Storefronts" icon="droplet" href="/architecture/liquid-storefronts">
    Learn about modern Liquid features and APIs
  </Card>

  <Card title="Theme Blocks" icon="cube" href="/architecture/theme-blocks">
    Deep dive into the theme blocks architecture
  </Card>

  <Card title="Getting Started" icon="rocket" href="/getting-started">
    Start building with Horizon
  </Card>
</CardGroup>