> ## Documentation Index
> Fetch the complete documentation index at: https://vr-it-services-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Classic templates, a token-based design system, and how page builder detection works.

# How it works

# How the theme works

Understanding this one page will save you an hour of confusion later. Vara SaaS is a **classic PHP theme with a Gutenberg-aligned `theme.json` and deep Elementor integration** — it is not a full site editing theme.

## The three layers

**1. Layer 1 — Classic PHP templates**

The page skeleton comes from PHP files in the theme root: `header.php`, `footer.php`, `front-page.php`, `home.php`, `single.php`, `page.php`, `archive.php`, `search.php`, `404.php`. WordPress picks the right one using the standard template hierarchy. Partial components live in `template-parts/`.

**2. Layer 2 — theme.json for the editor only**

`theme.json` declares a nine-color palette, two font families, ten type sizes, and a content width. It exists so that the **block editor** offers the same design vocabulary the front end uses. It does **not** control your page layout — that is still PHP.

**3. Layer 3 — Elementor for page content**

When you build a page in Elementor, the theme detects it and steps out of the way entirely.

> [!NOTE]
>
> You can confirm which system is in charge on any page: **view source** and look for `body` classes. `vara-saas-builder-page` means Elementor owns that page.

## Page builder detection

Vara SaaS checks several signals before deciding a page belongs to a page builder. It steps aside if **any** of these are true:

* The page's Elementor data (`_elementor_data`) exists and is not empty
* The page's `_elementor_edit_mode` meta equals `builder`
* The request is an Elementor editor or preview request

It also recognises three other builders so they behave the same way:

| Builder | Signals checked |
| - | - |
| **Elementor** | `_elementor_data`, `_elementor_edit_mode`, editor/preview query args |
| **Beaver Builder** | `_fl_builder_data` post meta, `FLBuilderModel` loaded |
| **Divi** | `_et_pb_use_builder` meta, `et_fb` query argument |
| **Bricks** | `_bricks_page_content_2` meta, `bricks` query argument |

When a page is detected as builder-owned **and** has content, `page.php`, `single.php`, and `front-page.php` render the content alone — no container, no theme `h1`, no sidebar, no comments wrapper on pages. The result is a full-bleed canvas.

![Screenshot: view source showing the vara-saas-builder-page body class](https://mintlify.s3.us-west-1.amazonaws.com/vr-it-services-pro/images/screenshots/how-it-works-body-classes.png)

## The design token system

Branding is implemented as CSS custom properties on `:root`. This is why a color change in the Customizer updates everything at once, including dark mode, without a stylesheet rebuild.

The theme enqueues `style.css` primarily to host these tokens, then appends your chosen values as inline styles. The naming convention is:

```css theme={null}
:root {
  --vara-primary: #7c3aed;
  --vara-accent:  #4edea3;
  --vara-bg:      #f8fafc;
  --vara-surface: #ffffff;
  --vara-text:    #0f172a;
  --vara-border:  #e2e8f0;
}
```

**Every token is documented**

The full list of variables, their defaults, and where each one is used is on
[CSS and design tokens](/developers/css-and-design-tokens.md).

## How colors reach Elementor

This is the part that surprises people, so it is worth being precise.

On `after_setup_theme` at priority `0` — before almost everything else runs — the theme reads Elementor's active kit post and writes your brand colors into its global settings:

1. The four **system colors** (Primary, Secondary, Text, Accent) are overwritten with your Customizer values.
2. Your remaining brand colors are merged in as **custom global colors**.

The practical effect: when you set your primary color in **Appearance → Customize → Vara SaaS → Global Colors**, every Elementor widget set to "Primary" updates too. You brand once.

> [!WARNING]
>
> Because this runs on **every request**, it also overwrites changes you make directly in **Elementor → Site Settings → Global Colors**. The Customizer is the source of truth. Edit brand colors in the Customizer, not in Elementor's global settings, or they will be replaced.

## How `front-page.php` decides what to show

Your front page can be a page, a blog, or something in between, and the theme resolves it at runtime:

1. If **Settings → Reading** shows your latest posts, the front page renders the full blog index.
2. If a **static front page** is set, the theme checks whether that page is builder-owned.
3. Builder-owned with content → render the builder content alone.
4. Not builder-owned or empty → render the six built-in demo sections (see [Default sections](/templates/default-sections.md)).

## How the blog templates work

Four templates share nearly identical logic — `home.php`, `archive.php`, `search.php`, and the posts-mode branch of `front-page.php`. Each renders:

> **A hero band**
>
> Title, subtitle, a search form, and the top four categories as filter pills. Archives and search results supply their own wording.

> **An optional featured post**
>
> On the blog home only: the first sticky post, or the newest post if there are no sticky posts. It is removed from the grid so it is not duplicated.

> **A responsive grid**
>
> Standard cards, except posts using the **aside** format, which render as compact cards with the content clamped to six lines.

> **Accessible pagination**
>
> `paginate_links()` in list mode, with screen-reader-only "previous" and "next" labels.

![Screenshot: the blog index showing the hero, featured post and card grid](https://mintlify.s3.us-west-1.amazonaws.com/vr-it-services-pro/images/screenshots/how-it-works-blog-index.png)

Category filtering works through a `?vara_cat=` query parameter. The pills in the blog hero link to filtered views, and the search form carries the active category through as a hidden field so searching from a filtered view keeps your filter.

## How the single post template works

`single.php` is the most feature-dense template in the theme. It renders, in order:

1. **Category pills** with a "(+N)" overflow control when a post has more than a handful of categories
2. **The `h1` title**
3. **The excerpt**, if present
4. **Byline** — author avatar, name, role, publish date, and reading time, each individually toggleable in the Customizer
5. **Featured image**
6. **Table of contents** — generated automatically from your `h2` and `h3` headings, placed in the sidebar when a sidebar is active, otherwise inline above the article
7. **The content**
8. **Tag pills** with the same overflow control
9. **Related reading** — up to two posts sharing a category
10. **Comments**

The table of contents is worth understanding because it is entirely automatic. The theme scans your post content for `<h2>` and `<h3>` elements, assigns each a unique slugged `id`, injects those ids back into the content, and builds a linked outline. Add new `h2` headings in the editor and they appear in the table of contents with no configuration.

> [!NOTE]
>
> Password-protected posts render **only** the title and the password form. The content, featured image, table of contents, related posts, and comments are all suppressed until the post is unlocked.

## Conditional asset loading

The theme only loads what a given page view needs:

| Assets | Loaded on |
| - | - |
| `screen.css`, `dynamic-vars.css`, `portfolio-and-theme.css`, local fonts, Font Awesome | Every page |
| `blog-index.css` | Blog home, archives, search |
| `single-blog.css` + `single-toc.js` | Singular views only |
| `main.js` | Every page, deferred |
| `animations.js` | Every page, priority 20 |
| `comment-reply.js` | Singular, when comments are open and threaded |
| Customizer preview JS/CSS | Customizer preview frame only |

## Next steps

> **[What's in the download](/introduction/whats-included.md)**
>
> Every file and what it does.

> **[Install it](/introduction/installation.md)**
>
> Get it running in two minutes.


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