# 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/`