# Bracen foundations

**Version:** 1.0
**Status:** Canonical. Values labelled legacy are compatibility only.
**Implementation:** `src/app/globals.css` and `src/app/nz/home.module.css`.

This file defines the intended system. Production code implements it; code does not silently overrule it. Any deliberate exception must be recorded in the design-system backlog before release.

## Colour

### The three-colour law

| Colour | Role | Do not use it for |
|---|---|---|
| Bracen blue | Sole brand and action colour: wordmark, links, buttons, focus, progress and active navigation | Decoration or a co-primary palette |
| Positive green | Confirmed completion, verified status or genuinely positive movement | Brand identity, buttons, headings or general evidence |
| Sand | Scarce editorial emphasis: the first ranked result, one decision note or one cost callout | Buttons, alternating sections or repeated decoration |

Navy is the darkest blue register, used for ink, evidence and strong editorial bands.

### Core palette

| Semantic role | Token | Value | Use |
|---|---|---:|---|
| Paper | `--color-background` | `#fffefa` | Default page field |
| White | `--color-white` | `#ffffff` | Raised or contrasting light surface |
| Ink/navy | `--color-foreground` | `#0c1f45` | Wordmark, headings and primary text |
| Deep ink | `--color-black` | `#071630` | Exceptional maximum contrast |
| Muted text | `--color-muted` | `#5c687b` | Supporting text only |
| Bracen blue | `--color-primary` | `#1746b8` | Primary action, links and focus |
| Bracen blue pressed | `--color-primary-hover` | `#103584` | Hover and pressed action state |
| Blue wash | local semantic token | `#edf3ff` to `#f5f8ff` | Evidence and quiet action context |
| Warm sand | `--color-sand` | `#f2dfb8` | Scarce editorial emphasis |
| Sand pale | `--color-sand-pale` | `#fbf6ec` | Warm quiet surface |
| Positive green | `--color-success` | `#21765a` | Positive state only |
| Error red | local semantic token | `#a2473d` | Error or negative state with text |
| Rule | `--color-zinc-200` | `#d8dee7` | Decorative divider |
| Control rule | `--color-zinc-400` | `#7e8999` | Interactive boundary on white/paper |

The Building Report may use its namespaced publication palette. It still inherits the Bracen wordmark, interaction rules and accessibility requirements; its green does not become the product action colour.

### Verified contrast

Ratios use WCAG relative luminance. Normal text requires 4.5:1, large text 3:1 and essential non-text boundaries 3:1.

| Pairing | Ratio | Result |
|---|---:|---|
| Navy on paper | 16.04:1 | AAA |
| Bracen blue on paper | 7.99:1 | AAA |
| White on Bracen blue | 8.06:1 | AAA |
| Muted text on paper | 5.59:1 | AA |
| Positive green on paper | 5.47:1 | AA |
| Navy on sand | 12.35:1 | AAA |
| Bracen blue focus against paper | 7.99:1 | Passes non-text requirement |
| Zinc-400 control rule on white | 3.54:1 | Passes non-text requirement |

Do not use gold/yellow alone as a focus ring on paper: the former `#f4c54e` ring measured only 1.61:1. Colour is never the only signal for evidence, status or error; include words and, where relevant, a date.

## Typography

### Typeface

**IBM Plex Sans is the only Bracen typeface.** It owns the wordmark, display, body, navigation, UI, tables and figures in weights 400, 500, 600 and 700. This single-family decision is deliberate: hierarchy comes from scale, weight and spacing, not from adding another personality.

Fallback: `Arial, sans-serif`. Do not introduce Newsreader, Inter, Bricolage or another display family into normal Bracen pages. The Building Report's existing namespaced publication fonts are the sole current exception.

### Type roles

| Role | Size | Weight | Tracking | Leading |
|---|---|---:|---:|---:|
| Hero H1 | `clamp(2.4rem, 5.2vw, 5.15rem)` | 600 | `-0.060em` | 0.96-1.00 |
| Page H1 | `clamp(2.4rem, 4.5vw, 4.25rem)` | 600 | `-0.050em` | 1.00 |
| H2 | `clamp(2.2rem, 4.2vw, 4rem)` | 600 | `-0.052em` | 1.02 |
| H3 | `1.4375rem` | 600 | `-0.025em` | 1.20 |
| Lead | `1.125rem` to `1.25rem` | 400 | normal | 1.45-1.60 |
| Reading body | `1.0625rem` | 400 | normal | 1.78 |
| UI/body | `1rem` | 400-600 | normal | 1.60 |
| Small/supporting | `0.875rem` | 400-600 | normal | 1.50 |
| Eyebrow/micro | `0.75rem` | 700 | `0.12em` uppercase | 1.40 |

Use sentence case. Uppercase is limited to short eyebrows, status labels and table headers. Statistics use tabular numerals. Long-form measure is 68ch; utility prose may use a 48rem layout container.

## Layout, spacing and breakpoints

### Grid

- Maximum content width: **1240px**.
- Standard desktop gutter: **24px**; mobile gutter: **20px**. Dense utilities may use 16px at the smallest width, but must not create a second alignment line on the same page.
- Long-form measure: **68ch**.
- Use 12 columns for complex desktop compositions, 6 for tablet and 4 for mobile. Most pages only need a one- or two-column subset.

### Rhythm

| Context | Mobile | Desktop |
|---|---:|---:|
| Standard editorial section | 72px | 112px |
| Dense/decision section | 56px | 80px |
| Internal component spacing | 4, 8, 12, 16, 24, 32, 48, 64px | Same scale |

Do not improvise arbitrary spacing where an approved step works. Imported article HTML inherits the article rhythm rather than defining its own.

### Breakpoints and QA widths

Tailwind breakpoints remain `sm` 640, `md` 768, `lg` 1024, `xl` 1280 and `2xl` 1536px. Required visual QA widths are **320, 375, 768 and 1280px**. The 320px pass proves minimum resilience; 375px is the primary mobile composition check.

## Shape, borders and elevation

| Role | Radius | Use |
|---|---:|---|
| Small | 3-4px | Buttons, inputs, images and small media |
| Panel | 6px | Enclosed evidence, calculator and editorial panels |
| Popover | 8px | Menus, dialogs and exceptional floating UI |

Nothing new exceeds 8px. Legacy `rounded-2xl` and `rounded-3xl` utility aliases resolve to the 8px ceiling in the shared stylesheet; new work should still use the named role that communicates intent. Pills are limited to genuine compact status or market context.

Hierarchy order: whitespace, surface shift, fine rule, then shadow. A content component does not combine a border and a shadow. Shadows are allowed for popovers and overlays whose depth is functional.

## Motion

- Standard transition: **160ms ease** for colour, border and small state changes.
- Motion communicates state only. No entrance animation, parallax, auto-advancing carousel, decorative counters or bouncing CTAs.
- `prefers-reduced-motion: reduce` is mandatory. Collapse transitions and animations to effectively zero and disable smooth scrolling.

## Iconography and ornament

`lucide-react` is the approved line-icon source when an icon is genuinely useful. Use a 1.5px stroke at 16px inline, 20px in controls and 24px maximum. Icons support visible text; they do not replace it. Use `currentColor`, one colour and `aria-hidden="true"` for decorative icons.

No feature-icon grids, filled badges, multi-colour icons or illustrated SaaS spot graphics. The short blue brace rule/edge used beside an eyebrow or evidence block is the only recurring ornament.