Add CLAUDE.md, research notes, and project scaffolding

- CLAUDE.md: project purpose, structure, conventions, design system summary, template format, global class reference, workflow for processing Bricks exports, and plans/research directory pointers - .claude/research/bricks-research.md: Bricks Builder technical notes - .claude/plans/: empty staging folder for future implementation plans - .gitignore: add settings.local.json and *.tmp.* exclusions Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-02-27 15:48:38 -06:00
parent dbbcfa27dd
commit 7f538a0132
4 changed files with 263 additions and 0 deletions
--- a/.claude/plans/.gitkeep
+++ b/.claude/plans/.gitkeep
--- a/.claude/research/bricks-research.md
+++ b/.claude/research/bricks-research.md
@@ -0,0 +1,173 @@
+# 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/)
--- a/.gitignore
+++ b/.gitignore
@@ -1 +1,3 @@
 Updated_Sections/
+.claude/settings.local.json
+*.tmp.*
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,88 @@
+# CLAUDE.md — BCW Bricks Templates
+
+## Project Purpose
+
+A structural boilerplate kit for Bricks Builder (WordPress). Templates are pure layout scaffolding — no decorative styling, colors, or brand content baked in. Drop them into a project, fill with client content, and the design system handles the rest.
+
+## Repository Structure
+
+```
+sections/        — section templates (8)
+headers/         — header templates (3)
+footers/         — footer templates (2)
+design/          — importable design system files (import before templates)
+bundles/         — bcw-starter-kit.zip for bulk import
+Updated_Sections/— gitignored staging area for raw Bricks exports
+.claude/
+  research/      — technical research and reference notes
+  plans/         — implementation plans for larger tasks
+```
+
+## Design System
+
+See `design/design.md` for the full variable reference. Always update `design.md` when making any changes to the design system files.
+
+**Variable naming:**
+- Colors: `--color-{name}` — primary/secondary/tertiary + light/dark, text, heading, bg, bg-alt, white
+- Spacing: `--space-{size}` — xs (8px) → 2xl (96px)
+- Typography: `--h1`–`--h6`, `--text-sm`/`--text-base`/`--text-lg`/`--text-xl`
+
+**Import order on a new project:**
+1. `design/bcw-css-variables.json` → Bricks Settings → Custom CSS → Variables
+2. `design/bcw-color-palette.json` → Bricks Settings → Color Palettes
+3. `design/bcw-global-classes.json` → Bricks Settings → Global Classes
+4. Then import any templates
+
+**Before importing on a real project:** replace the grey placeholder hex values in `bcw-css-variables.json` with the client's brand colors.
+
+## Template JSON Format
+
+Templates use a minimal hand-crafted format — not the full Bricks export format:
+
+```json
+{
+  "title": "BCW — Template Name",
+  "type": "section|header|footer",
+  "templateType": "section|header|footer",
+  "global_classes": [...],
+  "content": [...]
+}
+```
+
+- Sections use `"content"`, headers use `"header"`, footers use `"footer"`
+- Element IDs are readable (`sec001`, `con001`, `hdg001`) — not random hashes
+- `global_classes` is only present if the template references a class via `_cssGlobalClasses`
+- All headers and footers have `var(--color-primary)` set as background on their outer section element
+
+## Global Class Conventions
+
+Class IDs are descriptive (id == name). Current classes:
+
+| ID                   | Purpose                                           |
+| -------------------- | ------------------------------------------------- |
+| `section-container`  | Outer section wrapper — column, 40px gap          |
+| `section-header`     | Centered heading block — column, center, 16px gap |
+| `col-3`              | 3-column row, 32px gap, stacks mobile             |
+| `col-4`              | 4-column row, 24px gap, stacks mobile             |
+| `features-container` | Feature column — text-center, 10px row-gap        |
+| `footer-sub-section` | Footer column — 15px row-gap                      |
+
+## Workflow: Processing Bricks Exports
+
+When a template is updated and exported from Bricks:
+1. The raw export lands in `Updated_Sections/` (gitignored)
+2. Extract only the structural changes (layout, classes, new elements)
+3. Apply them to the existing repo file — preserve BCW placeholder text, discard client content
+4. Add/update `global_classes` array and `_cssGlobalClasses` references if new classes were introduced
+5. Delete the file from `Updated_Sections/` once processed
+
+## Philosophy
+
+- **Boilerplates, not finished sections.** Every template should be immediately extendable without fighting pre-baked styles.
+- **Structural only.** No hardcoded colors, decorative borders, font sizes, or shadow. Let the design system and Bricks global styles do that work.
+- **Avoid redundancy.** Before adding a template, ask whether it can be reasonably built by extending an existing one in under a minute. If yes, don't add it.
+
+## Plans and Research
+
+- Implementation plans for larger tasks: `.claude/plans/`
+- Technical research and Bricks-specific notes: `.claude/research/`