This commit is contained in:
Oleg Maslov
144
docs/redesign-warm-hive/PR8-BUILD-PLAN.md
Normal file
144
docs/redesign-warm-hive/PR8-BUILD-PLAN.md
Normal file
@@ -0,0 +1,144 @@
|
||||
# Warm-Hive Redesign — PR8 Build Plan (`apps/www` landing → warm-Hive identity)
|
||||
|
||||
> Source design package: `docs/design_handoff_waggle_app/` — esp.
|
||||
> `design-files/Waggle Landing.html` (648 lines, the canonical landing reference) +
|
||||
> `design-files/styles/waggle.css` (token master) + `README.md §9` (landing copy notes).
|
||||
> Roadmap slot: `BUILD-PLAN.md §6` — **PR8, the final roadmap item** (PR1–PR7 all shipped to origin/main @ `58f64f22`).
|
||||
> Branch: `feature/warm-hive-pr8`. Merge convention: `--no-ff` (PR5/PR6/PR7 pattern).
|
||||
|
||||
---
|
||||
|
||||
## 0. Strategic gate — scope fork (resolved by evidence, recommend-and-proceed)
|
||||
|
||||
PR8's slot in §6 reads "**full content + identity**." Recon resolved this:
|
||||
|
||||
- **Content already shipped.** `apps/www` is a complete Next.js 15 (App Router) landing with
|
||||
deliberate, current copy — `app/page.tsx:24-28` documents the live structure as the chosen
|
||||
**"N2 IA"** with "the committed flat copy" (hero = *"Be the expert. We'll be the AI."*).
|
||||
`messages/en.json` (311 lines) holds the full marketing copy, intentionally **evolved past**
|
||||
the older `Waggle Landing.html` reference (current = 5 pillars + comparison/wow beats; the
|
||||
reference HTML = 6 pillars + BYO-agent + self-evolving sections). The current copy is the
|
||||
newer direction and is committed.
|
||||
- **Identity is stale.** `app/globals.css:4-26` still carries the **pre-redesign cool palette**
|
||||
(`--hive-950:#08090c`, `--honey-500:#e5a000`, blue-grey hive greys, saturated `--status-ai
|
||||
#a78bfa`/`--status-healthy #34d399`) and **Inter** as the typeface — none of the warm-Hive
|
||||
identity PR1 applied to `apps/web`.
|
||||
|
||||
**Ratified scope (recommend-and-proceed unless founder objects):**
|
||||
**PR8 = identity reskin only.** Port the warm-Hive token values + Hanken Grotesk + honey-accent
|
||||
discipline + honeycomb/hex motifs onto the existing N2 landing. **Do NOT rewrite copy** to the
|
||||
older reference HTML. **Do NOT touch benchmark/proof claims** (honest-stats — see §5). Treat the
|
||||
reference HTML as the source of truth for *visual treatment*, `en.json` as the source of truth
|
||||
for *copy*.
|
||||
|
||||
---
|
||||
|
||||
## 1. Design contract (what "warm-Hive" means for the landing)
|
||||
|
||||
From `waggle.css §7` (and as implemented in `apps/web` PR1):
|
||||
|
||||
- **Dark default** surfaces: `--bg #14110b · --surface #1f1a12` (warm graphite, replaces cool `#08090c`).
|
||||
- **Honey accent**: `#e9a52c` (replaces `#e5a000`), used *sparingly* — primary buttons, active nav,
|
||||
key metrics, focus rings, 1–2 highlight words per headline. Never decorative fills.
|
||||
- **Type**: **Hanken Grotesk** (display+body, 300–800; headings 600 at `-0.02..-0.03em`) +
|
||||
**JetBrains Mono** (mono labels). Replaces Inter.
|
||||
- **Desaturated semantics**: `--intel #b196dd` (was `#a78bfa`), `--healthy #6cb78c` (was `#34d399`).
|
||||
- **Motifs**: honeycomb `.05` opacity SVG texture (warm line stroke), hexagon clip-path for the W
|
||||
mark / persona tiles, warm shadows + honey glow.
|
||||
- **Dark-only** for the landing (current site has no light theme; the design specifies both, but
|
||||
adding a landing theme toggle is out of reskin scope → deferred, §8).
|
||||
|
||||
---
|
||||
|
||||
## 2. Current state (grounded, file:line)
|
||||
|
||||
| Fact | Evidence |
|
||||
|---|---|
|
||||
| Next.js 15.1 App Router, React 19, TS 5.9, **vanilla CSS (no Tailwind)** | `apps/www/package.json:14-24`, `globals.css:2` |
|
||||
| Tokens = old cool palette + Inter | `globals.css:4-40` |
|
||||
| Components style via inline `var(--hive-*)`/`var(--honey-*)` → value remap cascades | grep across `app/_components/*` |
|
||||
| **Hardcoded** hex (bypasses vars) — must fix explicitly | `layout.tsx:38-91` (Clerk), `HeroVisual.tsx:62-309` (SVG), `BrandPersonasCard.tsx:343-417` (`<style>`) |
|
||||
| Honeycomb SVG uses URL-encoded old hex `%231f2433` | `globals.css:54` |
|
||||
| Honey rgb literal `229,160,0` in glow/selection/shadow | `globals.css:21,22,25,48` |
|
||||
| Clerk + Stripe + next-intl wired; legal routes + sign-in/up + account exist | `layout.tsx`, `app/api/stripe/*`, `app/(legal)/*` |
|
||||
| Single FE test (`BrandPersonasCard.test.tsx`); vitest | `__tests__/`, `vitest.config.ts` |
|
||||
|
||||
---
|
||||
|
||||
## 3. Decisions (recommend-and-proceed)
|
||||
|
||||
| # | Decision | Choice | Why |
|
||||
|---|---|---|---|
|
||||
| D1 | Scope | **Reskin, not rebuild** | Content is current/committed (N2 IA, `page.tsx:24`); only identity is stale |
|
||||
| D2 | Token strategy | **Remap var VALUES 1:1 by scale stop**, keep var NAMES | Components reference vars → one cascade restyles all (PR1 method) |
|
||||
| D3 | Hardcoded hex | **Literal remap table** applied to `app/**/*.{tsx,ts,css}` | Catches Clerk/SVG/style-block hex + stale fallbacks in one auditable pass |
|
||||
| D4 | Font | **Hanken Grotesk + JetBrains Mono** via `next/font/google` | Design typeface; `next/font` keeps SSR/perf |
|
||||
| D5 | Light theme | **Defer** (keep dark-only) | Landing has no toggle today; adding one is out of reskin scope (§8) |
|
||||
| D6 | Proof/benchmark copy | **Untouched** | Honest-stats — conservative framing is deliberate; upgrading to 87.66 SOTA is a founder call |
|
||||
| D7 | Deploy/env (Clerk/Stripe prod keys, Vercel) | **Documented, not executed** | EXTERNAL-DEP, founder-provisioned at deploy (§6) |
|
||||
|
||||
### Token remap table (old cool → warm-Hive, verbatim from `waggle.css`/`apps/web` PR1)
|
||||
```
|
||||
hive 950 #08090c→#0e0c07 900 #0c0e14→#14110b 850 #11141c→#1a160f 800 #171b26→#1f1a12
|
||||
700 #1f2433→#272117 600 #2a3044→#4a4030 500 #3d4560→#6b6250 400 #5a6380→#948a73
|
||||
300 #7d869e→#c8bfa9 200 #b0b7cc→#d8cfba 100 #dce0eb→#ece3d0 50 #f0f2f7→#f6f1e4
|
||||
honey 600 #b87a00→#c07e16 500 #e5a000→#e9a52c 400 #f5b731→#f6c45a 300 #fcd34d→#f9d27e
|
||||
sem status-ai #a78bfa→#b196dd status-healthy #34d399→#6cb78c
|
||||
rgb honey 229,160,0 → 233,165,44
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Architecture (do NOT recreate)
|
||||
|
||||
- Keep next-intl/Clerk/Stripe wiring, the hero A/B variant resolver infra, the `_data`/`_lib`
|
||||
modules, legal routes, sitemap, event taxonomy — all untouched by a reskin.
|
||||
- Reuse the existing inline-CSSProperties + global-CSS pattern. No Tailwind, no new CSS framework.
|
||||
- Named warm tokens (`--bg`,`--surface`,`--text`,`--line`, semantics) are *added* alongside the
|
||||
remapped `--hive-*`/`--honey-*` scales for future use, but components keep using the scale vars.
|
||||
|
||||
---
|
||||
|
||||
## 5. No-fabrication contract (F-traps gated off)
|
||||
|
||||
| F | Trap | Gate |
|
||||
|---|---|---|
|
||||
| F1 | Upgrading proof copy to 87.66 SOTA under cover of "reskin" | Benchmark/proof strings in `en.json` **left byte-identical** |
|
||||
| F2 | Inventing testimonials (`proof.human_quote` is intentionally empty) | Leave empty |
|
||||
| F3 | Claiming light theme works when not added | Don't add toggle; note as deferred |
|
||||
| F4 | Drifting tier prices/names while editing | Pricing copy untouched (color-only) |
|
||||
| F5 | "Deployed/live" claims | Smoke is local `next dev`; deploy is EXTERNAL-DEP, documented not executed |
|
||||
|
||||
---
|
||||
|
||||
## 6. EXTERNAL-DEP (founder-provisioned at deploy — not build blockers)
|
||||
|
||||
| Dep | Needed by | Absent behavior |
|
||||
|---|---|---|
|
||||
| `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` + secret | prod sign-in/up | Build/dev render; auth round-trip needs real keys |
|
||||
| Stripe live keys + 4 price IDs + webhook secret | prod checkout | `checkout` route already fails honestly without |
|
||||
| Vercel project + `waggle-os.ai` DNS | go-live | per `docs/launch/drafts/2026-05-12-apps-www-deployment-readiness.md` |
|
||||
|
||||
---
|
||||
|
||||
## 7. Phased plan + gates
|
||||
|
||||
- **A — Tokens & type** (`globals.css`, `layout.tsx`): remap `:root` values, honeycomb stroke,
|
||||
honey rgb, font Inter→Hanken+JetBrains Mono, heading styles, Clerk appearance hex→warm.
|
||||
- **B — Hardcoded-hex sweep** (`HeroVisual.tsx`, `BrandPersonasCard.tsx`, page-level fallbacks,
|
||||
`methodology/page.tsx`): apply remap table; re-grep proves zero old-palette hex remains in `app/`.
|
||||
- **C — Verify**: `tsc --noEmit` (apps/www) 0 · `next build` green · `next lint` clean · `vitest run` green.
|
||||
- **D — Adversarial review** (workflow): design-fidelity/leak, honest-stats, security(keys), correctness, a11y/contrast. Fix HIGH+MEDIUM.
|
||||
- **E — Live smoke**: `next dev`, screenshot landing + sign-in, **0 console errors**; commit
|
||||
`smoke-pr8-<date>/REPORT.md` + PNGs.
|
||||
- **F — Ship**: merge `--no-ff`, push origin, handoff + MEMORY.md START HERE.
|
||||
|
||||
**Gate (before merge):** tsc 0 · build green · lint clean · vitest green · review HIGH/MEDIUM clear · smoke 0 console errors.
|
||||
|
||||
---
|
||||
|
||||
## 8. Honesty log / deferred
|
||||
- Landing stays **dark-only**; warm light-paper theme + a nav theme toggle deferred (design supports it; out of reskin scope).
|
||||
- Proof copy stays conservative (67.8% AND-of-3); upgrading to the now-public 87.66 SOTA headline is a founder content decision, not this PR.
|
||||
- Older `Waggle Landing.html` has 6 pillars + BYO-agent + self-evolving sections the live N2 IA folds/omits; reconciling content to the reference is a separate content PR, not this reskin.
|
||||
- `methodology/page.tsx` + page fallbacks updated for hex consistency though vars already cascade.
|
||||
Reference in New Issue
Block a user