# Green Pages — DESIGN.md

> The complete visual language for **Green Pages** — the WhatsApp commerce platform, and the team that built **paige**. Drop this file into any AI agent (Motion, Stitch, Claude, Cursor, v0) to generate brand-consistent output.
>
> Canonical version lives at `/design.md` on the live brand site.

---

## 1. Visual Theme & Atmosphere

**Two surfaces, one voice.**

- **Marketing surfaces** — confident, playful, expensive. Hero gradients (navy → green), generous whitespace, big display type in Buvera, pill-shaped buttons with bounce + soft green glow. Lovable's warmth, Linear's economy.
- **Product (paige) surfaces** — quiet, dense, functional. Flat buttons, compact rows, no decorative gradients. The tone shifts; the brand doesn't.

**Mood words:** confident, friendly, deliberate, modern, premium. Never corporate, never cute.

**Density:** spacious on marketing (24–48 px gaps), tight on product (8–16 px gaps).

---

## 2. Color Palette & Roles

All values are stored in **oklch** in `src/styles.css`; hex shown here for portability.

### Brand core

| Token              | Hex       | Role                                                                |
| ------------------ | --------- | ------------------------------------------------------------------- |
| `--brand-navy`     | `#131D37` | Primary brand color. Backgrounds, headlines, secondary buttons.     |
| `--brand-green`    | `#81D741` | Accent / CTA. Primary buttons, links, focus ring, status success.   |
| `--brand-green-soft` | `#DCF8C6` | Subtle accent backgrounds, hero gradient endpoint.                |
| `--brand-blue-beta` | `#3B82F6` | **Reserved.** Only ever colors the `[beta]` suffix on paige. Retires at v1. |
| `--brand-ink`      | `#0B1220` | Deepest text (`foreground`).                                        |

### Neutrals

| Token                | Hex (approx) | Use                                       |
| -------------------- | ------------ | ----------------------------------------- |
| `--brand-grey-50`    | `#FAFAFA`    | Muted surfaces, secondary backgrounds.    |
| `--brand-grey-100`   | `#F5F5F5`    | Subtle dividers, alternating rows.        |
| `--brand-grey-200`   | `#E5E5E5`    | Default borders.                          |
| `--brand-grey-300`   | `#D4D4D4`    | Strong borders.                           |
| `--brand-grey-500`   | `#8E8E93`    | Muted text, captions, eyebrow tags.       |
| `--brand-grey-700`   | `#5C5C5C`    | Body copy on light surfaces.              |

### Semantic mapping (light mode)

- `background: white` · `foreground: --brand-ink`
- `primary: --brand-green` · `primary-foreground: --brand-navy`
- `secondary: --brand-navy` · `secondary-foreground: white`
- `accent: --brand-green-soft` · `accent-foreground: --brand-navy`
- `muted: --brand-grey-50` · `muted-foreground: --brand-grey-500`
- `destructive: oklch(0.62 0.22 27)` (red) · `destructive-foreground: white`
- `border / input: --brand-grey-200` · `ring: --brand-green`

### Dark mode

Light-on-navy. `background: --brand-navy`, `foreground: near-white`, `accent-foreground: --brand-green`. Card surfaces lift to a slightly lighter navy (~`oklch(0.26 0.045 264)`).

### Signature gradients

```css
--gradient-hero:         linear-gradient(135deg, #131D37 0%, #1f3a52 50%, #81D741 100%);
--gradient-hero-subtle:  linear-gradient(135deg, #DCF8C6 0%, #ffffff 50%, #f3faec 100%);
```

### Color rules

- **One accent.** Green is the only accent on a marketing surface — never two competing accents.
- **Beta blue is sacred.** It appears nowhere except `[beta]` on the paige wordmark. Don't introduce a second blue.
- **Green on green is illegal.** The logo never sits on a green background (low contrast).
- **No invented hues.** Stay on the ladder. Never `#9ee04f` or `#6ec22f` to "tweak" the green.

---

## 3. Typography Rules

**Three faces, three roles.** All defined in `@theme` at `src/styles.css`.

| Font            | Role             | When                                                                |
| --------------- | ---------------- | ------------------------------------------------------------------- |
| **Buvera**      | Display          | Headlines, hero copy, section titles, wordmark. **Minimum 24 px.**  |
| **Geist Sans**  | UI / Body        | Default for everything else — buttons, forms, body, in-product chrome. |
| **Geist Mono**  | Mono             | Code, file paths, hex values, CSS vars, eyebrow tags, the paige wordmark. |

### Type scale

| Key          | Size            | Use                                                              |
| ------------ | --------------- | ---------------------------------------------------------------- |
| `display-xl` | 88 px / 5.5rem  | Marketing hero only                                              |
| `display-lg` | 60 px / 3.75rem | Landing headline                                                 |
| `display-md` | 48 px / 3rem    | Section title                                                    |
| `h1`         | 36 px / 2.25rem | Page H1                                                          |
| `h2`         | 30 px / 1.875rem| Section H2                                                       |
| `h3`         | 24 px / 1.5rem  | Subsection / minimum Buvera size                                 |
| `xl`         | 20 px / 1.25rem | Subheading (Geist)                                               |
| `lg`         | 18 px / 1.125rem| Intros, long-form lead                                           |
| `base`       | 16 px / 1rem    | Default body (Geist)                                             |
| `sm`         | 14 px / 0.875rem| UI labels, captions                                              |
| `xs`         | 12 px / 0.75rem | Microcopy, legal                                                 |
| `mono-tag`   | 11 px / 0.6875rem | Eyebrow tags (uppercase, tracking 0.28em, Geist Mono)          |

### Weights

- **Buvera:** 500 / 600 / 700 / 800 / 900. ExtraBold for hero scale; SemiBold for restrained heads.
- **Geist:** 400 / 500 / 600 / 700. Medium for emphasis, never bold unless it's a heading.

### Type pairing pattern

```
[eyebrow — Geist Mono · 11px · uppercase · 0.28em tracking · green-700]
[headline — Buvera ExtraBold · display-md · navy · leading-[0.95]]
[body     — Geist Regular · base · grey-700 · leading-relaxed]
[inline accent code — Geist Mono · sm · grey-50 bg · navy text]
```

### Typography rules

- Headlines & section titles: **Buvera only**, never below 24 px.
- Body, buttons, forms, in-product UI: **Geist Sans only**.
- Anything code-shaped (paths, vars, hex, tokens) + eyebrow tags + the `paige` wordmark: **Geist Mono**.
- Stay on the ladder — don't invent intermediate sizes.

---

## 4. Component Stylings

### Buttons — two tracks, one component

The shadcn `<Button>` at `src/components/ui/button.tsx` supports both tracks via variants. **Never override hover with `className`** — add a variant instead.

#### Marketing track (landing pages, ads, decks)

Loud. Pill-shaped (`rounded-full`), bouncy (`btn-bounce`), with soft green glow (`shadow-hero`).

| Variant            | Looks like                                                 |
| ------------------ | ---------------------------------------------------------- |
| `hero`             | Green pill, navy text, hero shadow, lifts on hover.        |
| `hero-secondary`   | Outlined navy pill, transparent fill.                      |
| `green`            | Solid green, navy text, soft shadow.                       |
| `brand`            | Solid navy, white text, lifted.                            |
| `default`          | shadcn default (primary green).                            |
| `secondary` / `outline` / `ghost` / `link` / `destructive` | Standard shadcn variants. |

#### Platform track (paige in-app)

Flat, compact, functional. Mirrors `paige/components/ui/button.jsx`.

| Variant                 | Use                                          |
| ----------------------- | -------------------------------------------- |
| `platform-brand`        | Primary action in paige (e.g. Send, Deploy)  |
| `platform-default`      | Secondary primary action                     |
| `platform-secondary`    | Cancel, dismiss                              |
| `platform-outline`      | Edit, less-prominent action                  |
| `platform-ghost`        | Icon buttons, kebab menus                    |
| `platform-destructive`  | Delete confirmations                         |
| `platform-link`         | Inline doc links                             |
| `platform-success`      | "Deployed!" confirmation state               |

Platform sizes: `platform-lg | platform-default | platform-sm | platform-xs` + icon variants (`platform-icon-lg | platform-icon | platform-icon-sm | platform-icon-xs`).

#### Button anti-patterns

- ❌ Raw `<button>` with `hover:bg-*` → ✅ shadcn `<Button>` with a variant
- ❌ `hover:opacity-*` to suggest hover → ✅ Darker shade (`hover:bg-[colour]-700`) — fade is mushy
- ❌ Override `hover:` classes on `<Button>` via `className` → ✅ Add a new variant to `button.tsx`
- ❌ Native `title=` on icon buttons → ✅ shadcn `<Tooltip>` wrapping the button
- ❌ `window.alert()` / `window.confirm()` → ✅ Sonner toast / shadcn `AlertDialog`

### Cards, inputs, navigation

- **Card surface:** `bg-background`, `border border-grey-200`, `rounded-2xl` (1.5 rem), `shadow-soft`.
- **Inline code:** `font-mono text-sm bg-grey-50 border border-grey-200 rounded px-1.5 py-0.5 text-navy`.
- **Eyebrow tag:** `font-mono uppercase text-xs tracking-[0.28em] text-green-700` (or `text-grey-500` for neutral).
- **Focus ring:** 2 px green ring + 2 px offset. Never hide the focus ring.

### Toasts & dialogs

- **Toasts:** Sonner (`sonner` package). `toast.success / error / info`.
- **Confirmations:** shadcn `AlertDialog`. Never `window.confirm`.

---

## 5. Layout Principles

### Radius scale

Base `--radius: 1rem`. Derived: `sm: 0.5rem`, `md: 0.75rem`, `lg: 1rem`, `xl: 1.5rem`, `2xl: 2rem`, `3xl: 2.5rem`.

### Spacing

- **Marketing:** generous. Section padding `py-16` to `py-24` (4–6 rem). Card padding `p-6` to `p-12`.
- **Product (paige):** compact. Row padding `px-4 py-2`. Card padding `p-4` to `p-6`.
- **Eyebrow → title:** 8 px gap (`mb-2`). **Title → body:** 16–24 px gap.
- **Grids:** `gap-4` (16 px) for product cards, `gap-6` to `gap-8` for marketing.

### Layout container

- Max width: `max-w-6xl` (~1152 px) for marketing pages.
- Horizontal padding: `px-6` (24 px), bumps to `px-8` on lg screens.
- Centering: `mx-auto`.

### Whitespace philosophy

Whitespace is a feature, not negative space. If a section feels cramped, the answer is more padding — not smaller text.

---

## 6. Depth & Elevation

Three shadows. No more.

```css
--shadow-soft:  0 4px 18px -6px rgba(19, 29, 55, 0.12), 0 2px 6px -2px rgba(19, 29, 55, 0.06);
--shadow-hero:  0 20px 50px -16px rgba(129, 215, 65, 0.55), 0 8px 20px -6px rgba(19, 29, 55, 0.18);
--shadow-navy:  0 20px 50px -16px rgba(19, 29, 55, 0.45);
```

| Token          | When                                                       |
| -------------- | ---------------------------------------------------------- |
| `shadow-soft`  | Default lift for cards on light surfaces.                  |
| `shadow-hero`  | Marketing CTAs only — the signature green glow.            |
| `shadow-navy`  | Dark-card lift, used sparingly on hero surfaces.           |

**Don't:** invent new shadows (no `shadow-2xl`, no inline `boxShadow`), don't drop-shadow the logo, don't stack shadows.

---

## 7. Motion

**One curve, four durations.** Every animation across web, video, and product uses the same easing curve.

### The brand curve

```
--ease-brand: cubic-bezier(0.22, 1, 0.36, 1)   /* ease-out: snappy entrance, soft tail */
```

### Duration scale

| Token                 | ms     | Use                                                       |
| --------------------- | ------ | --------------------------------------------------------- |
| `--duration-micro`    | 150    | Button press, hover lift, toast fade                      |
| `--duration-default`  | 300    | Most transitions — dialogs, dropdowns, tabs               |
| `--duration-hero`     | 600    | Hero entrance, logo intro, page-level reveals             |
| `--duration-intro`    | 1200   | First-load brand intro on landing, video opener           |

Pick the closest step. **Don't invent in-between durations.**

### Choreography rules

- **Entrance** uses ease-out (`ease-brand`); **exit** uses ease-in (`cubic-bezier(0.7, 0, 0.84, 0)`).
- **Sibling stagger:** 50 ms for small lists, 80–100 ms for hero-scale staggers. Never animate siblings simultaneously.
- **Direction:** elements arrive from below + fade in (`y: 24 → 0`, `opacity: 0 → 1`). Logo intros add a `scale 0.92 → 1` and a `blur(8px) → blur(0)` for the 1200 ms variant.

### Reference logo motion

- **Intro (1200 ms):** `opacity 0 → 1` · `scale 0.92 → 1` · `blur 8 px → 0` · ease-brand
- **Outro (600 ms):** `opacity 1 → 0` · `y 0 → -12 px` · ease-in

---

## 8. Logo & Wordmark

- **Primary lockup:** WhatsApp speech-bubble + storefront awning silhouette + "Green Pages" wordmark. Available SVG (Buvera font embedded) and PNG.
- **Variants:** `logo-mark` (light), `logo-mark-white` (dark), `icon-navy`, `icon-white`. All in `public/logos/`.
- **Clear space:** half the icon's height (`x/2`) on every side. No exceptions.
- **Minimum sizes:** Full lockup 120 px wide (web) / 30 mm (print). Icon mark 32 px (web) / 10 mm (print). Paige wordmark 14 px text.
- **Co-lockup (Green Pages × paige):** only when both brands are an explicit subject. Default order: parent left, separator ×, product right.

### Paige product wordmark

Lowercase `paige` in `--brand-green` + `[beta]` in `--brand-blue-beta`. **Geist Mono only.** Never restyled. The `[beta]` suffix retires when paige hits v1 — along with the beta blue.

### Logo do / don't

✅ **Do**
- Use the full lockup as primary
- Icon mark alone for favicons, app icons, social avatars
- Place on white, grey-50, navy, or green-soft
- Maintain `x/2` clear space

❌ **Don't**
- Stretch, rotate, or skew
- Recolor the green disc
- Place on busy photography or patterns
- Separate the awning from the storefront
- Add drop shadows, outlines, or glow
- Use `[beta]` without `paige` or restyle either piece

---

## 9. Voice

**Playful but precise.** Lovable's warmth, Linear's economy. If a sentence sounds like a press release, rewrite it.

### Principles

1. **Plain over clever.** Say the thing. Don't dress it up.
2. **Short sentences. One idea each.** Vary length, lean short.
3. **Specific beats vague.** "Deploy in under a minute" > "Fast and reliable." Numbers, nouns, verbs — not stacked adjectives.
4. **Cheeky, never smug.** A little wink is fine. Punching down isn't.
5. **Developer-aware, not jargon-soaked.** Talk about APIs, deploys, flows — but assume the reader sells things, not ships infrastructure.

### Tone by context

| Context              | Pitch                                                                                              | Example                                                                                                  |
| -------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Marketing headline   | Confident, slightly cheeky. Says what's true, not what's safe.                                     | "Build a WhatsApp bot in the time it takes to brew coffee."                                              |
| Product UI copy      | Quiet, descriptive, never pleading. Buttons say what they do.                                      | "Send test template"                                                                                     |
| Error message        | Acknowledge, explain, give a next step. No "oops", no winking.                                     | "We couldn't reach your WhatsApp number. Try reconnecting from Settings → WhatsApp."                     |
| Support reply        | Warm, direct, accountable. Name the problem, name the fix, name the timeline.                      | "That deploy failed because the template wasn't approved by Meta yet. I've kicked off a re-submission."  |

### Banned words

| Don't say              | Say instead                                                                  |
| ---------------------- | ---------------------------------------------------------------------------- |
| Game-changing          | Say what changes.                                                            |
| Revolutionary          | Say what's different.                                                        |
| Synergy                | Say which two things work together and why.                                  |
| AI-powered             | Say what the AI does. "Generates bot code from a description."               |
| Unlock                 | Use a real verb. "Open", "send", "launch", "earn".                           |
| Supercharge            | Say the actual gain. "3× faster", "in one click".                            |
| Leverage               | "Use."                                                                       |
| Ecosystem              | Be specific. "Apps", "integrations", "partners".                             |
| Solution(s)            | Say what it actually is. "Bot builder", "broadcast tool".                    |
| Cutting-edge           | Show, don't claim. Demos beat adjectives.                                    |
| Empower                | "Let", "help", "give".                                                       |
| Seamless / seamlessly  | Describe how it actually flows. "One click", "no copy-paste".                |

### Rhythm

Vary length, lean short. Read everything aloud. If you run out of air, the sentence is too long.

---

## 10. Responsive Behavior

- **Breakpoints (Tailwind defaults):** `sm: 640 px`, `md: 768 px`, `lg: 1024 px`, `xl: 1280 px`, `2xl: 1536 px`.
- **Touch targets:** minimum 44 × 44 px on touch devices.
- **Hero type:** `text-5xl` mobile → `text-7xl` desktop → `text-[5.5rem]` xl. Drops a step per breakpoint down.
- **Grid collapse:** `md:grid-cols-2` collapses to single column below 768 px.
- **Section padding:** `py-16` mobile → `py-24` desktop.

---

## 11. Do's and Don'ts (cross-cutting)

✅ **Do**
- Use brand tokens, not raw hex (`bg-navy`, not `bg-[#131D37]`)
- Use the shadcn `<Button>` and add variants when none fit
- Use `cn()` from `src/lib/utils.ts` to merge classes
- Use `framer-motion` with `ease-brand` and a duration from the scale
- Use the eyebrow tag pattern (Geist Mono · uppercase · 0.28em tracking) for section labels

❌ **Don't**
- Override hover via `className` — add a variant
- Use opacity for hover state — use a darker shade
- Mix Buvera with body text or use it below 24 px
- Introduce a second accent color or a second blue
- Invent shadows, durations, or radii outside the scales above
- Use stock photography, fake 3D, or neon glow
- Write `Click here`, `Learn more`, or `Oops!`

---

## 12. Agent Prompt Guide

When pasting this into an AI agent (Motion, Stitch, Claude, Cursor, v0), pair it with a concrete brief:

```
Brand: Green Pages — the WhatsApp commerce platform that builds Paige.
Tagline: "Build in minutes, launch to millions."

Use the rules in DESIGN.md exactly:
- Colors: navy #131D37, green #81D741, soft green #DCF8C6 — one accent only
- Type: Buvera for display (24px+), Geist Sans for body, Geist Mono for code/eyebrows
- Buttons: pill-shaped + glow for marketing, flat for product (paige)
- Motion: cubic-bezier(0.22, 1, 0.36, 1), durations 150 / 300 / 600 / 1200 ms
- Eyebrow tags: Geist Mono uppercase, 0.28em tracking, green-700
- Voice: plain, specific, cheeky-not-smug. Banned: game-changing, unlock, seamless, AI-powered.

[then describe the artifact: hero video / landing page / ad / email]
```

### Quick color cheat sheet

```
Navy        #131D37   primary brand, headlines, secondary buttons
Green       #81D741   accent, CTAs, focus ring, success
Green soft  #DCF8C6   accent backgrounds, gradient endpoint
Ink         #0B1220   body text
Grey-500    #8E8E93   muted text, captions
Beta blue   #3B82F6   reserved — only the [beta] suffix on paige
```

### Ready-to-paste motion brief

```
16:9, 25s, ease cubic-bezier(0.22, 1, 0.36, 1)
0–4s   intro: logo lockup fades + scales (1200ms) on navy bg with soft green glow
4–10s  problem: overlapping WhatsApp message fragments accelerate
10–12s pivot: white flash, dead silence
12–20s product: clean off-white scenes of paige, 80ms stagger between elements
20–25s lockup: "Build in minutes, launch to millions" in Buvera ExtraBold, hold

Palette: navy #131D37, green #81D741, off-white
Type: Buvera ExtraBold for headlines, Geist Mono for timestamps/UI
No stock footage, no fake 3D, no neon glow.
```

---

*Source of truth: `src/styles.css` + the brand showcase site. If a value here disagrees with the live tokens, the tokens win.*