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