Bricks-Sections/CLAUDE.md

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:

{
  "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/