# CLAUDE.md — BT Web Group Packages Project

Guidance for Claude when building **any** asset in this repo: marketing web pages,
service/bundle/tripwire pages, email templates (eblasts), landing pages, or copy.

---

## 0 — The two rules that override everything

1. **Source of truth is `PACKAGES.md` + `FINALIZATION_QUESTIONS.md`. Read both before
   writing or editing any page, email, price, name, or fact.** Never invent a price,
   tier name, phone number, address, testimonial, or stat. If a value isn't in those
   files, ask — don't guess.

2. **Match the *look and feel* of `packages-html/packages-root.html`. Do NOT copy
   its *structure*.** Every new page gets a unique layout/section order/composition,
   but the visual language (tokens, type, color, components, spacing rhythm, motion)
   must feel like it came from the same brand. `packages-root.html` is the canonical
   design reference — open it when in doubt.

---

## 1 — Source-of-truth files

| File | Holds | Use it for |
|---|---|---|
| `PACKAGES.md` | Prices, tier names, market rates, feature bullets, bundle math, CRM context slugs, AI display rules, the list of downstream files to keep in sync | Any number, package name, or feature bullet that appears on a page or in an email |
| `FINALIZATION_QUESTIONS.md` | The owner's finalized decisions: brand/contact facts, testimonials, client logos, case-study numbers, assessment copy, email/UTM rules, AI-page scope, visual direction | Brand facts, proof content, copy decisions, and "is this allowed yet?" scope calls |

**Precedence when they disagree:** `FINALIZATION_QUESTIONS.md` answers are the most
recent human decision and win. When you act on one, reconcile `PACKAGES.md` to match in
the same change, and call out the drift to the user. (Example: `PACKAGES.md` still says
"12 years / since 2014" but the finalized answer is "20+ years / since 2005".)

**When you change a price or name:** update `PACKAGES.md` first, then every downstream
file it lists in §6 (service pages, bundle pages, tripwire pages, AI pages, eblasts).
Keep them in sync in one pass.

---

## 2 — Design system (the look & feel to replicate)

All of the following is lifted from `packages-html/packages-root.html`. Reuse the
tokens and component patterns; invent your own page structure around them.

### 2.1 Scoping & paste-safety (non-negotiable build rule)
- Pages are **Beaver Builder paste-safe**: no `<html>`, `<head>`, or `<body>`. A page is
  self-contained — inline `<link>` font tags, one or more `<style>` blocks, the markup,
  and an optional inline `<script>`.
- **Scope every rule under a single wrapper class** so styles never leak into the host
  site. Root uses `.btwx`; shared components use `.btw-pkg`. For a new page, reuse
  `.btwx` (cleanest, matches root) or a page-unique scope (e.g. `.btwx-seo`) — but pick
  one and prefix **every** selector with it.
- Reset inside scope: `box-sizing: border-box`, `img/svg { max-width:100%; display:block }`,
  list/button/heading resets, `:focus-visible` outline. Copy root's reset block.

### 2.2 Design tokens — copy this block into each new page's scope
```css
.btwx {
  /* ink / text */
  --ink:#111827; --ink-soft:#1f2937; --body:#4b5563; --muted:#6b7280; --faint:#9ca3af;
  /* gold (PRIMARY action/emphasis — buttons use dark --ink text on gold) */
  --gold:#fbb416; --gold-hover:#f0a500; --gold-dark:#a87800; --gold-deep:#946a00; --gold-tint:#fff6e0;
  /* brand green (SECONDARY — outline buttons, checkmarks, icon tiles, links, washes) */
  --green:#6c9a2e; --green-dark:#5d8527; --green-deep:#4b6d1f; --green-tint:#f1f6e8;
  /* surfaces */
  --bg:#ffffff; --bg-alt:#f7f8fa; --bg-soft:#fbfcfd; --card:#ffffff;
  --border:#e6e8ec; --border-strong:#d4d8df;
  /* shape */
  --radius:16px; --radius-sm:10px; --radius-pill:999px;
  --shadow-sm:0 1px 2px rgba(16,24,40,.05),0 1px 3px rgba(16,24,40,.07);
  --shadow-md:0 4px 14px rgba(16,24,40,.07);
  --shadow-lg:0 14px 36px rgba(16,24,40,.10);
  --font:'Montserrat',-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;
}
```

### 2.3 Principles
- **Light surfaces only.** Alternate sections between `--bg` (white) and `--bg-alt`
  (#f7f8fa). No dark sections — v3 deliberately removed them. Subtle green-tint radial
  gradients are the only "color wash."
- **Gold is the PRIMARY action/emphasis color (~70%); green is secondary (~30%).** Primary
  buttons are gold fill with **dark `--ink` text** (never white-on-gold — fails contrast);
  eyebrows, hero/heading `.accent` words, key numbers, savings/value pills, "Most popular"
  sticker and review stars are gold. Green is for **secondary** elements: outline buttons
  (green border + `--green-deep` text), checkmarks/tick badges, icon tiles (`--green-tint`
  discs), links, focus rings, section washes, and decorative product mockups.
- **Generous vertical rhythm:** sections are `padding: 88px 0` (tighten the *top* only
  when two content sections butt together, e.g. proof after guarantees → `28px 0 88px`).
- **Container:** `.x-wrap { max-width:1180px; margin:0 auto; padding:0 40px }` (20px on
  mobile).
- **Type scale:** H1 `clamp(38px,5.2vw,60px)`/800; section title `clamp(28px,3.6vw,40px)`/800
  with `letter-spacing:-0.02em`; body 16–17px/1.6–1.7; small meta 12–14px. Hero supporting
  copy is intentionally **#000 / weight 600** for contrast over imagery.
- **Section header pattern:** eyebrow (uppercase, 700, `letter-spacing:.08em`, green, with
  a short dash before it) → title (800) → subtitle (`--muted`). Center variant exists.

### 2.4 Component vocabulary (reuse, recompose freely)
- **Buttons** `.x-btn`: `--primary` (green fill, white text, lifts on hover),
  `--secondary` (white, `--border-strong` outline), `--sm`, `--block`. 52px tall (44 for sm),
  `--radius-sm`, weight 600.
- **Cards:** white, `1px var(--border)`, `--radius`, `--shadow-sm`; hover →
  `translateY(-4px)` + `--shadow-lg` + `--border-strong`. Used for tiers, bundles, quick
  wins, promises, steps, testimonials.
- **Check lists** `.x-checks`: green circular ✓ badge bullets (`--green-tint` disc + SVG
  tick). Standard for all feature lists.
- **Pricing display:**
  - Show a **market-rate strikethrough** (`.x-strike`, `--muted`, `line-through`, weight
    600 — must stay legible, not faint) next to / above the real price.
  - Cadence line under the price (`.x-tier-cad`) is `--muted` weight 600.
  - **AI pricing is always two separate line items:** `Activation: $X (one-time)` +
    `Maintenance: $Y/mo`. Never "$X setup + $Y/mo". (See `PACKAGES.md` §0.)
  - "Most popular" tier gets `--green-tint` background + inset green ring + gold sticker.
- **Trust/logo strip:** light band, grayscale logos that color on hover. Root uses an
  infinite auto-scroll marquee (duplicated track, `translateX(0→-50%)`, pause on
  hover/focus, reduced-motion fallback to a static wrapped row). Reuse this pattern.
- **FAQ:** native `<details>/<summary>` accordion with a rotating chevron.
- **Lead capture:** primary CTAs are buttons with `data-btw-lead-open="<crm-context>"`
  (the CRM context slug from `PACKAGES.md`, e.g. `service-seo-growth`, `bundle-lead-engine`,
  `tripwire-chatbot`). Don't hardcode a form action; the host wires the modal.

### 2.5 Motion & accessibility
- **Scroll reveal:** add class `xr` to reveal targets; an IntersectionObserver adds `.on`.
  Always ship a `@media (prefers-reduced-motion: reduce)` block that disables transforms
  and shows everything.
- Marquees/animations must pause or disable under reduced motion.
- Real `aria-label`s on icon-only / link stats; decorative duplicates get `aria-hidden`
  + `tabindex="-1"`; visible `:focus-visible` outline (green) everywhere.

### 2.6 Imagery
- Source photos via the **Unsplash MCP** (`search_photos`), landscape, relevant to the
  page topic. Per `FINALIZATION_QUESTIONS.md` Q27–28 this is the chosen approach for hero
  and per-service imagery.
- Used as a **faint background under a white veil** so dark text stays readable
  (e.g. `linear-gradient(105deg, rgba(255,255,255,.90), …,.68)` over the photo, green
  radial on top). Don't let imagery fight the copy.

---

## 3 — Email templates (eblasts)

- Follow the same brand palette and type feel, but use **email-safe, table-based,
  inline-styled HTML** (not the `.btwx` class system — email clients need inline styles).
- **Sender identity:** `From: Brian Evans - BT Web Group (hello@btwebgroup.com)`.
- **UTM rule:** every link that originates from an eblast carries
  `?utm_source=eblast&utm_campaign=<campaign>` (and `utm_medium=email`). Organic/non-eblast
  links stay clean. (Q21.)
- **CAN-SPAM footer:** physical address `168 E. Reynolds Rd. Lexington, KY 40517`, plus
  unsubscribe + company-registration block (owner will supply final unsub/reg text — leave
  a clearly-marked placeholder, don't fabricate). (Q20.)
- **Positioning in every eblast:** communicate that BT Web Group uses modern **AI platforms
  and the latest technology** — the client should see us as a modern tech provider. (Q22.)
- Prices/offers quoted in email copy must match `PACKAGES.md`.

---

## 4 — Confirmed brand & contact facts (cross-check against the source files)

- **Phone:** (859) 523-3053 · **Email:** hello@btwebgroup.com
- **Address:** 168 E. Reynolds Rd. Lexington, KY 40517
- **Tenure / proof:** 20+ years, serving Kentucky since 2005 · 100+ KY businesses · 5.0 ★
  Google reviews (show the multicolor Google "G") · <1 business-day response
- **Logo:** https://btwebgroup.com/wp-content/uploads/2023/11/BT-NEW-LOGO-Glossy-2@4x.png
- **Guarantees:** month-to-month, no setup fees on marketing, cancel anytime, full data
  export in 5 business days, genuinely-free $500 marketing assessment (PDF report walked
  through on the call).
- **Testimonials / client logos / case-study numbers:** use only what's in
  `FINALIZATION_QUESTIONS.md` §B (Q7–Q9). Condensing long quotes for layout is fine; keep
  the person's voice and never alter names/businesses.

---

## 5 — Known open items / do-not-ship-without-confirming

- **Brand font conflict:** `packages-root.html` ships **Montserrat**, but
  `FINALIZATION_QUESTIONS.md` Q6 specifies **Gilroy-Regular**. Unresolved — confirm with
  the owner before switching the font stack project-wide. Until resolved, match the
  reference page (Montserrat) and note the discrepancy.
- **CRM webhook URL:** placeholder; owner configures later (Q3). Don't hardcode an endpoint.
- **AI proof:** no live chatbot/automation pilot exists yet — **do not** publish fake
  conversation logs, HIPAA disclaimer, or pilot claims (Q25–26).
- **AI chatbot maintenance tiers:** only "from $497/mo" is confirmed; don't invent
  Growth/Pro monthly prices (Q12).

---

## 6 — Pre-ship checklist for any page or email

1. Read `PACKAGES.md` + `FINALIZATION_QUESTIONS.md`; every number/name/fact traced to them.
2. Unique structure, but `.btwx` tokens + component patterns from `packages-root.html`.
3. Light surfaces, green primary / gold emphasis, generous spacing, legible market-rate
   strikethrough.
4. AI pricing shown as Activation + Maintenance line items.
5. CTAs carry the correct `data-btw-lead-open` CRM context slug.
6. Reduced-motion fallback present; focus states visible; aria labels correct.
7. All external image URLs return 200.
8. Emails: inline styles, UTM on eblast links, CAN-SPAM footer, AI/modern-tech messaging.
9. If a price/name changed, `PACKAGES.md` and all downstream files updated in the same pass.
