# Bracen brand and design system (full text)

Published from docs/design-system in the Bracen repository. Authority order: README, foundations, brand, components, page-families. Hosted at https://brand.bracen.com. Generated 2026-10-23T00:03Z.


---

<!-- docs/design-system/README.md -->

# Bracen brand and design system

**Version 1.1**
**Completed:** 4 September 2026
**Owner:** Cameron Upton
**Status:** Canonical for Bracen and every market surface.

Start here before changing a public page, component, visual asset or interface string. This kit defines the brand and design contract. Production code implements it; the external Claude Design project is a visual workbench, not a second authority.

## Authority order

When sources disagree, the higher source wins:

1. This index and the locked decisions below.
2. [`foundations.md`](foundations.md), [`brand.md`](brand.md) and [`components.md`](components.md).
3. [`page-families.md`](page-families.md) for route composition and states.
4. Semantic tokens and shared production components in `src/app/globals.css`, `src/components/layout` and `src/components/content`.
5. Route-local CSS or Tailwind utilities.
6. Historical notes, screenshots and external explorations.

If code diverges from a locked rule, log and resolve the implementation gap. Do not rewrite the kit to legitimise accidental drift.

**Hosted copy:** [brand.bracen.com](https://brand.bracen.com) publishes this kit verbatim (`/kit/*.md`, `/llms-full.txt`, `/tokens.json`) for people and AI agents. Publish with `brand/build.sh --deploy` after a kit change; see [`../../brand/README.md`](../../brand/README.md).

**Claude Design pointer:** project `b7635a1c-32de-46e3-bde3-db24aa8756bb`, recorded in [`.design-sync/config.json`](../../.design-sync/config.json). The project informed this kit. These versioned files are the durable source of truth.

## The system in one page

- Bracen is an independent building decision platform, organised around **confidence before commitment**.
- The homeowner is the character; Bracen is the guide and evidence layer.
- `/` explains the global brand. `/nz` delivers the New Zealand journey. Builders Near Me remains acquisition/SEO context, not a competing visual brand.
- The wordmark is live text: **Bracen**, uppercase B, IBM Plex Sans Bold, with no symbol.
- IBM Plex Sans is the sole normal Bracen typeface.
- Navy and warm paper establish the editorial register. Blue is the only brand/action colour. Sand is scarce emphasis. Green is functional status only.
- Prefer real, permissioned NZ photography, ruled indexes and visible methodology to software-style cards or decorative UI.
- One dominant action per cluster. The homepage uses `Find my next step` primary and the online estimate secondary.
- Every claim, ranking, image and number carries an evidence boundary appropriate to its certainty.

## Document map

| File | Owns |
|---|---|
| [`brand.md`](brand.md) | Positioning, audience, architecture, wordmark, voice and imagery |
| [`foundations.md`](foundations.md) | Colour, verified contrast, typography, layout, spacing, shape, motion and icons |
| [`components.md`](components.md) | Actions, navigation, forms, evidence, comparisons, rows/cards, tables, disclosures and states |
| [`page-families.md`](page-families.md) | Eight page families, jobs, structures and required states |
| [`authority-map.md`](authority-map.md) | Code owners and change path |
| [`tokens.md`](tokens.md) | Compatibility pointer to foundations |
| [`rules.md`](rules.md) | Compatibility pointer to brand/components |

[`../branding-ux-notes.md`](../branding-ux-notes.md) is historical rationale. [`../strategy/26-bracen-homepage-design-system-closeout-2026-09-03.md`](../strategy/26-bracen-homepage-design-system-closeout-2026-09-03.md) records the implementation closeout. Neither overrides this kit.

## Locked decisions

Change these only through an explicit decision recorded in `docs/decision-log.md` and `docs/changelog.md`:

- Brand promise, homeowner-first role and Bracen/market architecture.
- Text-only `Bracen` wordmark and casing; no mascot or logo symbol.
- IBM Plex Sans as the normal product/editorial family.
- Blue as sole action colour, sand as scarce emphasis, green as functional status.
- Core palette, type roles, 1240px container, 68ch reading measure and spacing/radius roles.
- Real-image provenance rules and the ban on fake project imagery.
- Evidence, commercial disclosure and ranking separation.
- Accessibility floor: visible focus, 44px targets, labelled controls, keyboard use, contrast and reduced motion.
- The anti-SaaS rules: no repeated floating cards, capsule CTA system, decorative dashboards, feature-icon grids or generic gradients.

## Provisional implementation layers

The rule is settled, but these need shared code or assets:

| Layer | Current position | Definition of done |
|---|---|---|
| Form primitives | Shared field, label, help and error classes now govern public lead and estimate forms | Extract React wrappers when a third interaction pattern needs them |
| Evidence/ruled-row primitives | Shared CSS primitives now serve comparison, directory, guide and conversion families | Extract React wrappers only where semantics and behaviour are identical |
| Accordion primitive | Native behaviour specified | Shared details/summary styling with keyboard QA |
| Header consolidation | Global/NZ home and inner pages still have separate markup | One responsive shell without changing route behaviour |
| Owned photography library | Policy complete; assets limited | Governed registry and roughly 40 approved NZ images |
| Route-family refinement | Core public families now use the shared visual grammar; deeper profile and editorial variants remain | Each remaining variant passes its family brief and visual QA |

Provisional does not mean teams may invent alternatives. Build to the rule, then improve the shared implementation.

## Completeness assessment

| Layer | Evidence | Kit state |
|---|---|---|
| Strategy and audience | `brand.md` position and audience sections | Complete |
| Brand/market architecture | Global, NZ and Builders Near Me roles | Complete, locked |
| Identity | Exact wordmark case, family, weight, spacing and prohibitions | Complete, locked |
| Colour | Semantic roles, prohibited uses and contrast table | Complete, locked |
| Typography | One family and full role scale | Complete, locked |
| Layout and spacing | Container, measure, gutter, grid, rhythm and breakpoints | Complete |
| Shape and elevation | Role-based radii, border/shadow rule | Complete |
| Motion and icons | Timings, reduced motion, line-icon rules | Complete |
| Components and states | Component contracts plus interaction acceptance | Complete; some shared classes provisional |
| Page templates | Eight family briefs covering all public routes | Complete |
| Voice and microcopy | Voice, terminology, uncertainty and banned language | Complete |
| Imagery | Provenance, AI/stock boundary, crop, caption, alt and performance | Rules complete; owned asset library outstanding |
| SEO/editorial | Answer-first structure, route ownership, sources/method and canonical depth | Complete |
| Accessibility | Contrast receipts, focus, targets, keyboard, states and QA widths | Complete; implementation audit ongoing |
| Governance | Authority, versioning, change protocol and release gate | Complete |

**Conclusion:** the brand kit is complete enough to be the production authority. The remaining items are implementation and asset backlogs, not unresolved brand decisions.

## Design-to-code map

| Role | Current code |
|---|---|
| Global palette, radii, type family, shared actions and article body | `src/app/globals.css` |
| Font loading | `src/app/layout.tsx` |
| Flagship global/NZ composition | `src/app/page.tsx`, `src/app/nz/page.tsx`, `src/app/nz/home.module.css` |
| Inner-page header/footer | `src/components/layout/Header.tsx`, `Footer.tsx` |
| Ranked comparison | `src/components/content/LanePageTemplate.tsx`, `src/lib/lane-page-content.tsx` |
| Builder profile | `src/app/nz/builders/[slug]/page.tsx` and `profile.module.css` |
| Guide template | `src/app/nz/guides/[slug]/page.tsx` |
| Estimate journey | `src/app/nz/estimate`, `src/components/instant-estimate` |
| Report exception | `src/app/nz/report/layout.tsx` and namespaced `report-*` tokens |

New shared UI should use semantic tokens and named shared components. Do not add raw brand hex values or a new visual register to a route file.

## Change protocol

1. Identify the page family and customer job.
2. Read the relevant brand, foundation and component sections.
3. Add or change a semantic token/shared primitive before using a one-off local value.
4. Preserve content, metadata, structured data, forms, analytics, CRM and route behaviour unless explicitly in scope.
5. Update the kit and code in the same change when a locked rule deliberately changes.
6. Record a major/minor version bump in the changelog: major for identity/palette/type/architecture; minor for a new component or resolved provisional layer.
7. Run the release gate below.

## Release gate

- One H1 and logical heading order.
- Existing full, partial, empty, loading and error states still render.
- Semantic tokens/components used; no new raw brand hex or accidental type system.
- One dominant action per cluster and clear lower-commitment alternative.
- Metadata, canonical, JSON-LD, index rules, redirects and internal links preserved unless deliberately changed.
- Forms retain identifiers, payloads, validation, analytics, CRM and dedupe behaviour.
- Evidence, dates, sources and commercial relationships are visible where relevant.
- Image source, permission, caption/alt and responsive crop are recorded.
- No horizontal overflow at 320, 375, 768 or 1280px.
- Keyboard path, focus visibility, 44px targets, contrast and reduced motion pass.
- Type check, lint, build, route smoke and representative visual QA pass.

## Implementation and asset backlog

1. Consolidate the global/NZ homepage shell and inner-page shell without changing their route jobs.
2. Continue replacing route-local utilities with the shared form, evidence and ruled-row primitives where repeated semantics justify it.
3. Extract a shared disclosure component after its use expands beyond the comparison family.
4. Complete keyboard and boundary-contrast QA for authenticated/admin controls; the public conversion paths are aligned.
5. Replace licensed bridge photography with the governed first-party NZ library over time.
6. Add explicit provenance records for existing Supabase builder/project images.
7. Continue family-by-family visual QA and measurement rather than starting another identity pass.


---

<!-- docs/design-system/foundations.md -->

# 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.


---

<!-- docs/design-system/brand.md -->

# Bracen brand

**Version:** 1.0
**Status:** Strategy, architecture, identity and voice locked. Photography policy locked; the owned library is an asset backlog.

## Position

Bracen is an independent building decision platform. It helps homeowners understand likely costs, plan the right questions, evaluate options and choose who to contact before commitment.

The organising promise is **confidence before commitment**. The useful customer outcome is: **Know what you are getting into before you build.** Bracen is not merely a builder directory and does not lead with “find and compare builders”. Discovery is one useful downstream step in a larger decision journey.

The brand should feel calm, protective, specific, editorial and grounded in real construction. It must not feel like a SaaS dashboard, a generic property-tech template, a lead-auction marketplace or a luxury architecture magazine.

Reference patterns, never copied styling:

- ArchiPro for real project photography and assured whitespace.
- Consumer Reports and Which? for methodology and comparison hierarchy.
- GOV.UK-style clarity for forms and uncertainty.
- BuildHub for answer-first pages, linked supporting questions and visible ranking order, while improving its imagery, spacing and type consistency.

## Audiences

| Audience | Primary need | What loses trust |
|---|---|---|
| Homeowner planning a build or renovation | Clear costs, risks, next steps and honest evidence boundaries | Hype, vague claims, false precision and bidding-war framing |
| Builder managing a listing | Fair terms, accurate representation and clear commercial separation | Paid status presented as approval or rank |
| Industry, media and research reader | Dated data, method, provenance and limitations | Undated claims or unexplained numbers |

The homeowner is the primary character. Bracen is the guide and evidence layer, not the hero. A mascot is not part of the identity.

## Brand and market architecture

- **Bracen** is the parent brand and global product system.
- `/` is the global brand homepage.
- `/nz` is the New Zealand market surface and current complete homeowner journey.
- Builders Near Me is the inherited NZ acquisition, domain and SEO context. Preserve relevant URLs, attribution and high-intent language without presenting it as a second visual brand.
- Future `/au` content must use the same identity but cannot launch until its local data, content and operational gates are met.

One header carries one Bracen wordmark. Market context such as `NZ`, `New Zealand` or `Global` is a quiet text label, not a second logo.

## Wordmark

The wordmark is live text: **`Bracen`**.

| Property | Rule |
|---|---|
| Case | Uppercase B, lowercase remainder |
| Typeface | IBM Plex Sans Bold (700) |
| Tracking | `-0.045em` |
| Size | 25px mobile, 28px desktop; never below 16px |
| Colour | Navy/ink on light; white on a compliant dark field |
| Clear space | At least one cap height around the standalone wordmark |

Do not add a symbol, monogram, shield, house, brace glyph, avatar or alternate lockup. Do not set `BRACEN`, `bracen` or `BraCen`. Do not render it as an image when live text works. No gradient, outline, shadow, box or texture.

## Voice and content

Voice is direct, protective and specific. Write as an informed party on the homeowner's side of the table.

- Use New Zealand English on `/nz`.
- Prefer concrete nouns: quote, consent, contract, deposit, site visit, `$/m²` and Code Compliance Certificate.
- One idea per sentence. State limits beside the claim they qualify.
- “You” is the homeowner. “We” is Bracen.
- No emoji and no em dashes in product copy.
- Avoid hype such as `revolutionary`, `unlock`, `game-changing`, `best-in-class`, `hassle-free` and `dream home`.
- Avoid manufactured urgency and multi-builder competition language.
- Never state `winner`, `best overall` or `editor's choice` without the visible method and support for that exact claim.

| Situation | Pattern |
|---|---|
| Unknown | `Not checked`, `Not available`, `Not published` |
| Verification | State what was checked, source and date |
| Indicative figure | Range, region, date, units, basis and uncertainty |
| Primary action | Verb plus object: `Get an estimate` |
| Error | What happened, what remains safe, next action |
| Commercial relationship | Plain disclosure adjacent to the affected content |

## Imagery

Priority order:

1. Permissioned builder/project imagery with recorded attribution.
2. First-party NZ project, people, process and detail photography with usage rights.
3. Licensed NZ editorial photography that cannot be mistaken for a listed builder's work.
4. A deliberate type-led or abstract construction placeholder.

AI imagery may illustrate an abstract concept only when clearly labelled. It must not depict a house, room, site, builder or project as if it were real. Do not use stock handshakes, generic foreign architecture or unsourced dream-home renders.

Crop buildings with verticals intact and avoid cutting rooflines or people awkwardly. Heroes use 3:2 or 16:9, rows 3:2 and grids 4:3 or 1:1. Do not apply heavy filters or misleading colour grades. Real-project captions name what is shown and only include builder/location attribution when governed. Alt text describes the frame and its relevance, not the article title. Use `next/image`, explicit dimensions and responsive sizes.

The missing owned photography library is an asset backlog, not an unresolved design rule. Target roughly 40 governed NZ images across homes, builders at work, process, materials and details. Each asset needs source, permission basis, location, subject, approved crops, caption and alt-text record.


---

<!-- docs/design-system/components.md -->

# Bracen component contracts

**Version:** 1.0
**Status:** Canonical behaviour and visual roles. A component marked provisional still requires extraction into a shared implementation.

Every interactive control has a visible label, a minimum 44px target, keyboard access, a visible focus state and a disabled/loading state where relevant. State is not communicated by colour alone. Standard transitions are 160ms and must collapse under reduced motion.

## Actions and links

### Primary button

Use for the dominant next step within an action cluster. Blue background, white text, 3-4px radius, 44px minimum height and a darker blue hover/pressed state. Loading changes the label to a present-tense verb, sets `aria-busy` and prevents a duplicate submission.

### Secondary button

Use for a genuinely useful lower-commitment alternative. White or paper background, navy text and a zinc-400 boundary. It must not look equal to the primary action. Green and sand are never button colours.

### Text link

Body links are blue and underlined. Navigation or card-title links may omit the default underline where position makes the affordance obvious, but require a hover/focus cue. External-link meaning cannot depend on an icon alone.

Rules:

- One dominant action per cluster. A sticky/header action may coexist with a page action, but the page must not present two equal primary choices.
- No capsule CTA, gradient fill, bounce, icon-only primary action or button used merely as navigation decoration.
- The homepage hierarchy is `Find my next step` primary, `Get an online estimate` secondary.

Shared implementations: `.bracen-button-primary` and `.bracen-button-secondary`. Homepage modules implement the same roles locally pending consolidation.

## Navigation

The shared header contains the text-only Bracen wordmark, quiet market context, the minimum useful information architecture and one estimate action. Desktop dropdowns are functional popovers, so a restrained shadow is permitted. Active, hover and focus states need a non-colour cue as well as colour.

Mobile uses the same destinations and labels rather than inventing a second navigation model. Opening a menu updates `aria-expanded`; keyboard focus remains inside the visible flow and returns to the trigger on close. Footer groups routes by customer task and carries editorial/commercial disclosure where relevant.

Current implementation: `src/components/layout/Header.tsx`, `Footer.tsx`, plus the global and NZ homepage shells. Consolidating the bespoke homepage headers into shared primitives is implementation debt, not permission for a second identity.

## Forms and decision tools

**Visual primitive extraction is provisional; behaviour is locked.**

- Visible label above every field. Placeholder is never the label.
- White field, 3-4px radius, zinc-400 boundary and 44px minimum height.
- Help text follows the field; error text follows help and is connected with `aria-describedby` and `aria-invalid`.
- Error copy says what is wrong and how to recover; do not rely on a red border.
- A wizard presents one coherent question group per step, with blue progress and plain back/continue actions.
- Completion may use green. Evidence never uses green.

Restyling must preserve survey IDs, service variants, Google Places mode, validation, calculations, payloads, analytics, GHL tags, deduplication and form DOM contracts. A real `<form>` is for real lead capture only so third-party form detection does not misclassify utility controls.

## Evidence, alerts and status

Evidence is an inline, dated statement of what was checked, against which source, and when. Unknown states use plain language such as `Not checked` or `Not published`.

| Role | Surface | Text | Use |
|---|---|---|---|
| Evidence/information | Blue wash with blue rule | Navy | Method, provenance, checked fact |
| Positive | Pale neutral/green support | Green plus text | Completed task or confirmed positive state |
| Caution | Sand/pale sand | Navy or accessible amber | Limitation or decision note |
| Error | White/paper | Error red plus text | Failure and recovery action |

Badges state a fact with a date. A compact pill is allowed for status or market context only. Payment never implies approval or ranking. Do not expose private contact, owner/source fields, NZBN/LBP numbers or insolvency data. Association names remain neutral in public claims.

### Badges (off-site profile badges)

The design kit file `components/badges/ProfileBadge.jsx` is the visual authority for badges a
builder places on their own site; `src/lib/badge-kit.ts` renders it as static SVG. Claims are
`listed`, `featured` (cited by name in the linked guide) and `checked`; variants are `bar`
(default), `card` and `inline`, each light or dark. Status badges carry no date because the check
date and current status live on the linked Bracen page. `topRated` and award claims exist in the
kit as proposals and are not rendered until the ranking methodology is signed off. No text below
14px at 1x.

## Ranked comparison result

- Show selection criteria, evidence boundary, update date and commercial disclosure before the first result.
- Number one may receive one sand treatment when the documented method supports its position.
- Lower ranks remain quieter; no trophies, medals or score-gauge theatre.
- Paid placement is labelled, unnumbered and visually separate. It cannot receive the number-one treatment.
- Visible order and `ItemList` structured-data order match.
- A short cost/licensing/consent answer is useful when it links to the canonical deep guide; do not duplicate the full guide.

Current implementation: `src/components/content/LanePageTemplate.tsx` and `src/lib/lane-page-content.tsx`.

## Rows, cards and media

Prefer a ruled row for directory listings, guide indexes and related links. Use a flat bordered panel only where content forms one enclosed unit. Shadow is reserved for overlays/popovers or an exceptional raised object. A content block never combines border and shadow.

Cards are not banned, but repeated floating cards are the SaaS-template signal the system avoids. Builder rows stack image, identity, evidence and action in that order on mobile.

Media uses a 3-4px radius and a neutral backing. When there is no governed image, use an honest typographic/abstract placeholder rather than a misleading stock project.

Current global primitives: `.bracen-card`, `.bracen-page-shell`, `.bracen-page-hero` and route-specific ruled structures. A shared row/evidence primitive remains to be extracted.

## Tables

- Full width, left aligned, top aligned, ruled rows and tabular numerals for numeric columns.
- The caption or introducing sentence states what is compared and the relevant date/region.
- Units remain visible.
- Reflow to a definition list on mobile where possible; horizontal scrolling is acceptable only for a true comparison that cannot reflow.
- Headers may use a short uppercase micro style; body stays at least 14.5px.

## Accordions and disclosure

Use native `<details>`/`<summary>` for FAQs and secondary detail. Do not hide price, a material limitation or the primary decision behind an accordion. The summary is a full-width 44px target. Open state uses both a chevron and a weight/rule change. Structured-data answers remain in the DOM.

The pattern is locked; a dedicated shared class remains provisional.

## Empty, loading and error states

| State | Contract |
|---|---|
| Empty | State the fact, then offer the useful alternative route. No joke or decorative illustration. |
| Loading | Skeletons match final dimensions to prevent layout shift. Avoid a spinner where a skeleton communicates better. |
| Error | State what happened, what was not changed and the next safe action. One recovery action, optional secondary route. |

All states keep Bracen chrome and voice. Global `not-found` and `error` pages follow the same pattern.

## Interaction acceptance

For every component verify default, hover, focus-visible, active/pressed, disabled, loading, error and success states where applicable. Test keyboard order, 44px targets, contrast, 320/375px reflow and reduced motion. Automated checks support but do not replace visual and keyboard QA.

## Anti-patterns

- Large rounded cards, capsule CTAs, decorative gradients, glass, glows and dashboard widgets.
- Blue and green as co-primary actions.
- Feature-icon grids or oversized spot icons.
- Equal-weight CTA clusters.
- Decorative badges implying unsupported proof.
- Long unbroken article walls or alternating coloured sections with no semantic job.


---

<!-- docs/design-system/page-families.md -->

# Bracen page-family briefs

**Version:** 1.0
**Status:** Canonical route-composition contract.

Every public route belongs to one family. Families share identity, foundations and component rules but may vary composition according to their customer job. A new route does not create a ninth style unless none of these jobs fits.

## 1. Brand and market home

**Routes:** `/`, `/nz`, future `/au`
**Job:** Explain Bracen, make the promise clear and route the visitor to the right next decision.

Required: market context, one H1/value proposition, decision router, evidence/research moment, useful internal discovery, builder path and one closing action. `/` stays global; `/nz` owns local cost, consent, guide and builder pathways. `Find my next step` is primary and the online estimate secondary. The H1 does not need the brand name when the wordmark/eyebrow supplies identity.

Hero imagery must be real and attributable. If a suitable image is unavailable, use a strong type-led composition rather than generic foreign property imagery.

## 2. Editorial guide and comparison

**Routes:** `/nz/guides`, `/nz/guides/[slug]`, `/nz/master-build-guarantee`, `/nz/best-*`
**Job:** Answer a defined question, earn trust and move the reader to one useful next step.

Required: answer-first opening, author/reviewed date, contents for long pages, readable 68ch body, sources/method, limitations, related questions and one contextual CTA. Use coloured backgrounds only for evidence, caution or a single key takeaway.

Comparison variant: criteria and disclosure above the ranking, visible and structured-data order aligned, restrained sand treatment for number one only, paid placement unnumbered and separate. Include short cost/licensing/consent context that links to the canonical deep guide. Do not show a `client share` or similar internal/commercial percentage unless it is explicitly meaningful to the homeowner and methodologically defensible.

## 3. Service and location discovery

**Routes:** `/nz/[service]`, `/nz/[service]/[region]`, `/nz/builders-in/[region]`
**Job:** Own builder-discovery intent while helping the homeowner understand fit and coverage quality.

Required: query-matched H1, concise service/location context, visible result count and evidence boundary, image-led horizontal builder rows, clear sparse/empty states, related services/regions and contextual links to costs, consent and guides. Coverage state must remain visible and index/noindex rules must not be disguised by styling.

## 4. Builder profile

**Route:** `/nz/builders/[slug]`
**Job:** Help a homeowner assess one company without overstating verification.

Required: identity, region/services, source status and dates near the top, explicit unknowns, governed projects/images, review provenance, credentials in neutral language, service areas, related builders and one relevant enquiry. Support rich, sparse, claimed, unclaimed, rated, unrated and unavailable states. Never expose private data or let payment imply approval.

Profile implementation: `src/app/nz/builders/[slug]/page.tsx` and `profile.module.css`.
Use a full-width photographic hero with white identity text and an 80% black overlay, followed by a
compact directory-facts strip, in-page section links and a framed single-builder enquiry. The
profile body uses white. This route treatment follows Cameron's explicit 23 October 2026 direction.
Use an explicitly stored cover when available; otherwise use the existing Bracen NZ framing image
with a visible illustrative-image credit. Scraped social images do not become covers automatically.
Record-update dates must not be labelled as verification dates.

## 5. Cost guide and calculator

**Routes:** `/nz/cost-guides`, `/nz/[service]/cost`, `/estimate`, `/nz/estimate`, `/au`, `/au/guides/[slug]`, `/au/estimate`, approved future calculators
**Job:** Give an immediate useful range while showing its assumptions and uncertainty.

Required: answer/range in the first viewport, market currency (NZD or AUD, stated), region/date/units, scope qualifiers, method/source, calculator or scenario where governed, limitations, FAQ and next step. A comparison or service page may carry a short answer but the cost guide owns the canonical depth. Preserve calculations, validation, payloads, CRM and analytics during visual work.

## 6. Data report

**Routes:** `/nz/report` and report issues/regions
**Job:** Publish defensible market intelligence that can be cited and shared.

Required: issue/date masthead, findings before commentary, charts/tables with units, source and methodology, limitations, citation/share affordance and related homeowner decision. The report may use its namespaced publication palette/type exception but must retain Bracen identity and interaction accessibility.

## 7. Product and conversion

**Routes:** `/nz/plan-your-project`, `/nz/feasibility`, `/nz/claim`, `/nz/pricing` and their confirmed global equivalents
**Job:** Complete a concrete homeowner or builder task without looking like a generic dashboard.

Required: outcome-first header, clear scope and expectations, one action, progress where multi-step, privacy/lead-use copy, validation, result boundary and success/error states. Preserve all identifiers, query parameters, directory lookup, checkout hooks and event contracts. An incomplete payment path must look unavailable, not live.

## 8. Utility and governance

**Routes:** editorial/about, privacy, terms, methodology, contact, not-found, loading and error
**Job:** Make standards, obligations and recovery actions easy to read.

Required: shared chrome, one-column reading measure, explicit effective/updated date, accountable contact where relevant and one safe recovery action for errors. No marketing-card grid or decorative illustration is required.

## Shared release checks

- One H1 and logical headings.
- Full, partial, empty, loading and error states remain truthful.
- Metadata, canonical, JSON-LD, index rules, redirects, internal links, forms and analytics are preserved unless explicitly changed.
- Evidence uses words and dates, not colour alone; commercial relationships are adjacent to what they affect.
- Every image has a known source, permission basis, alt/caption decision and responsive crop.
- No overflow at 320, 375, 768 or 1280px; keyboard, focus, 44px targets, contrast and reduced motion pass.


---

<!-- docs/design-system/authority-map.md -->

# Bracen design authority map

**Updated:** 4 September 2026

The governing order is defined in [`README.md`](README.md). In short: the versioned kit owns design decisions; production code implements them; external Claude Design work and screenshots are references until reconciled into this kit.

| Decision | Authority |
|---|---|
| Brand, architecture, wordmark, voice, imagery | [`brand.md`](brand.md) |
| Colour, type, spacing, grid, shape, motion, icons | [`foundations.md`](foundations.md) |
| Component roles and states | [`components.md`](components.md) |
| Route jobs, composition and required states | [`page-families.md`](page-families.md) |
| Homepage SEO and proposition | `docs/strategy/25-nz-market-homepage-strategy-and-handoff.md` where it does not conflict with the kit |
| Live implementation | `src/app/globals.css`, shared components and route templates |
| External visual workbench | Claude Design project in `.design-sync/config.json` |

When code and the kit differ, log the gap and fix the shared implementation. Do not create a local exception or silently change the design rule.