diff --git a/.claude/plans/.gitkeep b/.claude/plans/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/.claude/research/bricks-research.md b/.claude/research/bricks-research.md new file mode 100644 index 0000000..5e3d5b2 --- /dev/null +++ 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/) diff --git a/.gitignore b/.gitignore index 7b6aa86..0aa05d4 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,3 @@ Updated_Sections/ +.claude/settings.local.json +*.tmp.* diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..fd012c5 --- /dev/null +++ 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/`