0. Introduction

What is Noir

Noir is a Shopranos storefront theme implemented with Liquid templates and a section-based page composition model.
Pages are rendered by the main layout template (Structure/LayoutA.liquid) and are composed from Header / Body / Footer component lists.

Key technologies used in Noir:

Liquid for server-side rendering and template composition

Tailwind CSS for styling (generated bundle: output.css)

Alpine.js for interactive UI behavior and shared state (stores)

Vendor libraries loaded by the layout (e.g. axios, swiper, leaflet, lightgallery, nouislider)

This documentation describes how Noir is structured, how it renders, and how to extend it safely.

Who this is for

This guide is written for developers who are new to Noir and want to understand the whole theme before changing it.

Assumed knowledge: basic Liquid, HTML/CSS, Tailwind, and Alpine.js.

No prior Noir knowledge is required — read the sections in order (see the learning path at the end of this page).

Theme structure

This documentation focuses on the following theme folders:

Structure/
Layout and infrastructure templates (layout, metas, CSS variables, component list renderer, debug utilities).

Components/
Platform-rendered components. Each component typically includes:

Default.liquid (markup + bindings)

Default.js (client behavior, if needed)

Default.json (translations/strings, if needed)

Reusables/
Theme-only building blocks that can be rendered from other templates (often used for modals, buttons, shared UI pieces).
Reusables follow the same file pattern (Default.liquid, optional Default.js, optional Default.json).

Assets/
Static assets: CSS, JS, fonts, images, vendor libraries.

This three-file pattern (Default.liquid + Default.js + Default.json) is called the trio, and you will see it referenced throughout these docs.

How rendering works (high level)

Noir renders HTML using:

Main layout template: Structure/LayoutA.liquid
It outputs the page shell (<head>, CSS/JS includes, header/main/footer) and renders the component lists.

Component list renderer: Structure/ComponentsList.liquid
It iterates components and includes the correct template by naming convention.

At runtime, the layout injects some globals into window (feature flags and basic user info), which are used by JavaScript and Alpine stores.

Assets are referenced via GlobalData.RootPath and versioned with GlobalData.Settings.Version.

Component include convention

The component list renderer resolves each component template name using:

Components_<model.Name>_<model.View>

So, a component with:

model.Name = "Announcement"

model.View = "Default"

will be rendered via the include:

Components_Announcement_Default

This convention is critical: if the Name / View combination doesn't match an existing template, the component won't render.

Core principle: server-prepared data

The most important thing to understand before reading any component page is where the work happens.

The platform prepares the data: totals, grouping, and currency strings arrive already formatted in the component model.

The client JS only drives UI state: tabs, toggles, show/hide, selected options.

So when you read "what a component can do", assume the data is ready to render. Client-side fetching on load is the exception, not the rule — the few components that do it call it out explicitly on their own page.

Common data you'll see in templates

Component model

Component templates receive a model object. Common fields:

model.Settings.Id
A deterministic identifier used for DOM ids.

model.Settings.CssClass
Optional CSS class (used to customize spacing/appearance).

model.Translations.*
Strings backed by the component's Default.json (when available).

Global objects (Liquid)

Across templates you will commonly see:

Root
Page and user-related data.

GlobalData
Global settings and paths (e.g. root path, version for cache busting).

Client-side architecture

Noir uses a mix of:

Theme-wide JS: Assets/js/theme.js
Contains shared utilities and cross-component logic (e.g. cookies, observers, GA helpers) and is the home for Alpine stores.

Theme "SDK / Services": Reusables/Services/Default.js
Exposes a servicesreusabledefault object with helper methods and API calls used by components/reusables (e.g. wishlist, shopping lists, product search helpers).

Component / Reusable scripts
Many components/reusables register Alpine-compatible objects or factories and rely on the layout's script loading order.

Styling approach

Main CSS bundle: output.css (generated from Tailwind)

Custom styles: stored under Assets/scss/ and compiled into CSS that is imported by the Tailwind entrypoint.

When adjusting markup, prefer existing Tailwind utility classes. Avoid introducing new custom CSS unless needed.

Debugging tips

Use the theme's JSON/debug helpers (see Structure/Json.liquid) to inspect view models in the browser.

Inspect runtime globals injected by the layout (feature flags, user auth state) via DevTools.

How to use this documentation

Read the sections in this order — each one builds on the previous:

Introduction (this page)
The big picture: tech stack, structure, rendering pipeline, and core principles.

Structure
The rendering pipeline in detail: layout responsibilities, shared includes, and runtime globals.

Components
What each component does and how to configure it. Open the section overview first, then the page for a specific component.

Reusables
Shared building blocks (modals, buttons, list items) rendered from components/layout.

Assets
The CSS/JS pipeline plus vendor and font guidance.

SDK
The theme-side service methods, shared globals, and API-call breakdown.

FAQ
Quick answers to common questions (e.g. how model, Root.Page, and Root.GlobalData relate).

Finding what a component does

Every component and reusable has its own page describing its purpose, inputs, template behavior, and JavaScript. Each section also has an _Overview.md index you can browse first to get the lay of the land.

If you're extending Noir, always follow the existing naming conventions and shared-store patterns to avoid breaking cross-component behavior.

0. Introduction

What is Noir#

Who this is for#

Theme structure#

How rendering works (high level)#

Component include convention#

Core principle: server-prepared data#

Common data you'll see in templates#

Component model#

Global objects (Liquid)#

Client-side architecture#

Styling approach#

Debugging tips#

How to use this documentation#

Finding what a component does#