# Hook Agency Brand System · Context File

**Version:** 2.0 · 2026
**Purpose:** Drop-in context for Claude Code, Claude Design, or any AI assistant working on Hook Agency projects.
**Source of truth:** [brandkit.hookagency.com](https://brandkit.hookagency.com)

---

## How to use this file

Paste this entire file into your AI tool (Claude Projects, Claude Code instructions, ChatGPT system prompt, Cursor rules, etc.) at the start of any Hook Agency project. The assistant should treat every rule in this document as mandatory, not optional. When in doubt, the assistant should prefer paraphrasing these rules back over guessing.

**Critical behavior:**
- Follow every rule in this document strictly. Rules are not suggestions.
- When a rule is ambiguous, ask before improvising.
- When generating code, reference these CSS variables and tokens — never invent new colors or font stacks.
- Never substitute alternative colors, fonts, or spacing scales even if they would "look similar."
- When generating designs (mocks, illustrations, layouts), respect approved color pairings and the 80/20 ratio explicitly.

---

## Brand Overview

Hook Agency is a digital marketing agency serving home services clients (roofing, HVAC, plumbing). The brand is **bold, structured, performance-driven, and confident**. The visual system balances high-impact primaries with flexible neutrals. The feel is editorial and modern without being decorative.

When in doubt, the aesthetic is closer to *Financial Times* meets *Patagonia billboard* than to *SaaS marketing site*. Blocky, typographic, ruthlessly structured.

---

## Core Palette

Three primary brand colors. Use these for 80% of any composition.

| Name     | Hex        | RGB               | CMYK               | Role |
|----------|------------|-------------------|--------------------|------|
| Shadow   | `#19191C`  | 25, 25, 28        | 74, 69, 63, 78     | Foreground on light · background on dark · the brand anchor |
| Lime     | `#D4FD52`  | 212, 253, 82      | 21, 0, 85, 0       | Primary accent on dark · high-energy highlights |
| Cobalt   | `#253FF6`  | 37, 63, 246       | 84, 73, 0, 0       | Primary accent on light · confident calls-to-action |

**Rules for core colors:**
- Lime is for emphasis, highlights, key brand moments. **Not for large background fills.**
- Cobalt drives action on light mode. White on Cobalt is the only approved text pairing on Cobalt.
- Shadow is the anchor — it's the dark background in dark mode and the foreground text in light mode.

---

## Secondary Palette

Two supporting neutrals for 20% of any composition.

| Name       | Hex        | RGB            | CMYK         | Role |
|------------|------------|----------------|--------------|------|
| Dark Gray  | `#828282`  | 130, 130, 130  | 0, 0, 0, 49  | Tertiary text · borders on light · muted UI |
| UI Gray    | `#EFEFEF`  | 239, 239, 239  | 0, 0, 0, 6   | Light surfaces · card backgrounds · subtle panels |

**Rules for secondary colors:**
- Secondary colors support the core palette. They never lead.
- Never use Dark Gray on Shadow, on Lime, or on Cobalt — low contrast (see Avoid Pairings below).

---

## Approved Color Pairings

**These are the ONLY approved text/background pairings. Do not use combinations outside this set.**

### Core pairings
1. **Lime on Shadow** — primary dark-mode treatment
2. **Shadow on Lime** — primary light-on-brand moment
3. **White on Shadow** — neutral dark-mode text
4. **White on Cobalt** — primary action on light mode

### Secondary pairings
5. **Dark Gray on UI Gray** — quiet tertiary text
6. **UI Gray on Dark Gray** — inverted quiet treatment
7. **Shadow on Dark Gray** — muted but readable
8. **Shadow on UI Gray** — standard light-mode text

---

## Avoid Pairings

**Never use these combinations. They reduce contrast and break brand consistency.**

1. ❌ Dark Gray on Shadow — low contrast
2. ❌ Dark Gray on Lime — low contrast
3. ❌ Lime on UI Gray — low contrast
4. ❌ Dark Gray on Cobalt — low contrast
5. ❌ Dark color on any core color (other than approved pairings)
6. ❌ Light color on light color
7. ❌ Dark color on dark color
8. ❌ Any two colors combined within a single glyph or word
9. ❌ Type rendered at opacity < 100%
10. ❌ Gradients inside type
11. ❌ New gradient colors (outside the 6 official gradients below) in backgrounds
12. ❌ Off-brand color shades — no yellow, no magenta, no teal, nothing outside this palette

---

## Color Ratio · 80/20

- **80% primary** — Shadow, Lime, Cobalt dominate any composition.
- **20% secondary** — UI Gray and Dark Gray support.

This ratio applies at the brand level, not per-page. A single page can be all primary or all secondary, but across communications the balance should hold.

---

## Color Opacity Rules

Opacity is used **only on surfaces, shapes, and backgrounds** — never on type.

- ✅ Shape backgrounds at 80%, 60%, 40%, 20% — acceptable
- ✅ Panel overlays at reduced opacity — acceptable
- ❌ Text at any opacity below 100% — never

If text needs to feel quieter, use a different semantic color (muted-foreground = Dark Gray on light, derived light gray on dark), not reduced opacity.

---

## Official Gradients

**Only these six gradients are approved. Do not invent new gradient combinations.**

| Name                         | Stops                          | Usage |
|------------------------------|--------------------------------|-------|
| Lime → Dark Lime             | `#D4FD52 → #9EDC2E`            | Energetic accents, bright-on-bright |
| Lime → UI Gray               | `#D4FD52 → #EFEFEF`            | Soft fade-outs on light |
| Lime → Shadow                | `#D4FD52 → #19191C`            | Dramatic edge transitions |
| Cobalt → Soft Slate Blue     | `#253FF6 → #6A7CFF`            | Tonal depth within blue |
| Cobalt → UI Gray             | `#253FF6 → #EFEFEF`            | Soft fade-outs on light |
| Shadow → Cobalt Variation    | `#19191C → #36467E`            | Moody dark-mode atmosphere |

**Gradient rules:**
- Gradients are for **backgrounds, shapes, and accents** — never on type.
- Do not introduce new gradient stops not listed above.
- Default direction is left-to-right (90deg) unless the layout calls for something specific.
- For hero treatments: dark mode uses Lime variants, light mode uses Cobalt variants.

---

## Textures

Seven gradient-line shapes plus a vertical-stripe hero texture are part of the system. They're used as decorative accents, never as the main subject.

**Available textures (hosted on the CDN):**
- `https://brandkit.hookagency.com/assets/textures/shape-01.svg` through `shape-07.svg` — organic shapes filled with line patterns, for editorial layouts
- `https://brandkit.hookagency.com/assets/textures/hero-texture.svg` — vertical-stripe pattern for hero treatments

**Texture rules:**
- Textures are black-on-transparent SVGs. Color them via CSS `mask-image` (recommended) or `filter: invert()` for mode inversion.
- When used in hero/marketing layouts, tint the texture to brand color (Lime in dark mode, Cobalt in light mode).
- Subtle paper-noise textures are acceptable on large background panels.
- Textures never carry type. Content sits on solid color or on the page background, not on top of textures.

---

## Typography System

Hook uses three typefaces across the system. They do very different jobs and should not cross over.

### 1. Champion HTF · Display (Licensed)

**Family:** `Champion HTF Welterweight` (core), plus Featherweight and Heavyweight
**Source:** Licensed from Hoefler & Co. · Hook Agency license · **do not redistribute**
**Fallback stack:**
```css
font-family: 'Champion HTF Welterweight', 'Champion Welterweight', Impact, Haettenschweiler, 'Arial Narrow', sans-serif;
```

**Usage:**
- Page titles and hero headlines (required)
- Section headers (use sparingly — only when ceremonial weight is warranted)
- Never for long-form reading
- **NEVER below 24px.** Below 24px, Champion loses sharpness and presence. If text must be smaller than 24px, use Archivo SemiBold instead.

**Case:**
- All Caps or Title Case only
- Never sentence case
- Never mixed case

**Alignment:**
- Left-aligned or centered only
- Never justified
- No decorative modifications, no outlines, no shadows

### 2. Archivo · Body / UI (Open Source)

**Family:** `Archivo`
**Source:** Google Fonts · SIL Open Font License · free to use anywhere
**Fallback stack:**
```css
font-family: 'Archivo', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
```

**Weights used:**
- Regular (400) — body text, captions
- SemiBold (600) — buttons, labels, emphasis, small headings

**Usage:**
- Everything below 24px
- Body copy, paragraphs
- Buttons, inputs, labels
- Small headings (H3 and below)
- UI chrome, navigation

**Rule:** Archivo supports Champion — it never competes with it.

### 3. Archivo Condensed · Dense Data (Open Source)

**Family:** `Archivo Condensed`
**Source:** Google Fonts · SIL Open Font License · free to use anywhere
**Fallback stack:**
```css
font-family: 'Archivo Condensed', 'Archivo Narrow', 'Archivo', -apple-system, sans-serif;
```

**Weights used:**
- Medium (500)

**Usage:**
- Data tables, spec sheets, metadata
- Captions, tags, timestamps
- UI chrome where vertical density matters
- SEO reports, dashboards, technical readouts

### Type Scale

| Role          | Font                   | Size        | Weight | Case         |
|---------------|------------------------|-------------|--------|--------------|
| Display       | Champion               | 64–140px    | 700    | All Caps     |
| H1            | Champion               | 40–56px     | 700    | All Caps     |
| H2            | Champion               | 24–32px     | 700    | All Caps or Title |
| H3            | Archivo SemiBold       | 20px        | 600    | Sentence     |
| H4            | Archivo SemiBold       | 16px        | 600    | Sentence     |
| Body          | Archivo Regular        | 15px        | 400    | Sentence     |
| Small         | Archivo Regular        | 13px        | 400    | Sentence     |
| Caption       | Archivo Condensed      | 11–12px     | 500    | All Caps     |
| Data / Mono   | Archivo Condensed      | 13px        | 500    | Sentence     |

---

## Consolidated Don'ts

A flat list of everything forbidden. If any rule is ambiguous, escalate rather than guess.

1. **Don't use colors outside the palette.** No yellows, no magentas, no teals, no "similar" greens or blues.
2. **Don't use unapproved color pairings.** See the list above.
3. **Don't put opacity on type.** Only on surfaces.
4. **Don't use gradients inside type.** Gradients are for backgrounds and shapes.
5. **Don't use Champion below 24px.** Use Archivo SemiBold instead.
6. **Don't use Champion for body copy.** It's display only.
7. **Don't use sentence case for Champion.** All Caps or Title Case only.
8. **Don't justify text.** Left or centered only.
9. **Don't combine two colors within a single word or glyph.** Pick one color per piece of type.
10. **Don't invent new gradient combinations.** Use only the six official gradients.
11. **Don't redistribute Champion HTF.** License is restricted to Hook Agency.
12. **Don't deploy Champion HTF to client-owned domains.** Keep it on Hook infrastructure.
13. **Don't decorate type.** No outlines, shadows, glows, or embellishments.

---

## Implementation · shadcn CSS variables

Drop this into `app/globals.css` in any Next.js/shadcn project. Light mode is the default; dark mode activates on `.dark` class.

```css
@layer base {
  :root {
    /* Surfaces */
    --background: #FAFAFA;
    --foreground: #19191C;            /* Shadow */
    --card: #FFFFFF;
    --card-foreground: #19191C;
    --popover: #FFFFFF;
    --popover-foreground: #19191C;

    /* Brand — Cobalt drives action on light */
    --primary: #253FF6;
    --primary-foreground: #FFFFFF;

    /* Neutrals (official secondary) */
    --secondary: #EFEFEF;             /* UI Gray */
    --secondary-foreground: #19191C;
    --muted: #EFEFEF;
    --muted-foreground: #828282;      /* Dark Gray */
    --accent: #E4E4E4;
    --accent-foreground: #19191C;

    /* Status (derived — not in brand guideline) */
    --destructive: #E11D48;
    --destructive-foreground: #FFFFFF;
    --success: #10B981;
    --warning: #F59E0B;
    --info: #06B6D4;

    /* Lines */
    --border: #E1E1E1;
    --input: #E1E1E1;
    --ring: #253FF6;

    /* Charts — all within approved palette */
    --chart-1: #253FF6;               /* Cobalt */
    --chart-2: #D4FD52;               /* Lime */
    --chart-3: #6A7CFF;               /* Soft Slate Blue */
    --chart-4: #9EDC2E;               /* Dark Lime */
    --chart-5: #828282;               /* Dark Gray */

    /* Sidebar — UI Gray panel with Shadow text in light */
    --sidebar: #EFEFEF;
    --sidebar-foreground: #19191C;
    --sidebar-primary: #253FF6;
    --sidebar-primary-foreground: #FFFFFF;
    --sidebar-accent: #E4E4E4;
    --sidebar-accent-foreground: #19191C;
    --sidebar-border: #D8D8D5;
    --sidebar-ring: #253FF6;

    --radius: 0.625rem;
  }

  .dark {
    --background: #19191C;            /* Shadow */
    --foreground: #EFEFEF;            /* UI Gray */
    --card: #232327;
    --card-foreground: #EFEFEF;
    --popover: #232327;
    --popover-foreground: #EFEFEF;

    /* Brand — Lime drives action on dark */
    --primary: #D4FD52;
    --primary-foreground: #19191C;

    --secondary: #2A2A2E;
    --secondary-foreground: #EFEFEF;
    --muted: #2A2A2E;
    --muted-foreground: #A1A1A6;      /* derived — Dark Gray on Shadow is AVOID */
    --accent: #36363B;
    --accent-foreground: #EFEFEF;

    --destructive: #F43F5E;
    --destructive-foreground: #FFFFFF;
    --success: #34D399;
    --warning: #FBBF24;
    --info: #22D3EE;

    --border: #2F2F33;
    --input: #2F2F33;
    --ring: #D4FD52;

    --chart-1: #D4FD52;
    --chart-2: #6A7CFF;
    --chart-3: #9EDC2E;
    --chart-4: #A1A1A6;
    --chart-5: #36467E;

    --sidebar: #0F0F11;
    --sidebar-foreground: #EFEFEF;
    --sidebar-primary: #D4FD52;
    --sidebar-primary-foreground: #19191C;
    --sidebar-accent: #19191C;
    --sidebar-accent-foreground: #EFEFEF;
    --sidebar-border: #232327;
    --sidebar-ring: #D4FD52;
  }
}
```

---

## Implementation · Tailwind v4 @theme

For Tailwind v4 projects, add this `@theme inline` block to your CSS entry file. This exposes the semantic tokens as utility classes (`bg-primary`, `text-foreground`, etc.) and also exposes the raw brand hexes for marketing work.

```css
@import "tailwindcss";

@theme inline {
  /* Semantic tokens (mode-aware via CSS vars) */
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-card: var(--card);
  --color-card-foreground: var(--card-foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  --color-secondary: var(--secondary);
  --color-muted: var(--muted);
  --color-muted-foreground: var(--muted-foreground);
  --color-accent: var(--accent);
  --color-destructive: var(--destructive);
  --color-success: var(--success);
  --color-warning: var(--warning);
  --color-info: var(--info);
  --color-border: var(--border);
  --color-input: var(--input);
  --color-ring: var(--ring);
  --color-chart-1: var(--chart-1);
  --color-chart-2: var(--chart-2);
  --color-chart-3: var(--chart-3);
  --color-chart-4: var(--chart-4);
  --color-chart-5: var(--chart-5);
  --color-sidebar: var(--sidebar);
  --color-sidebar-foreground: var(--sidebar-foreground);
  --color-sidebar-primary: var(--sidebar-primary);
  --color-sidebar-accent: var(--sidebar-accent);
  --color-sidebar-border: var(--sidebar-border);

  /* Raw brand hexes — for marketing, gradients, hero lockups */
  --color-brand-shadow: #19191C;
  --color-brand-lime: #D4FD52;
  --color-brand-cobalt: #253FF6;
  --color-brand-dark-gray: #828282;
  --color-brand-ui-gray: #EFEFEF;
  --color-brand-dark-lime: #9EDC2E;
  --color-brand-soft-slate: #6A7CFF;
  --color-brand-cobalt-variation: #36467E;

  /* Font families */
  --font-champion: "Champion HTF Welterweight", "Champion Welterweight", Impact, Haettenschweiler, "Arial Narrow", sans-serif;
  --font-sans: "Archivo", ui-sans-serif, system-ui, sans-serif;
  --font-condensed: "Archivo Condensed", "Archivo Narrow", "Archivo", sans-serif;

  --radius-sm: calc(var(--radius) - 4px);
  --radius-md: calc(var(--radius) - 2px);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) + 4px);
}
```

**Usage examples:**
```html
<!-- Semantic tokens (preferred for UI) -->
<button class="bg-primary text-primary-foreground font-sans">Run Audit</button>
<h1 class="font-champion uppercase text-foreground">Bold Statement</h1>
<p class="text-muted-foreground text-sm">Subtitle</p>

<!-- Raw brand colors (for marketing, hero lockups) -->
<div class="bg-brand-shadow text-brand-lime p-16">
  <h1 class="font-champion uppercase">Hook Agency</h1>
</div>

<!-- Condensed data -->
<span class="font-condensed uppercase tracking-wider text-muted-foreground">
  24,813 sessions · 18.4% MoM
</span>
```

---

## Implementation · JSON tokens

For design tools (Figma Tokens Studio, Style Dictionary), config generation, or cross-platform export:

```json
{
  "brand": {
    "shadow":    "#19191C",
    "lime":      "#D4FD52",
    "cobalt":    "#253FF6",
    "darkGray":  "#828282",
    "uiGray":    "#EFEFEF",
    "darkLime":  "#9EDC2E",
    "softSlate": "#6A7CFF",
    "cobaltVariation": "#36467E"
  },
  "gradients": [
    { "name": "Lime → Dark Lime",          "stops": ["#D4FD52", "#9EDC2E"] },
    { "name": "Lime → UI Gray",            "stops": ["#D4FD52", "#EFEFEF"] },
    { "name": "Lime → Shadow",             "stops": ["#D4FD52", "#19191C"] },
    { "name": "Cobalt → Soft Slate Blue",  "stops": ["#253FF6", "#6A7CFF"] },
    { "name": "Cobalt → UI Gray",          "stops": ["#253FF6", "#EFEFEF"] },
    { "name": "Shadow → Cobalt Variation", "stops": ["#19191C", "#36467E"] }
  ],
  "typography": {
    "display": {
      "family": "Champion HTF Welterweight",
      "stack":  "'Champion HTF Welterweight', 'Champion Welterweight', Impact, Haettenschweiler, 'Arial Narrow', sans-serif",
      "minSizePx": 24,
      "usage": "Page titles, section headers (sparingly). Never below 24px."
    },
    "body": {
      "family": "Archivo",
      "stack":  "'Archivo', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif",
      "weights": [400, 600],
      "usage": "Main UI font. Everything below 24px."
    },
    "condensed": {
      "family": "Archivo Condensed",
      "stack":  "'Archivo Condensed', 'Archivo Narrow', 'Archivo', -apple-system, sans-serif",
      "weights": [500],
      "usage": "Dense data, metadata, specs, UI chrome."
    }
  },
  "light": {
    "background": "#FAFAFA",
    "foreground": "#19191C",
    "card": "#FFFFFF",
    "primary": "#253FF6",
    "primaryForeground": "#FFFFFF",
    "secondary": "#EFEFEF",
    "muted": "#EFEFEF",
    "mutedForeground": "#828282",
    "border": "#E1E1E1",
    "ring": "#253FF6",
    "destructive": "#E11D48",
    "success": "#10B981",
    "warning": "#F59E0B",
    "info": "#06B6D4",
    "charts": ["#253FF6", "#D4FD52", "#6A7CFF", "#9EDC2E", "#828282"],
    "sidebar": {
      "background": "#EFEFEF",
      "foreground": "#19191C",
      "primary": "#253FF6",
      "accent": "#E4E4E4",
      "border": "#D8D8D5"
    }
  },
  "dark": {
    "background": "#19191C",
    "foreground": "#EFEFEF",
    "card": "#232327",
    "primary": "#D4FD52",
    "primaryForeground": "#19191C",
    "secondary": "#2A2A2E",
    "muted": "#2A2A2E",
    "mutedForeground": "#A1A1A6",
    "border": "#2F2F33",
    "ring": "#D4FD52",
    "destructive": "#F43F5E",
    "success": "#34D399",
    "warning": "#FBBF24",
    "info": "#22D3EE",
    "charts": ["#D4FD52", "#6A7CFF", "#9EDC2E", "#A1A1A6", "#36467E"],
    "sidebar": {
      "background": "#0F0F11",
      "foreground": "#EFEFEF",
      "primary": "#D4FD52",
      "accent": "#19191C",
      "border": "#232327"
    }
  }
}
```

---

## Asset URLs

All assets are hosted on `brandkit.hookagency.com`. Fonts and logos are CORS-configured to allow loading from any `*.hookagency.com` subdomain.

### Fonts stylesheet
```html
<link rel="stylesheet" href="https://brandkit.hookagency.com/hook-fonts.css">
```

This single import registers all `@font-face` declarations and exposes these CSS variables:
- `--font-champion` · the Champion stack
- `--font-champion-light` · Featherweight weight
- `--font-champion-heavy` · Heavyweight weight
- `--font-sans` · the Archivo stack
- `--font-condensed` · the Archivo Condensed stack

### Logos
- `https://brandkit.hookagency.com/assets/logos/hook-icon-black.svg`
- `https://brandkit.hookagency.com/assets/logos/hook-icon-white.svg`
- `https://brandkit.hookagency.com/assets/logos/hook-wordmark-black.svg`
- `https://brandkit.hookagency.com/assets/logos/hook-wordmark-white.svg`

Logo SVGs have no `fill` attribute — they inherit `currentColor`. Use one file, style via CSS:
```css
.hook-logo { color: var(--foreground); }
.hook-logo svg { fill: currentColor; }
```

### Textures
- `https://brandkit.hookagency.com/assets/textures/shape-01.svg` through `shape-07.svg`
- `https://brandkit.hookagency.com/assets/textures/hero-texture.svg`

Textures are black-on-transparent PNGs wrapped in SVG. For brand-colored rendering, use CSS `mask-image`:
```css
.hero-texture {
  background-color: var(--primary);
  mask-image: url('https://brandkit.hookagency.com/assets/textures/hero-texture.svg');
  mask-size: contain;
  mask-repeat: no-repeat;
}
```

---

## License & Distribution

- **Champion HTF** — licensed to Hook Agency. **Do not redistribute.** **Do not deploy to client-owned domains.** Keep font loading restricted to `*.hookagency.com` via CORS.
- **Archivo** and **Archivo Condensed** — SIL Open Font License. Free to use anywhere, including client deployments.
- **Hook logos and brand assets** — proprietary to Hook Agency. Use only in Hook-authorized work.

For client reports, keep deployments on `reports.hookagency.com/[client-slug]` to stay within Champion's self-hosted license.

---

## Quick reference — the 12 things to internalize

If you read nothing else, follow these:

1. **Colors:** Shadow `#19191C` · Lime `#D4FD52` · Cobalt `#253FF6` · Dark Gray `#828282` · UI Gray `#EFEFEF`.
2. **80/20:** Primary colors dominate. Secondary supports.
3. **Pairings:** Use only the 8 approved combinations. Never invent new ones.
4. **Champion HTF:** Display only. All Caps or Title Case. Never below 24px.
5. **Archivo:** Everything below 24px. Body, UI, captions.
6. **Archivo Condensed:** Dense data, metadata, dashboards.
7. **No opacity on type.** Ever. Only on surfaces.
8. **No gradients in type.** Ever. Gradients are for backgrounds.
9. **Only 6 gradients.** Don't invent new stop combinations.
10. **Dark mode primary:** Lime. Light mode primary: Cobalt.
11. **Charts:** Pull from the 5 approved chart colors — all within the brand palette.
12. **License:** Champion is licensed. Archivo is free. Don't ship Champion to client domains.

---

*End of context file. Paste complete — do not truncate.*