Bricks-Sections/.claude/research/bricks-research.md

# Bricks Builder Template System — Research Notes

**Date:** 2026-02-26

---

## 1. Template Export / Import

### Export
- **Single template:** Hover template title → Click Export → Downloads a `.json` file
- **Bulk export:** Bricks → Templates → Select templates → Bulk Actions → Export → Downloads a `.zip` containing individual `.json` files

### Import
- Bricks → Templates → Import Templates → Select `.json` or `.zip`
- Drag-and-drop supported
- Optional checkbox: **IMPORT IMAGES** — downloads template images into the media library

### File Formats
| Scenario | Format |
|---|---|
| Single template | `.json` |
| Multiple templates | `.zip` (containing individual `.json` files) |
| Components | `.json` (same pattern) |

---

## 2. Template Types

| Type | Purpose |
|---|---|
| **Header** | Site-wide header (navigation, logo) |
| **Footer** | Site-wide footer (copyright, links) |
| **Single** | Individual post/page layouts |
| **Single Product** | WooCommerce product detail pages |
| **Section** | Reusable content blocks (hero, CTA, etc.) |
| **Archive** | Category/tag/author archive pages |
| **Search Results** | Custom search results layout |
| **404 Error Page** | Not-found page |
| **Product Archive** | WooCommerce shop/category pages |

**Notes:**
- Bricks auto-applies the first published Header and Footer templates site-wide by default
- Section templates do **not** auto-sync after being inserted into a page — they become independent
- Section templates can be injected via WordPress hooks (since v1.9.1) with priority control
- Template **conditions** control where each template displays; conditions can also be excluded (since v1.3.6)

---

## 3. Remote Templates (Built-in Feature)

The cleanest way to serve a personal library across multiple sites without manual importing.

### Setup on the Source Site
1. Bricks → Settings → Templates → Enable **"My Templates Access"**
2. Optionally set a password and whitelist allowed URLs

### Setup on Client/New Site
1. Bricks → Settings → Templates → Add **"Remote Templates URL"** (source site URL)
2. Remote templates then appear in the Bricks Template Library panel

**Notes:**
- Permalink structure on source site must not be set to "Plain"
- Unlimited remote URLs supported since v1.9.4
- Third-party plugin **Yabe Ukiyo** (free) offers more flexibility and licensing support

---

## 4. Plugin-Based Distribution

You can bundle templates into a WordPress plugin for one-click installs:

```php
// Minimal example: register templates on plugin activation
register_activation_hook( __FILE__, 'bcw_import_templates' );

function bcw_import_templates() {
    $template_dir = plugin_dir_path( __FILE__ ) . 'templates/';
    $files = glob( $template_dir . '*.json' );

    foreach ( $files as $file ) {
        $data = json_decode( file_get_contents( $file ), true );
        // Insert into Bricks templates (stored as CPT: bricks_template)
        wp_insert_post( [
            'post_type'   => 'bricks_template',
            'post_title'  => $data['title'] ?? basename( $file, '.json' ),
            'post_status' => 'publish',
            'meta_input'  => [
                '_bricks_page_content_2' => json_encode( $data['content'] ?? [] ),
                '_bricks_template_type'  => $data['type'] ?? 'section',
            ],
        ] );
    }
}
```

**Notes:**
- Bricks templates are stored as the custom post type `bricks_template`
- Template content is stored in the post meta key `_bricks_page_content_2`
- Template type is stored in `_bricks_template_type`

---

## 5. BricksSync (Third-Party Tool)

File-based sync tool that stores templates as Git-friendly JSON files.

- **Storage locations:** Child Theme, Uploads Folder, or custom path
- **Sync modes:** Manual Only, Auto Import Only, Auto Export Only, Full Auto Sync
- **Supports:** Templates, Components, Settings, Content, Plugin data
- Useful for version control and multi-environment deployments

---

## 6. Template JSON Structure (Inferred)

While official schema docs are sparse, the JSON export contains at minimum:

```json
{
  "title": "Template Name",
  "type": "section",
  "content": [ /* array of Bricks element objects */ ],
  "settings": { /* page/template-level settings */ },
  "source": "bricks",
  "version": "1.x"
}
```

Each element in `content` follows this general pattern:

```json
{
  "id": "unique-id",
  "name": "section",
  "parent": 0,
  "children": ["child-id-1"],
  "settings": {
    "_padding": { "top": "var(--space-m)" },
    "_background": { "color": { "raw": "var(--color-primary)" } },
    "tag": "section"
  }
}
```

---

## 7. Existing Project Design System (sibling directory)

`/mnt/d/Dropbox/Bricks Source/Style-Guide-By-BricksTemplate/` contains:

| File | Contents |
|---|---|
| `bricks-color-palette-brickstemplate.json` | 40+ color variables (primary, secondary, tertiary, tints, semantic) |
| `bricks-css-variables-brickstemplate.json` | 140+ design tokens: typography, spacing, shadow, radius, grid, widths |
| `bricks-theme-style-brickstemplate.json` | Global theme config (Inter headings, Poppins body, section padding, container width) |
| `bricks-css-classes-brickstemplate.json` | 50+ predefined classes: buttons, headings, text sizes, font weights, icons, section padding |

**Design token conventions used:**
- Fluid sizing: `clamp(min, preferred, max)` throughout
- Colors: `var(--color-{name})`, hover: `var(--color-{name}-hover)`, tints: `var(--color-{name}-tint-{1-9})`
- Spacing: `var(--space-{scale})` (scale: 7xs → 6xxl)
- Typography: `var(--h1)` through `var(--h6)`, `var(--text-xxl)` through `var(--text-xs)`

---

## 8. Key Resources

- [Template Library — Bricks Academy](https://academy.bricksbuilder.io/article/template-library/)
- [An Intro To Templates — Bricks Academy](https://academy.bricksbuilder.io/article/an-intro-to-templates/)
- [Template Settings — Bricks Academy](https://academy.bricksbuilder.io/article/template-settings/)
- [Remote Templates — Bricks Academy](https://academy.bricksbuilder.io/article/remote-templates/)
- [Components — Bricks Academy](https://academy.bricksbuilder.io/article/components/)
- [BricksSync Documentation](https://brickssync.com/brickssync-documentation/)