# Homicity — Brand Guide

*A working reference for designers. Every value here is drawn from the live website's design system, so what you design will match what's already built. File paths point to the source assets in this repository.*

---

## 1. Brand at a glance

| | |
|---|---|
| **Name** | Homicity |
| **Tagline** | *The intelligence layer for real estate.* |
| **Founded** | 2015 (Canada) |
| **Flagship product** | Neighbourly.io — the real estate data API for Canada (10 data layers) |
| **What we are** | A real estate technology company: property data, mapping and market intelligence. We build the products and infrastructure that turn the built world into decisions. |

**Personality:** calm, precise, premium, trustworthy, editorial. Anthropic-inspired — warm and human, never cold "tech-blue." Confident but understated; data-driven and honest, never hypey.

**Design north star:** warm paper backgrounds, one restrained clay accent, serif headlines, generous whitespace, and clean line-art illustration. If a choice feels loud, it's wrong.

---

## 2. Logo & marks

**Source:** `components/logo.tsx` (exports `Logo`, `LogoMark`, `ICON_PATH`, `WORDMARK_PATH`)

### The mark
A set of concentric "signal" rings forming a house — signal radiating from a home, i.e. location intelligence. Natural aspect ratio **105 × 139** (taller than wide). Delivered as vector (SVG path), never rasterized.

### The lockup (primary logo)
`Logo` = the mark (in clay) + the word **"Homicity"** set in **Newsreader** (the brand serif), semibold, in ink.
- Mark colour: **Clay 600 `#bd6a4d`**
- Wordmark colour: **Ink 900 `#191817`**
- Wordmark font: Newsreader, weight 600, tight tracking
- Icon-to-word gap: ~10px at default size; icon height ~32px

> Note: the wordmark is **live text in Newsreader**, not an outlined path — keep it that way so it stays crisp and consistent with the site's headings. (A fully-outlined lockup path also exists as `WORDMARK_PATH` if a flattened asset is ever required.)

### The icon alone (`LogoMark`)
Use for favicons, app icons, avatars, compact spaces, or as a motif. Inherits `currentColor` (default it to clay). Never below ~20px tall on screen.

### Usage rules
- **Clear space:** keep at least the height of the mark's rings as padding on all sides.
- **Minimum size:** lockup ≥ 120px wide; mark ≥ 20px tall.
- **Backgrounds:** place on Ivory/Cloud/Linen (light warm) or an Ink dark panel. Not on busy imagery or saturated colour.
- **Don't:** recolour the mark outside the clay family, stretch/distort, add effects (shadows, bevels, gradients on the mark), swap the wordmark font, or box it in a coloured chip.

---

## 3. Favicon & app icons

All generated from one shared renderer: `lib/og-icon.tsx` (`brandIcon()`), which draws the **clay mark on a warm light tile `#f0eee6`**.

| Asset | Size | Source | Notes |
|---|---|---|---|
| Favicon | 32×32 | `app/icon.tsx` | rounded tile |
| Apple touch icon | 180×180 | `app/apple-icon.tsx` | full-bleed (iOS rounds it) |
| PWA icon | 192×192 | `app/icon-192.png/route.ts` | full-bleed / maskable safe zone |
| PWA icon | 512×512 | `app/icon-512.png/route.ts` | full-bleed / maskable |
| Web manifest | — | `app/manifest.ts` | name, `theme_color #cc785c`, `background_color #faf9f5` |

---

## 4. Colour

### Warm paper backgrounds — never pure white
| Token | Hex | Role |
|---|---|---|
| Ivory | `#faf9f5` | Primary page background |
| Cloud | `#f0eee6` | Section/secondary background, icon tiles |
| Linen | `#fffefb` | Card surfaces |
| Sand | `#e7e3d7` | Borders, dividers, hairlines |

### Clay — the signature accent (use sparingly, one focal point per view)
| Token | Hex | Role |
|---|---|---|
| Clay (DEFAULT / 500) | `#cc785c` | Primary accent, accent buttons, illustration primary |
| Clay 400 | `#d99a83` | Lighter accent, gradient end |
| Clay 600 | `#bd6a4d` | Hover, the logo mark |
| Clay 700 | `#a1543b` | Eyebrows, small labels, gradient start, illustration deep |

### Ink — warm near-black text scale (never pure `#000`)
| Token | Hex | Role |
|---|---|---|
| Ink 950 | `#0f0f0e` | Deepest |
| Ink 900 | `#191817` | Headings, primary text, dark panels |
| Ink 800 | `#26251f` | — |
| Ink 700 | `#3d3b34` | Emphasis body |
| Ink 600 | `#5c584d` | **Default body text** |
| Ink 500 | `#726d60` | Secondary text |
| Ink 400 | `#928d7e` | Muted captions/labels |

### Muted secondary accents (rare — never compete with clay)
Sky `#6b8ca3` (·400 `#8aa8bd`), Sage `#7d8f6f`.

### Signature gradient
`linear-gradient(to right, #a1543b → #cc785c → #d99a83)` (`from-clay-700 via-clay to-clay-400`). Used for small dots, tiny accents and text-gradient headers — not large fills.

### Dark panel
Feature/contrast sections use a gradient **Ink 800 `#26251f` → Ink 950 `#0f0f0e`** with a soft clay glow (`#cc785c` at ~25% opacity, heavily blurred) and Ivory text.

**Ratio guidance:** ~90% warm neutrals, ~8% ink text, ~2% clay. Clay marks the one thing you want the eye to land on.

---

## 5. Typography

Two families. Serif for display, sans for everything else.

### Newsreader — display / headings
- Google Font "Newsreader" (serif), normal + italic.
- Editorial, elegant, high-contrast.
- Headings: weight **500 (medium)**, occasionally 600. Tight tracking **≈ −0.02em**, line-height ~1.03–1.1.
- Used for: H1–H3, big numbers/stats, pull quotes, the logo wordmark.

### Inter — body / UI
- Google Font "Inter". Regular for body; **500 (medium)** for buttons, labels, nav.
- Body copy colour Ink 600; line-height ~1.6.

### Mono — data accents only
Any clean monospace (SF Mono / ui-monospace) for code, API paths, reference IDs.

### Eyebrow label (recurring motif)
Inter · **12px** · semibold · **UPPERCASE** · letter-spacing **0.18em** · colour **Clay 700**, usually preceded by a short clay hairline rule. Sits above section headings.

### Type scale (approx, responsive)
| Level | Size (desktop) | Font / weight |
|---|---|---|
| Display H1 | 48–60px | Newsreader 500 |
| H2 | 30–40px | Newsreader 500 |
| H3 | 18–20px | Newsreader 500 |
| Lead / subtitle | 18–20px | Inter, Ink 500 |
| Body | 14–16px | Inter, Ink 600 |
| Small / caption | 12–13px | Inter, Ink 400/500 |
| Eyebrow | 12px | Inter 600, uppercase, Clay 700 |

---

## 6. Iconography

- **Library:** Lucide (thin line icons). Keep stroke light and consistent.
- **Treatment:** icon in **Clay 700**, inside a rounded tile (`rounded-xl`, ~44px) with a **Cloud** or **Linen** fill and a **Sand** border. On dark panels, use a `clay/20` fill with Clay 400 icons.
- Don't mix icon styles (no filled/duotone alongside line icons).

---

## 7. Layout, spacing & shape

- **Content width:** max **1200px**, centered. Horizontal gutters 24px (mobile) → 32px (≥sm). Utility: `container-x`.
- **Breakpoints:** Tailwind defaults — sm 640, md 768, lg 1024, xl 1280, 2xl 1536.
- **Section rhythm:** generous vertical padding (typically 80–96px between major sections). Let content breathe.
- **Corner radii:** buttons `rounded-xl` (~12px); cards `rounded-2xl` (~16px); large panels/feature cards `rounded-3xl` (~24px). Nothing sharp-cornered.
- **Borders:** 1px **Sand** hairlines everywhere instead of heavy rules.
- **Backdrops:** faint warm grid (`bg-grid`, ink at ~5%, 64px cells) or dot grid (`bg-dots`, 22px) behind hero areas, faded out with a mask (`mask-fade-b` / `mask-radial`). Always subtle.

---

## 8. Elevation

Soft, warm, low-opacity shadows — never hard drop shadows.
- **Card hover:** `0 8px 40px -16px rgba(25,24,23,0.18)`
- **Floating graphic card:** `0 28px 80px -32px rgba(25,24,23,0.40)`
- **Menu/popover:** `0 16px 50px -20px rgba(25,24,23,0.35)`

---

## 9. Core components (as built)

Reference implementations live in `components/`. Match these patterns.

- **Buttons**
  - Primary: Ink 900 fill, Ivory text, `rounded-xl`, hover Ink 800 (`.btn-primary`).
  - Accent: Clay fill, Ivory text, hover Clay 600 (`.btn-accent`).
  - Ghost: transparent, faint ink border, subtle hover tint (`.btn-ghost`).
- **Card:** Linen fill, Sand border, `rounded-2xl`, soft hover shadow + border shift (`.card`).
- **Eyebrow:** the uppercase clay label described in §5 (`.eyebrow`).
- **PageHero** (`components/page-hero.tsx`): eyebrow → serif H1 → Ink 500 subtitle → actions, with an optional right-column illustration (`media`) that hides below `lg`. Text column keeps a `max-w-3xl` regardless of the graphic.
- **SectionHeader** (`components/section.tsx`): eyebrow + serif title + optional subtitle.
- **CTA** (`components/cta.tsx`): closing call-to-action band.
- **Reveal** (`components/reveal.tsx`): entrance animation wrapper (see §12).
- **Navigation** (`components/nav.tsx`): sticky header, three mega-menus on desktop, accordion menu on mobile. **Footer** (`components/footer.tsx`): 4-column link groups + brand block.

---

## 10. Illustration system — "intelligence cards"

Our signature graphics are **not photography and not stock art.** They're clean, custom **line-art SVG scenes** inside a floating "intelligence card" frame: a rounded Linen card with a soft clay glow, a header with a live badge, a small data scene (maps, pins, node networks, mini charts, app windows), chips, an insight row, and floating metric/label chips.

**Where they live:**
- `components/marketing-hero-graphics.tsx` (Research, Data-for-Good, Partnerships, Advertising, Build, Locations, Blog, About, Platforms, Responsible-AI…)
- `components/data-hero-graphics.tsx` (data layers, data hub, Neighbourly)
- `components/service-hero-graphics.tsx`, `components/industry-hero-graphic.tsx`, `components/solutions-hero-graphic.tsx`

**Illustration palette (SVG constants):**
| Name | Hex |
|---|---|
| Clay (primary line/fill) | `#cc785c` |
| Clay dark | `#a1543b` |
| Muted (secondary line) | `#928d7e` |
| Sand (grid/soft) | `#e7e3d7` |
| Paper (fills/highlights) | `#fffefb` |
| Ink | `#191817` |

**Style rules:** rounded line caps/joins, 1–2px strokes, clay for the "signal"/focus element, muted for supporting data, sand for grids. One pulsing accent node max. Keep scenes uncluttered — the card frame is already detailed.

---

## 11. Data visualization

Component: `components/blog-chart.tsx`. Four chart kinds — `stats` (metric rows), `bars` (horizontal), `line`, `callout` (highlighted figure). Server-rendered SVG/CSS, clay bars/lines on sand gridlines.

**Data-integrity rule (non-negotiable, brand-critical):**
- Verified public figures (Bank of Canada rates, dated policy events, Statistics Canada inflation) are stated **as fact**.
- Any price/sales/market figure is captioned **"Homicity Research estimate."**
- **Never** fabricate audited certifications or present estimates as verified. Precision over hype — this is core to the brand's credibility.

---

## 12. Motion

- **Entrance:** gentle fade-up — 16–20px rise, ~0.7s, ease-out `cubic-bezier(0.16, 1, 0.3, 1)`, small stagger. Implemented in `Reveal`.
- **Ambient:** slow `pulse-glow` on live/accent dots (~4s loop).
- **Transitions:** 200–300ms, ease. Calm. No bounce, no fast slides, no parallax.
- **Reduced motion:** the site fully honors `prefers-reduced-motion` (Framer Motion via `useReducedMotion`, plus a global CSS fallback that neutralizes keyframe animations/transitions). Any new motion must degrade gracefully — content must be readable with motion off.

---

## 13. Social / Open Graph images

- **Format:** 1200 × 630 PNG.
- **Static brand card:** `app/opengraph-image.tsx`.
- **Dynamic per-page card:** `app/og/route.tsx` — renders a branded card from `?eyebrow=&title=&sub=` so every page has a unique social image (mark + Homicity, clay eyebrow, big title, subtitle, "Data · Mapping · Insights" / "neighbourly.io" footer).
- **Style:** Ivory `#faf9f5` background, soft clay glow top-right, clay mark, Ink title, Ink-500 subtitle. Sans-serif (system) for reliable rendering.

---

## 14. Voice & tone

- **Clear, editorial, confident, human.** Short sentences. Concrete over abstract.
- **Honest and precise.** No superlatives we can't defend; label estimates; don't overclaim.
- **Canadian.** English-CA spelling (neighbourhood, colour, standardize→standardise not required but "-ize" used in product copy — keep consistent with existing copy).
- **Helpful, not salesy.** Explain the value; let the data and product do the selling.
- Product framing: Homicity = the intelligence layer / infrastructure; **Neighbourly.io** = the flagship API; the other platforms are "built on Neighbourly."

---

## 15. Accessibility

- Text colours meet contrast on warm backgrounds (body = Ink 600 on Ivory). Keep clay for accents, not body text.
- Visible focus states; keyboard-navigable menus; honor reduced motion.
- Icons that convey meaning need labels; decorative SVGs are `aria-hidden`.
- Don't rely on colour alone to convey state.

---

## 16. Asset index (where everything lives)

| Asset | Path |
|---|---|
| Logo lockup + icon mark | `components/logo.tsx` |
| App-icon renderer | `lib/og-icon.tsx` |
| Favicon / Apple / PWA icons | `app/icon.tsx`, `app/apple-icon.tsx`, `app/icon-192.png/`, `app/icon-512.png/` |
| Web manifest | `app/manifest.ts` |
| OG images | `app/opengraph-image.tsx`, `app/og/route.tsx` |
| Colour + font tokens | `tailwind.config.ts` |
| Global styles (buttons, card, eyebrow, utilities, motion) | `app/globals.css` |
| Fonts loaded | `app/layout.tsx` (Inter, Newsreader) |
| Illustration components | `components/*hero-graphic*.tsx`, `components/data-hero-graphics.tsx` |
| Charts | `components/blog-chart.tsx` |
| Core UI | `components/page-hero.tsx`, `section.tsx`, `cta.tsx`, `reveal.tsx`, `nav.tsx`, `footer.tsx` |

**Fonts to license/obtain:** Newsreader and Inter — both free via Google Fonts.

---

## 17. Quick do / don't

**Do** — warm ivory backgrounds · serif headlines · one clay accent per view · generous whitespace · custom line-art SVG · honest, sourced data · soft warm shadows · rounded corners.

**Don't** — pure white or pure black · cold blues/purples or neon · heavy drop shadows · dense, cramped layouts · stock photography · sans-serif headlines · gradients as large fills · recolouring the logo mark · fabricated stats or unlabelled estimates.

---

*This guide reflects the current, shipped Homicity design system. When in doubt, match the live site — the components in `components/` are the source of truth.*