# Design System — PlanBetter

> A design spec you can hand to an AI coding agent (e.g. Claude Code) to build
> interfaces in the PlanBetter brand language. Drop this file into a project, or
> paste it into a prompt: "Build X using the PlanBetter design system below."
>
> **PlanBetter** is a benefits-decision platform for small/mid businesses. The
> brand promise — *we help you put the picture together* — is encoded in the logo,
> which is a **puzzle piece**. Tone: calm, premium, plainspoken. The opposite of
> loud HR-tech.

---

## 1. Visual Theme & Atmosphere

Warm, confident, editorial. A "warm paper" off-white canvas carries deep teal and
a green-leaning near-black. Generous whitespace, large humanist headlines, and one
ownable signature move: the **puzzle-piece aperture** (photography seen *through*
the logo mark). It should feel like a steady colleague who has done the homework —
reassuring, never hyped.

Keywords: calm · confident · warm · uncluttered · premium · human.

---

## 2. Color Palette & Roles

### Core (the whole brand runs on three)
| Token | Hex | Role |
|------|-----|------|
| Accent (teal) | `#026163` | The signal color. Primary surfaces, brand moments, key CTAs, links. |
| Black (green-black) | `#001c16` | Headlines, body text, deep backgrounds. Never pure `#000`. |
| Off-white (cream) | `#f6f2e9` | Default canvas. Warm, paper-like — the room everything lives in. |

### Teal tonal scale (UI, charts, states)
`50 #e6efee` · `100 #c2d9d8` · `200 #8fbab9` · `300 #4f928f` · `400 #1f7a78` ·
`500 #026163` · `600 #024e50` · `700 #023a3b` · `800 #012827` · `900 #001c16`

### Usage rules
- **Backgrounds alternate** cream → white (`#ffffff`, for crisp cards) → teal (`#026163`) → black (`#001c16`) to pace the page.
- Pure white (`#ffffff`) is used **only** for product/logo display cards, not as the page canvas.
- Text on cream/white: `#001c16`. Text on teal/black: `#f6f2e9` (cream), never pure white.
- Accent teal for links, primary buttons, and small emphasis spans inside headlines.
- Borders/hairlines: black at 10–12% opacity on light; cream at 15–25% on dark.

---

## 3. Typography Rules

### Font Family
- **Display / headlines / the logo wordmark:** **Mozilla Text** (humanist, warm, variable 200–700). CSS var `--font-display`.
- **Body / UI / buttons / captions:** **PT Sans** (Regular, Bold + italics). CSS var `--font-sans`.
- Self-host via `next/font/local`. Substitute fallbacks: Mozilla Text → a humanist serif-adjacent sans; PT Sans → `system-ui, sans-serif`.

### Hierarchy
| Level | Font / weight | Size | Tracking |
|------|----------------|------|----------|
| Display | Mozilla Text SemiBold | `text-6xl`→`text-7xl`+ | `tracking-tight` (~ -2%) |
| H1 | Mozilla Text SemiBold | `text-5xl` | `tracking-tight` |
| H2 | Mozilla Text Medium | `text-3xl` | `tracking-tight` |
| Lead | PT Sans Regular | `text-xl` / 20px | normal, `leading-relaxed` |
| Body | PT Sans Regular | `text-base` / 16px | normal, `leading-relaxed` |
| Caption / eyebrow | PT Sans Bold | `text-xs`–`text-sm` UPPERCASE | `tracking-[0.18em]–[0.24em]`, teal-600 |

### Principles
- Headlines are tight and confident; lean on size + weight, not color.
- One accent-teal word inside a black headline is the maximum color emphasis.
- Eyebrows are small-caps PT Sans Bold with wide tracking and a short hairline rule.
- Never em-dash in headlines.

---

## 4. Component Stylings

### Buttons
- **Primary:** `rounded-full`, solid cream on teal/dark surfaces or solid accent on light, PT Sans medium, `px-6 py-3`, hover `scale-105`.
- **Secondary:** `rounded-full` outline (`border border-cream/40` on dark), hover subtle fill (`bg-cream/10`).
- **Chip / utility (downloads etc.):** `rounded-full`, thin bordered, `text-xs uppercase tracking-wide`, leading icon.

### Cards & Containers
- Radius: `rounded-2xl` (≈1rem) standard; `rounded-[2rem]` for hero/feature panels.
- Light cards: `bg-white ring-1 ring-black/10`. Tinted cards: `bg-cream`, `bg-accent`, `bg-black`, or `bg-teal-800`.
- Inner padding `p-8 md:p-12`. Card grids gap `gap-5`.

### Navigation
- Sticky, `bg-cream/80 backdrop-blur-md`, hairline bottom border, `max-w-7xl` inner.
- Mark + wordmark left; text links right (`text-black/60`, hover `text-accent`).

### Image Treatment — the SIGNATURE move
- **Puzzle-piece aperture:** photography is masked by the logo-mark silhouette so the
  image is seen *through* the puzzle piece. Implement with CSS `mask-image` of the
  mark SVG (`mask-size: contain; mask-repeat: no-repeat; mask-position: center`).
- Subjects: real SMB professionals in genuine, warm work moments (never stiff stock).
- Place apertures on a teal panel so the cutout reads. Optionally a faint second mark
  eases into frame to imply "the picture coming together."

---

## 5. Layout Principles

- **Container:** `max-w-7xl`, horizontal padding `px-6 md:px-10`.
- **Section padding:** `py-20 md:py-28` (teal feature sections may go `py-32`).
- **Section dividers:** hairline `border-t border-black/10` between sections.
- **Spacing base:** 4px scale (Tailwind default). Whitespace is generous — let
  headlines breathe; don't crowd the mark (clear space = one "step" of the symbol).
- **Border radius scale:** chips `full` · cards `1rem` · hero panels `2rem`.

---

## 6. Depth & Elevation

- Elevation is soft and sparing. Signature shadow for hero/photo panels:
  `shadow-[0_40px_90px_-35px_rgba(0,28,22,0.65)]` (a deep teal-black, never gray).
- No hard drop shadows on cards; use `ring-1` hairlines for separation instead.

---

## 7. Motion

- **Library:** Framer Motion.
- **Default entrance (`fadeUp`):** `opacity 0→1`, `y 24→0`, `duration 0.7`,
  `ease [0.16, 1, 0.3, 1]`, `viewport={{ once: true, amount: 0.3 }}`.
- **Signature beats (use sparingly, 2–3 per page max):**
  - Logo mark **path-draws** in (`pathLength 0→1`, ~1.4s).
  - Puzzle aperture photo does a slow **settle-zoom** (`scale 1.12→1`, ~6.5s ease-out).
  - A faint **completing piece** eases into frame after the aperture settles.
- Principle: subtle, generous easing, no bouncy springs. Always honor
  `prefers-reduced-motion`.

---

## 8. Do's and Don'ts

### Do
- Lead with the puzzle aperture — it's the most ownable visual.
- Keep copy plainspoken: name the worry, then take the weight off.
- Alternate cream / white / teal / black to pace the page.
- Use one accent word per headline, max.
- Let the mark have room; treat it as a puzzle piece, not a generic icon.

### Don't
- Don't use pure black (`#000`) or pure white as the page canvas.
- Don't write AI-tell copy: "Empower / Unlock / Seamlessly / Leverage", three vague
  feature cards, manifesto blocks, or "Not because X — because Y" constructions.
- Don't put em-dashes in headlines.
- Don't recolor, rotate, stretch, or crowd the mark.
- Don't use stiff, generic stock photography in the aperture.

---

## 9. Responsive Behavior

- **Breakpoints:** Tailwind defaults; key shift at `md` (768px) and `lg` (1024px).
- **Type:** scale display down (`text-7xl`→`text-5xl`) without losing weight/impact.
- **Touch targets:** min 44px.
- **Collapsing:** multi-column card grids → single column; hero two-column → stacked
  with the aperture leading.
- **Motion:** drop heavy scroll-linked effects on mobile; keep entrances.

---

## 10. Agent Prompt Guide

### Quick reference
```
Accent teal   #026163
Black         #001c16   (green-black, never pure)
Off-white     #f6f2e9   (warm canvas)
Display font  Mozilla Text (SemiBold/Medium), tracking-tight
Body font     PT Sans (Regular/Bold)
Radius        chips full · cards 1rem · panels 2rem
Container     max-w-7xl, px-6 md:px-10, sections py-20 md:py-28
Motion        Framer Motion, fadeUp ease [0.16,1,0.3,1]
Signature     puzzle-piece aperture (mark as CSS mask over photography)
```

### Globals (Tailwind v4 `@theme`) — paste to scaffold
```css
@theme inline {
  --color-accent: #026163;
  --color-black:  #001c16;
  --color-cream:  #f6f2e9;
  --color-teal-50:#e6efee; --color-teal-100:#c2d9d8; --color-teal-200:#8fbab9;
  --color-teal-300:#4f928f; --color-teal-400:#1f7a78; --color-teal-500:#026163;
  --color-teal-600:#024e50; --color-teal-700:#023a3b; --color-teal-800:#012827;
  --color-teal-900:#001c16;
  --font-display: var(--font-mozilla);
  --font-sans:    var(--font-ptsans);
}
```

### Example prompts
- "Build a pricing page in the PlanBetter system: cream canvas, Mozilla Text
  headlines with one teal accent word, PT Sans body, `rounded-2xl` white cards with
  `ring-1 ring-black/10`, a teal CTA section, and `fadeUp` entrances."
- "Create a feature hero using the puzzle-piece aperture: a warm SMB-workplace photo
  masked by the logo mark on a teal panel, with a faint completing piece easing in."
- "Design a stat band on `bg-black` with `text-cream`, teal-200 eyebrows, and a slow
  count-up — keep motion subtle, honor reduced-motion."

### Iteration guide
- Too loud? Reduce accent usage, add whitespace, drop a shadow.
- Feels generic? Bring the puzzle aperture forward; specify the photo subject.
- Copy reads AI-generated? Rewrite plainspoken; cut hype verbs and em-dashes.

---

*PlanBetter Brand Kit · v1.0 · 2026. Mark = puzzle piece: we help you put the picture together.*