# BCW Design System Reference

Three importable files. **Import in this order** before any templates:

1. `bcw-css-variables.json` — defines all custom properties
2. `bcw-color-palette.json` — adds named swatches to the Bricks color picker
3. `bcw-global-classes.json` — adds shared layout classes

---

## Bricks Style Manager — Spacing

Bricks has a built-in Spacing section in the Style Manager that works well and should be kept enabled. One setting needs to match our design system:

- **Scale Steps** → set to: `2xs,xs,sm,md,lg,xl,2xl`
- **Baseline** → set to `sm`

This aligns the Style Manager's spacing scale labels with our `--space-*` CSS variable naming convention.

---

## How to Import

| File                      | Where to import                                          |
| ------------------------- | -------------------------------------------------------- |
| `bcw-css-variables.json`  | Bricks → Settings → Custom CSS → Variables → Import     |
| `bcw-color-palette.json`  | Bricks → Settings → Color Palettes → Import             |
| `bcw-global-classes.json` | Bricks → Settings → Global Classes → Import             |

---

## CSS Variables

All variables follow the pattern `var(--variable-name)`.

### Colors

Replace the placeholder grey hex values with the client's brand colors before importing.

| Variable                  | Default    | Purpose                                    |
| ------------------------- | ---------- | ------------------------------------------ |
| `--color-primary`         | `#374151`  | Main brand color. Used on headers, footers, and primary buttons. |
| `--color-primary-light`   | `#9CA3AF`  | Lighter variant. Use for hover states, borders, or secondary UI. |
| `--color-primary-dark`    | `#1F2937`  | Darker variant. Use for active states or deep accents.           |
| `--color-secondary`       | `#6B7280`  | Supporting brand color.                    |
| `--color-secondary-light` | `#D1D5DB`  | Light secondary. Good for dividers, subtle backgrounds.          |
| `--color-secondary-dark`  | `#4B5563`  | Dark secondary. Use for secondary hover/active.                  |
| `--color-tertiary`        | `#F3F4F6`  | Accent or background fill color.           |
| `--color-tertiary-light`  | `#FFFFFF`  | Lightest tertiary. Usually pure white.     |
| `--color-tertiary-dark`   | `#E5E7EB`  | Slightly deeper tertiary. Card backgrounds, borders.             |
| `--color-text`            | `#374151`  | Default body copy color.                   |
| `--color-heading`         | `#111827`  | Default heading color.                     |
| `--color-bg`              | `#FFFFFF`  | Main page background.                      |
| `--color-bg-alt`          | `#F9FAFB`  | Alternate section background (off-white).  |
| `--color-white`           | `#FFFFFF`  | Forced white — useful for text on dark backgrounds. |

**Usage example in Bricks:**
Set any color field to `var(--color-primary)`. When you rebrand, update the variable once and every element using it updates automatically.

---

### Spacing

A simple scale from extra-small to 2x-large. Use these in gap, padding, and margin fields.

| Variable       | Value   | Typical use                                      |
| -------------- | ------- | ------------------------------------------------ |
| `--space-xs`   | `8px`   | Tight internal gaps (icon to label, etc.)        |
| `--space-sm`   | `16px`  | Standard element gaps within a block             |
| `--space-md`   | `24px`  | Medium spacing — between content blocks          |
| `--space-lg`   | `40px`  | Section internal gap (header to content row)     |
| `--space-xl`   | `64px`  | Section top/bottom padding                       |
| `--space-2xl`  | `96px`  | Hero or large feature section padding            |
| `--row-gap`    | `15px`  | Default row gap between stacked elements         |
| `--col-gap`    | `15px`  | Default column gap between side-by-side elements |

**Usage example in Bricks:**
In any gap or padding field, type `var(--space-lg)` instead of a fixed pixel value.

---

### Typography

Heading and text size scale. Apply these in the font-size field of any text element or via Global Classes.

| Variable       | Value       | Purpose              |
| -------------- | ----------- | -------------------- |
| `--h1`         | `64px`      | Page-level heading   |
| `--h2`         | `48px`      | Section heading      |
| `--h3`         | `36px`      | Sub-section heading  |
| `--h4`         | `28px`      | Card or block heading|
| `--h5`         | `22px`      | Minor heading        |
| `--h6`         | `18px`      | Small label heading  |
| `--text-sm`    | `14px`      | Captions, footnotes  |
| `--text-base`  | `16px`      | Body copy (default)  |
| `--text-lg`    | `18px`      | Lead paragraph       |
| `--text-xl`    | `20px`      | Large intro text     |

---

## Color Palette

`bcw-color-palette.json` imports a "BCW" palette into the Bricks color picker. Every swatch references a CSS variable — so updating a variable updates the swatch automatically.

Swatches: `primary`, `primary-light`, `primary-dark`, `secondary`, `secondary-light`, `secondary-dark`, `tertiary`, `tertiary-light`, `tertiary-dark`, `text`, `heading`, `bg`, `bg-alt`, `white`

---

## Global Classes

`bcw-global-classes.json` imports shared layout classes. Apply them to container elements in the Bricks panel under **CSS → Classes**.

| Class                | Apply to                          | What it sets                                              |
| -------------------- | --------------------------------- | --------------------------------------------------------- |
| `section-container`  | Outermost section container       | `flex-direction: column`, `gap: 40px`, `margin: 15px top/bottom` |
| `section-header`     | Heading + subtitle block          | `flex-direction: column`, `align-items: center`, `gap: 16px` |
| `col-3`              | 3-column row container            | `flex-direction: row`, centered, `gap: 32px`, stacks on mobile |
| `col-4`              | 4-column row container            | `flex-direction: row`, centered, `gap: 24px`, stacks on mobile |
| `features-container` | Individual feature column (3 or 4 col) | `text-align: center`, `row-gap: 10px`               |
| `cards-grid`         | Fluid wrapping card row                  | `flex-wrap: wrap`, `align-items: stretch`, `gap: var(--col-gap)` — cards wrap to new rows automatically |
| `feature-card`       | Individual feature column (card variant) | `background: var(--color-bg-alt)`, `padding: var(--space-md)`, `border-radius: 8px`, `row-gap: 15px`, `max-width: 33%` (50% landscape, 95% portrait) |
| `footer-sub-section` | Footer column containers          | `row-gap: 15px`                                           |

**Note:** `features-container` and `footer-sub-section` are also embedded in the `features-3col`, `features-4col`, and `footer-columns` templates — importing those templates will bring these classes along automatically. `feature-card` is embedded in `features-3col-cards` and `cards`. `cards-grid` and `feature-card` are embedded in `cards` — importing that template brings both along. For the fluid card layout, each card element also has `_flexBasis: 280px` and `_flexGrow: 1` set inline so they fill the row and wrap to the next line automatically.