# Paralegent AI — Design System (canonical)

> **Status:** Live · this document describes what the homepage at `/` actually ships today.
> **Benchmark:** the homepage (`app/_home/HomeV2Body.tsx` + `app/_home/v2.css`) is the reference. If a future change disagrees with this doc, the homepage wins and this doc is updated.
> **Last sync:** 2026-05-11.
> **Sync rule:** any token / component / pattern change must update both the homepage and this file in the same commit.

---

## Table of Contents

| § | Section |
|---|---|
| 01 | [Manifesto](#01--manifesto) |
| 02 | [Foundations — colors · type · spacing · radius · motion](#02--foundations) |
| 03 | [Where everything lives (file map)](#03--where-everything-lives) |
| 04 | [Section primitives (`.v2-*` classes)](#04--section-primitives) |
| 05 | [Custom components rendered on the homepage](#05--custom-components) |
| 06 | [Homepage section rhythm](#06--homepage-section-rhythm) |
| 07 | [Header & Footer](#07--header--footer) |
| 08 | [Voice & vocabulary](#08--voice--vocabulary) |
| 09 | [Anti-patterns](#09--anti-patterns) |
| 10 | [GEO / AEO / SEO rules](#10--geo--aeo--seo-rules) |
| 11 | [Accessibility floor](#11--accessibility-floor) |

---

## 01 — Manifesto

Paralegent's site should feel like a research-grade due-diligence brief that happens to be a website. Editorial discipline. Generous whitespace. Confident typography. Hairline geometry instead of pillow shadows.

**What we reject**
- AI-startup gradient meshes, glassmorphism, chatbot iconography.
- 2018-SaaS pillow cards with 24-px shadows and 16-px radius.
- Pure brutalism — for enterprise legal it reads as hostile. We borrow neo-brutalist moves (sharp borders, oversized type, asymmetric grids) inside editorial restraint.

**What we commit to**
- Editorial typography first. The Inter 700 ↔ Inter 300 contrast is the brand.
- Geometry over decoration — borders, dot grids, mono labels. No ornament.
- One signature kinetic moment per page. Total motion budget < 400 ms per visible viewport. Always honor `prefers-reduced-motion`.

---

## 02 — Foundations

### 02.1 — Color

All design tokens live in `tailwind.config.ts` (the canonical source of truth) and are referenced from `app/_home/v2.css` and from page markup via Tailwind classes.

| Token (Tailwind class fragment) | Hex | Role |
|---|---|---|
| `primary` | `#FF4800` | CTAs · accents · focus rings · comparison column highlight · footnote underlines · mono `→` arrows · ORANGE tier |
| `primary-hover` | `#E64100` | Button hover |
| `primary-active` | `#CC3A00` | Button active |
| `secondary` | `#042729` | Hero dark zone · dark CTA · brand-scene background |
| `cream` | `#FCFCFA` | Default body bg · alt section bg |
| `peach` | `#FCDED2` | Soft accent tile · tier-card backgrounds |
| `background` | `#FFFFFF` | Tiles needing lift · default white sections |
| `foreground` | `#1F1F1F` | All body text · 2 px editorial borders |
| `text-on-dark` | `#F8F5EE` | Text on `secondary` |
| `muted-spec` | `#6B6B6B` | Captions · labels · mono eyebrows |
| `border-spec` | `#E5E5E2` | Hairline dividers, card borders (warm gray) |
| `tier-green` | `#16A34A` | GREEN tier · check marks |
| `tier-red` | `#DC2626` | RED tier · errors · x marks |

ORANGE tier explicitly re-uses `primary`. WCAG 1.4.1: tier color is always paired with text label + icon — never color alone.

**Usage rules**
- **Cream over white** as the default body color (warmer paper feel).
- **Teal as punctuation** — max 3 zones per page (hero, dark tile, dark CTA).
- **Orange as system color** — not just for CTAs.

### 02.2 — Typography

Single family: **Inter** at weights 300 / 400 / 500 / 600 / 700, plus **JetBrains Mono** for mono eyebrows / labels. Loaded as Next.js fonts in `app/layout.tsx` via `--font-inter` and `--font-mono`. The historical `--font-display` (Instrument Serif) is still loaded but no longer applied to headings.

**Hierarchy**

| Use | Size | Weight | Line | Tracking | Notes |
|---|---|---|---|---|---|
| Hero `<h1>` | clamp(28 → 56) px | 700 | 1.05 | −0.01em | UPPERCASE |
| Section `<h2>` | clamp(28 → 42) px | 700 | 1.1 | −0.005em | sentence case |
| Sub-card `<h3>` | 20 px | 700 | 1.3 | 0 | |
| Sub-card `<h4>` | 17 px | 600 | 1.35 | 0 | |
| Lead body | 17 px | 400 | 1.5 | 0 | post-H1 BLUF |
| Body | 15 px | **300** | 1.6 | 0 | the editorial Light signature |
| Body small | 13 px | 300 | 1.5 | 0 | |
| Mono eyebrow | 11 px | 700 | 1.3 | 1.2 px | UPPERCASE · JetBrains Mono |
| Caption | 11 px | 400 | 1.4 | 0.4 px | |
| Top nav | 13 px | 400 | 1.4 | 0.4 px | |
| Button label | 12 px | 700 | 1.0 | 1.2 px | UPPERCASE |

**Principles**
- The signature is **Inter 700 (display) ↔ Inter 300 (body)**. Never blur it with 400 / 500 body weights.
- UPPERCASE only on: hero H1, mono eyebrows, button labels, section eyebrows.
- All numerals: `font-variant-numeric: tabular-nums` for stat readability.
- Mobile reduction: hero H1 56 → 38, section H2 42 → 32, H3 20 → 18.

### 02.3 — Spacing

Editorial wide-step scale used in section padding and stack gaps:

| Token | px | Use |
|---|---|---|
| `s-1` | 4 | hairline |
| `s-2` | 8 | tight inline |
| `s-4` | 16 | default body gap |
| `s-6` | 24 | card internal padding |
| `s-10` | 40 | stack between content blocks |
| `s-16` | 64 | section internal padding |
| `s-24` | 96 | section vertical padding (desktop) |
| `s-36` | 144 | hero / dramatic vertical padding |

For utility classes outside these multiples, fall back to Tailwind's default scale.

### 02.4 — Radius

| Token | px | Use |
|---|---|---|
| `radius-sharp` | 0 | Bento tiles · comparison cells · spec sheets |
| `radius-soft` | 4 | Buttons · inputs · badges (Tailwind `rounded`) |
| `radius-card` | 8 | Article cards · modals (Tailwind `rounded-md`) |
| `radius-pill` | 9999 | P-mark, dots only |

Hierarchy: **"almost always 0, sometimes circular"** — binary by intent.

### 02.5 — Elevation

Borders carry hierarchy. Shadows appear only on hover and modals. Shadow color is teal-tinted `rgba(4, 39, 41, 0.08–0.16)` — never pure black.

| Level | Treatment | Use |
|---|---|---|
| 0 — flat | none | inline content · default |
| 1 — hairline | `1 px solid border-spec` | resting card · FAQ row · tile |
| 2 — edge | `2 px solid foreground` | active / selected |
| 3 — hover | `1 px border + shadow + translateY(-2px)` | card hover |
| 4 — overlay | `1 px border + 32 px shadow` | modal · overlay |

### 02.6 — Motion

**One signature motion per page** (currently the hero H1 word-stamp on the homepage). Plus three micro-motions:

- **Chevron translate** on button hover — 4 px right, 200 ms.
- **Tile elevation lift** on hover — 2 px translate-y + shadow fade, 200 ms.
- **Footnote underline** on hover — 1 px line draws left → right, 250 ms.

**Hard rules**
- Total motion budget < 400 ms per visible viewport.
- Every animation respects `prefers-reduced-motion`.
- Never animate body text. Never re-trigger animations on scroll-back-up.

---

## 03 — Where everything lives

This is the **file map**. Edits to design tokens happen in these specific files only.

| What | Path |
|---|---|
| Font faces (Inter, JetBrains Mono) | `app/layout.tsx` |
| Color, radius, font-size, spacing, shadow scale | `tailwind.config.ts` |
| Site-wide element base styles (`h1`, `h2`, `p`, `li` defaults) | `app/globals.css` |
| Homepage scoped CSS (`.v2-*` classes — also used by `/product`) | `app/_home/v2.css` |
| Homepage body markup (canonical reference for section vocabulary) | `app/_home/HomeV2Body.tsx` |
| Shared site Header (mega-menu, on every route) | `components/Header.tsx` |
| Shared site Footer (dark) | `components/Footer.tsx` |
| Shared chrome wrapper | `components/SiteChrome.tsx` |
| Stat values, terminology, founder data, page registry | `lib/data/*` + `lib/constants/pages.ts` |
| FAQ data | `lib/data/faqs.ts` |
| JSON-LD schema generators | `lib/schemas/*` |

---

## 04 — Section primitives

These are the scoped CSS classes that the homepage composes from. All live in `app/_home/v2.css`. Anything new added to the page should reuse one of these patterns first; only invent a new class if the existing vocabulary truly doesn't fit.

| Class | Purpose |
|---|---|
| `.v2-hero` | full-bleed hero, accepts `<video class="v2-hero-bg-video">` + `<div class="v2-hero-bg-scrim">` |
| `.v2-hero-grid` | hero 2-col grid (text-left, visual-right) |
| `.v2-hero-bluf` | hero body paragraph (post-H1 BLUF) |
| `.v2-hero-cta-row` | hero buttons row |
| `.v2-hero-tag` | hero audience tagline |
| `.v2-hero-meta` | hero bottom meta strip (label / value pairs) |
| `.v2-bigstmt` / `.v2-bigstmt-inner` / `.v2-bigstmt-stats` / `.v2-bigstmt-stat` / `.v2-bigstmt-arrow` | "30 hrs → 30 min" big-statement section |
| `.sect` + `.sect-white` / `.sect-cream` | section bg variants |
| `.sect-eyebrow` + `.rule` | mono uppercase eyebrow with 32 px orange rule |
| `.sect-head-split` + `.sect-h` + `.desc` | top-aligned 2-col section header (h2 left, description right) |
| `.v2-cards` + `.v2-card` (`.card-num` / `.card-title` / `.card-body` / `.card-cta`) | generic 3-up linked card grid |
| `.v2-vps` + `.v2-vp` (`.vp-num` / `.vp-title` / `.vp-body`) | value-props 3-card grid (oversized numerals) |
| `.v2-class-grid` + `.v2-class-card` (`.green` / `.orange` / `.red` modifiers) + `.v2-class-badge` | 3-tier classification cards |
| `.v2-cmp-wrap` + `.v2-cmp` + `.pl-col` | spec-sheet comparison table with primary-highlighted Paralegent column |
| `.v2-faq-list` + `.v2-faq-row` (`.v2-faq-num` / `.v2-faq-q` / `.v2-faq-a`) | numbered, always-open FAQ |
| `.v2-dcta` + `.v2-dcta-inner` (`.v2-dcta-row` / `.v2-dcta-trust`) | final dark CTA section |
| `.t-green` / `.t-orange` / `.t-red` | inline tier-colored text in headings |

The `.v2` wrapper on the page (`<div className="v2">`) scopes all of the above so they only render where intended.

---

## 05 — Custom components

Five client/server components are composed inside the homepage. They wrap content that doesn't fit the generic primitives.

| Component | File | What it does |
|---|---|---|
| `RoleSwitcher` | `app/_home/RoleSwitcher.tsx` | Auto-cycling 5-tab role switcher (GC / CFO / CIO / CPO / Legal Ops), 4 s per role, IntersectionObserver-gated, prefers-reduced-motion honored. |
| `BriefBento` | `app/_home/BriefBento.tsx` | 6-tile bento — anchor 2×2 peach, 18+ specialists, 15→2 SLA, dark pull-quote 2×1, orange deploy tile, 15-20s match. |
| `Workflow` | `app/_home/Workflow.tsx` | Animated 3-step workflow visualization with SVG mock art for upload / review / done. |
| `WordWalkthrough` | `app/_home/WordWalkthrough.tsx` | Microsoft Word mockup showing the reviewed MSA with redline marks + Paralegent panel. |
| `VideoOverlay` + `VideoOverviewButton` | `app/_home/VideoOverlay.tsx`, `VideoOverviewButton.tsx` | Same-page fullscreen video overlay opened by the hero's "Video Overview" button. Custom-event-based; fullscreens via Fullscreen API inside the click activation. |

---

## 06 — Homepage section rhythm

The live homepage at `/` renders these **15 sections** in order. Each is a `<section>` inside `<main>`. Backgrounds alternate white / cream with the hero (dark video) and Dark CTA (teal) as the two dark zones.

| # | Section | Bg | Purpose | Class hooks |
|---|---|---|---|---|
| 1 | Hero | dark video + scrim | H1 + BLUF + 2 CTAs + meta strip | `.v2-hero` |
| 2 | Big Statement | cream | 30 hrs → 30 min | `.v2-bigstmt` |
| 3 | For Your Role | white | 5-tab auto-cycle (GC / CFO / CIO / CPO / Legal Ops) | `.v2-role-sect` + `<RoleSwitcher />` |
| 4 | The Brief (bento) | cream | 6-tile asymmetric brief | `.v2-brief-sect` + `<BriefBento />` |
| 5 | Value Props (3 commitments) | white | numbered 3-card grid | `.v2-vps` |
| 6 | Product Grid | cream | 6 product cards | `.v2-cards` |
| 7 | Solutions | white | 3 solution cards | `.v2-cards` |
| 8 | How It Works | cream | 3-step Workflow component | `<Workflow />` |
| 9 | Inside the Word Add-in | white | walkthrough + 3 annotation cards | `.v2-word-sect` + `<WordWalkthrough />` |
| 10 | Integrations | cream | "Built on" 10-logo strip | `.v2-int-grid` |
| 11 | Risk Classification | white | 3 tier cards + bold-lead bullets + citation | `.v2-class-grid` + `.v2-blead` |
| 12 | Comparison | cream | spec-sheet table | `.v2-cmp` |
| 13 | Explore More | white | 3 outbound cards | `.v2-cards` |
| 14 | Dark CTA | teal | "Bring the brief…" final CTA | `.v2-dcta` |
| 15 | FAQ | cream | numbered always-open 2-col list | `.v2-faq-list` |

The shared dark `<Footer />` (from `components/Footer.tsx`) renders below #15 on every route.

---

## 07 — Header & Footer

**Header** — `components/Header.tsx`. Sticky mega-menu, ~72 px tall, white background, hairline bottom border. Layout:
- Wordmark left.
- Centered nav row: Product · Solutions · Resources · Company. Hovering reveals a full-bleed white mega menu with multi-column links and a YouTube demo tile on the right.
- Primary "Request a Demo" orange pill on the far right.

The header renders on every route via `SiteChrome`. There are no per-route header variants.

**Footer** — `components/Footer.tsx`. Dark teal (`secondary`), 4-column link grid, social row, founder portrait + bio block, last-updated date, legal links. Renders on every route via `SiteChrome`.

---

## 08 — Voice & vocabulary

### Locked terms — ALWAYS use

- `rulebook` (lowercase) — never "playbook" for our product.
- `accelerator` — production AI accelerator.
- `18+ AI Specialists` — with the `+`.
- `GREEN / ORANGE / RED` — uppercase, every time.
- `deploy in your cloud` — never "hosted" or "our cloud".
- `Request a Demo` — every CTA.
- `Word-Native AI Review` — hyphenated.
- `Multi-Agent Orchestration`.
- `Compliance Explanations`.
- `3-Tier Risk Classification`.

### Banned terms — NEVER use

- `SaaS`, `subscription`, `monthly`, `per-seat`.
- `hosted`, "our cloud", "our servers".
- `platform` (use "accelerator").
- `free trial`, "sign up", "try it free".
- `playbook` for our product (use "rulebook").
- `revolutionizing`, "next-generation", "cutting-edge", "seamless", "unleash", "empower".
- "trusted by X companies" — until we have real signed logos.
- Retracted stats: 312% ROI · 90% accuracy · $99/month · 14-day free trial · 70% reduction.

### V1 → V2 voice diff

| Move | V1 voice | V2 voice |
|---|---|---|
| Hero subtitle | "Paralegent AI is the production AI accelerator that reviews master agreements in 30 minutes — deployed in your cloud." | "**Paralegent** reviews an **80-page+ master agreement** in **30 minutes**. Deployed in your cloud. Your data does not leave." |
| Feature description | "Our rulebook system learns your preferred clauses with deep contextual understanding." | "One rulebook upload. 80–150 terms learned. Every clause from then on, scored against your standard." |
| FAQ opener | "Great question! Paralegent handles your existing rulebook by…" | "Yes. Paralegent ingests your rulebook once — PDF or DOCX, 80–150 terms — and processes it in 4–8 hours." |
| CTA label | "Get Started" / "Sign Up" / "Try Free" | **"Request a Demo"** → `/demo` |
| Number style | "30 hours to 30 minutes" | **"30 hrs → 30 min"** with footnote |

---

## 09 — Anti-patterns

What this site **will not do**.

| Bad | V2 alternative |
|---|---|
| 24 px radius + 24 px shadow pillow card | 0 px radius, 1 px hairline border. Shadow only on hover. |
| Pill CTA with "Get started for free" | 4 px radius, mono UPPERCASE label, mono `→` chevron, locked vocabulary. |
| Accordion FAQ that hides content | Numbered always-open list. AI engines extract verbatim. |
| Fake countdown / urgency timer | Honest framing — "Sandbox demo · 2 weeks". |
| "Trusted by 500+ companies" with placeholder logos | "Built on" framing with real partner logos. |
| Generic AI gradient hero | White + dot-grid OR full-bleed video with teal scrim. |
| Page-level `'use client'` on content pages | SSR only. Client components are leaves. |

---

## 10 — GEO / AEO / SEO rules

These are not stylistic preferences — they are crawler / citation rules.

1. **SSR only** on content pages. AI bots execute zero JS.
2. **One `<h1>` per page**, containing primary keyword or brand.
3. **BLUF after H1** — first 20–25 words answer directly with bold brand + bold stat.
4. **`<h2>` every 300–400 words** — AI engines chunk at H2 boundaries.
5. **120–180 words per H2 section** — never under 50.
6. **2,000–3,500 words on pillar pages** (5.1 average citations vs 3.2 under 800 words).
7. **19+ data points per page**.
8. **≥1 comparison table** (2.5× citation rate) — Paralegent column primary-highlighted.
9. **≥1 bold-lead bullet list** (2.8× citation rate).
10. **≥10 FAQs with FAQPage schema** (2.7× citation rate). Bottom of page, SSR, always-open — never accordions.
11. **JSON-LD `@graph`** with WebPage + FAQPage + BreadcrumbList + Organization (+ HowTo where applicable) on every page.
12. **No fake social proof** — no "trusted by X companies" without real logos.
13. **Performance budgets** — FCP < 0.4 s · LCP < 2.5 s · CLS 0 · INP < 200 ms.

---

## 11 — Accessibility floor

- WCAG AA color contrast on body text and CTAs (orange `#FF4800` on white = 3.55:1 — borderline for normal text; we use it only at 600+ weight or as a button bg with white text).
- Tier colors **always paired with text label + icon** (WCAG 1.4.1).
- Touch targets ≥ 44 px (primary CTA ≥ 48 × 48 px).
- Visible focus rings on every interactive element (3 px primary-tinted).
- Every animation honors `prefers-reduced-motion`.
- Semantic HTML — `<section>`, `<article>`, `<nav>`, `<main>`, `<ol>` for ordered processes.
- Alt text on every meaningful image. Decorative images use `alt=""`.

---

## Sync Rule (read before editing)

The homepage (`/`) is the benchmark. This document follows it. If they disagree, **the homepage wins** and this doc is updated in the same commit that changed the homepage.

When editing this file:
1. Update tokens / sizes / rules / copy.
2. Verify the homepage actually renders what you wrote — open `paralegent.ai/` and check.
3. If a locked token changed, mention it in the commit message.

When editing the homepage:
1. Update the live page (`app/_home/HomeV2Body.tsx`, `app/_home/v2.css`, or `tailwind.config.ts`).
2. Update this file's relevant section in the same commit.
3. Commit message: `feat(home): … (design-system §xx.x updated)`.

---

*End of document. This is the operative system — nothing supersedes it.*