launchframe 0.3.0 → 0.4.0

package/.continue/rules/project.md

@@ -1,285 +1,151 @@
-<!-- AUTO-GENERATED from AGENTS.md — do not edit directly.
-     Run `bash scripts/sync-agent-rules.sh` to regenerate. -->
-
----
-description: Project conventions for AI Website Clone Template
-alwaysApply: true
----
-<!-- BEGIN:nextjs-agent-rules -->
-# This is NOT the Next.js you know
-
-This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.
-<!-- END:nextjs-agent-rules -->
-
-# Launchframe Project (AI Website Cloner + SaaS Rebrand)
-
-## What This Is
-This project was scaffolded by [Launchframe](https://github.com/evangruhlkey/launchframe) via `npx launchframe@latest <url> "<saas idea>"`. It is a Next.js + shadcn/ui + Tailwind v4 base wired with an AI-cloner skill (`/clone-website`) that reverse-engineers a real website pixel-perfectly and then re-skins its copy/branding for the user's SaaS idea.
-
-## Single Source of Truth: `launchframe.config.json`
-At the project root there is a `launchframe.config.json` containing:
-- `url` — the visual source-of-truth to clone
-- `idea` — the SaaS idea used as the rebranding directive after the clone
-
-**Always read this file first** at the start of any cloning or build task. The `/clone-website` skill depends on it.
-
-## What the user says (zero-setup flow)
-Users scaffold with `npx launchframe@latest <url> "<saas idea>"` — `npm install` already ran — then they open this folder and say **Build it** (or **Go**, **Ship it**, **Clone the site**).
-
-When you see that with no other instructions, **start the full clone-website pipeline immediately** using only `launchframe.config.json` for `url` and `idea`. Do not ask them to repeat the URL unless the config is missing or invalid. `/clone-website` is an alias for the same work.
-
-## Tech Stack
-- **Framework:** Next.js 16 (App Router, React 19, TypeScript strict)
-- **UI:** shadcn/ui (Radix primitives, Tailwind CSS v4, `cn()` utility)
-- **Motion:** **Framer Motion** (`framer-motion`) — **default for non-trivial animation** (scroll reveals, staggers, layout, gestures). Use CSS `transition` / `@keyframes` only when they reproduce the target exactly without JS.
-- **Icons:** Lucide React (default — will be replaced/supplemented by extracted SVGs)
-- **Styling:** Tailwind CSS v4 with oklch design tokens
-- **Media:** Real **images & videos** from the target URL, saved under `public/images/` and `public/videos/` (see `.claude/skills/clone-website/SKILL.md` and `docs/research/INSPECTION_GUIDE.md`). Do not ship a “pretty shell” with missing raster/video unless extraction is **blocked** and documented in `docs/research/EXTRACTION_LIMITATIONS.md`.
-- **Deployment:** Vercel
-
-## Priority: images, videos & motion
-Treat these as **first-class deliverables**, not polish at the end.
-
-1. **Raster & video** — Early in recon, inventory every `<img>`, `<picture>` / `<source>`, `<video>`, poster image, and meaningful `background-image` URL. Download into `public/` and reference **local paths** in specs and components. Hero bands and marketing sections often fail visually when a single layer is skipped.
-2. **Motion** — Match the target’s feel: easing, duration, stagger, scroll triggers. Prefer **`motion` from `framer-motion`** for entrance sequences, viewport-driven animations, shared-layout-style transitions, and anything beyond a one-off CSS transition. Note in each component spec whether behavior is **CSS-only** vs **Framer Motion**.
-3. **Illustration & brand marks** — Inline **SVG React components** (not only Lucide) for motifs that repeat across sections: logo glyph variants, dividers, grain/noise overlays, hero “scene” shapes, feature-card mini-compositions. Prefer **`currentColor`** + CSS variables so SVGs inherit theme tokens. For **pixel art**, keep a tight palette (4–8 fills), consistent pixel grid logic, and use `style={{ imageRendering: "pixelated" }}` on upscaled raster OR build pixel SVG paths intentionally — never blurry upscale.
-
-## Production polish for marketing landings *(idea-tailored visuals + motion + brand)*
-
-Use this whenever the page is **authored or minimalist** (internal templates, rebranded clones that still feel flat, or targets that are mostly typography). “Looks OK” is not ship-ready — **production landings** stack multiple visual layers, choreographed motion, and cues that clearly belong to **this** product (`launchframe.config.json#idea`), not any SaaS.
-
-### Idea-tailored imagery *(uniqueness bar)*
-
-Generic decoration fails review. Apply this to **every** hero composition, feature-card illustration, OG image sketch, and major `public/` marketing raster.
-
-1. **Derive metaphors from the idea** — Read `idea` (and product name). List 3–6 concrete nouns/verbs the product owns (e.g. voice → waveform, mic; notes → folded page, margin line; sync → paired arrows). Every bespoke visual must trace back to that list — **not** interchangeable clipart (random apparel, unrelated lifestyle objects, vague “business” silhouettes unless the idea demands them).
-2. **Could this ship on another site unchanged?** If yes, redesign until **no** — different silhouette story, palette accent, or composition so the asset “only fits” this narrative.
-3. **One tie-in sentence per asset** — In specs or `docs/research/REBRAND.md`, each image/SVG scene gets **Idea tie-in:** `<why this belongs to this product>`.
-4. **Prefer authored scenes** — Custom SVG narratives (several shapes telling one moment), optional pixel mascot **on-brand** for the category, or composed raster under `public/images/marketing/` when illustration needs texture. Lucide-only piles and neutral blobs are **last resort**, not default.
-5. **Distinct accents** — Pick accent hues/shapes suggested by the idea’s personality (precise studio vs warm companion vs rugged utility); avoid default gray-only SaaS anonymity unless the brief is explicitly brutalist.
-
-### Imagery density (every fold earns a visual idea)
-
-- **Hero** — Never headline-only on white: add at least two of — soft gradient mesh / radial spotlight, **idea-specific** SVG cluster (metaphors from the list above), notebook/grid lines when the idea is docs, waveform device frame when the idea is capture, masked **purpose-built** raster in `public/images/marketing/`, geometric frame echoing **this** logo shape.
-- **Between sections** — Optional dividers whose pattern/stroke **echoes the product motif** (not a stock wave).
-- **Feature rows** — Each card illustration is a **different** moment in the same visual language (shared stroke weight, accent, or grid) — all still **idea-native** (e.g. capture → transcript lines; workspace → shared cursors; publish → export channels). No unrelated filler.
-- **Social proof** — Logo strip may use grayscale marks; add **slow infinite marquee** or gentle opacity drift — motion sells “living product.”
-
-### Motion choreography *(ship several layers; respect `prefers-reduced-motion`)*
-
-Default minimum bar for authored landings — implement with **`framer-motion`** unless matching CSS-only parity:
-
-| Tier | What users feel | Typical implementation |
-|------|-----------------|-------------------------|
-| **A — Page load** | Hero headline, subcopy, CTAs, and hero art **stagger in** (opacity + `y`, or blur-in for type) | Parent `variants` + `staggerChildren`; durations 0.35–0.7s, ease `[0.22, 1, 0.36, 1]` or springs |
-| **B — Scroll** | Sections **ease up / fade** on first viewport entry; grids **stagger cards** | `whileInView` + `viewport.once`; `margin: "-80px"` tweak so reveals feel early |
-| **C — Looping ambient** | Logo strip marquee; gradient drift; subtle SVG stroke dashoffset loop; “thinking…” **typing caret** | CSS `@keyframes` or Framer `animate` repeat; keep amplitude **low** |
-| **D — Interaction** | Buttons scale/shine on hover; cards **lift** (`translateY`, shadow); nav **backdrop blur / height** past threshold | `whileHover`, `whileTap`; scroll listener or Framer scroll hooks for nav |
-| **E — Decorative depth** | Pointer parallax on hero cluster (2–4 layers at different strengths) OR scroll-linked `useTransform` | Small rotate/translate ranges (≤ 8px / ≤ 2deg) |
-
-Always gate looping motion: **`useReducedMotion()`** from Framer Motion — swap loops for static frames and shorten entrances.
-
-### Brandability checklist *(distinctive, not generic SaaS gray)*
-
-- **Motif thread** — One recurring visual hook (pen stroke, folded page corner, hub spark, pixel creature) reused in hero, favicon, OG image sketch, and one feature illustration.
-- **Accent discipline** — Define **primary + secondary accent** in `:root` (even if mostly monochrome). Use accents on CTAs, SVG highlights, focus rings — not rainbow scatter.
-- **Wordmark lockup** — SVG glyph + tracked type; provide **icon-only** variant for favicon / meta.
-- **OG & SEO assets** — Generate **`public/seo/og.png`** (or route og image) that includes motif + product name — not a bare screenshot.
-
-### Where artifacts live
-
-- **Raster/video** — `public/images/`, `public/videos/` (see `MEDIA_MANIFEST.md`).
-- **SVG React illustrations** — Prefer `src/components/marketing/art/` or co-located `*-scene.tsx` modules; export named components (`HeroBackdrop`, `FeatureCaptureIllustration`).
-- **Pixel art** — Same folder pattern; document palette in file header comment.
-
-### Spec requirement *(hand-off quality)*
-
-When writing `docs/research/components/*.spec.md`, add sections **Illustration** (**Idea tie-in** per asset, layers, SVG components, raster paths) and expand **Motion** with tier **A–E** coverage and reduced-motion fallback. Builders should not invent motion ad hoc — the spec states durations and triggers.
-
-## Commands
-- `npm run dev` — Start dev server
-- `npm run build` — Production build
-- `npm run lint` — ESLint check
-- `npm run typecheck` — TypeScript check
-- `npm run check` — Run lint + typecheck + build
-- **`npm run recon`** — **Playwright** capture: full-page screenshots, `computed-snapshot.json`, `MEDIA_MANIFEST.md` (use when Browser MCP / Chrome DevTools MCP is broken or missing)
-- **`npm run recon:headed`** — Same as `recon` but **headed** Chromium (often better for WAF / “Just a moment…” pages)
-
-**Playwright browser binaries (once per machine):** `npx playwright install chromium`
-
-## When Browser MCP is down
-Prefer **Playwright** for repeatable extraction in-repo — do **not** rely on Chrome DevTools MCP alone.
-
-1. Run **`npm run recon`** (or **`npm run recon:headed`** if headless hits a challenge page).
-2. Read **`docs/research/computed-snapshot.json`**, **`docs/research/MEDIA_MANIFEST.md`**, and **`docs/research/EXTRACTION_LIMITATIONS.md`** before writing specs.
-3. Fill **`scripts/download-assets.mjs`** from `MEDIA_MANIFEST.md` and run it to populate `public/images/` and `public/videos/`.
-
-## Code Style
-- TypeScript strict mode, no `any`
-- Named exports, PascalCase components, camelCase utils
-- Tailwind utility classes, no inline styles
-- 2-space indentation
-- Responsive: mobile-first
-
-## Design Principles
-- **Images & video fidelity** — prefer real downloaded assets; preserve aspect ratio, `object-fit`, layering, and poster frames. Rebrand pass may **swap** URLs for IP-safe alternates but must keep layout identical.
-- **Motion fidelity** — timing and easing matter as much as color; use Framer Motion when CSS alone cannot match staggered or scroll-driven behavior.
-- **Idea-specific imagery** — Marketing art (SVG, raster, OG) must be **tailored to `launchframe.config.json#idea`**: explicit metaphors, per-asset **Idea tie-in** notes, and **no interchangeable filler** that could belong to any generic SaaS.
-- **Production landing density** — For authored/minimal pages, deliberately add **idea-specific** illustration (not generic SaaS filler), **pixel-art accents** when they reinforce the metaphor, and **tiered motion (A–E)** per “Production polish” above; static monochrome layouts are incomplete unless the user explicitly wants extreme minimalism.
-- **Pixel-perfect emulation** — match the target's spacing, colors, typography exactly
-- **No personal aesthetic changes during emulation phase** — match 1:1 first, rebrand later
-- **Real content during extraction** — use actual text and assets from the target site so the clone scaffolds against real shapes
-- **Rebrand pass swaps copy, not visuals** — once the clone is built, replace product name, headlines, feature copy, and brand marks with content tuned to `launchframe.config.json#idea`. Do NOT alter spacing, color tokens, typography scale, animations, or responsive breakpoints during the rebrand.
-- **Beauty-first** — every pixel matters
-
-## Project Structure
-```
-src/
-  app/              # Next.js routes
-  components/       # React components
-    ui/             # shadcn/ui primitives
-    marketing/      # Landing sections + authored SVG scenes (`art/` recommended)
-    icons.tsx       # Extracted SVG icons as React components
-  lib/
-    utils.ts        # cn() utility (shadcn)
-  types/            # TypeScript interfaces
-  hooks/            # Custom React hooks
-public/
-  images/           # Downloaded images from target site
-  videos/           # Downloaded videos from target site
-  seo/              # Favicons, OG images, webmanifest
-docs/
-  research/         # Inspection output (design tokens, components, layout)
-  design-references/ # Screenshots and visual references
-scripts/            # Asset download scripts
-```
-
-## MOST IMPORTANT NOTES
-- **Always start by reading `launchframe.config.json`** — that file dictates the URL to clone and the SaaS idea to re-skin for.
-- When launching Claude Code agent teams, ALWAYS have each teammate work in their own worktree branch and merge everyone's work at the end, resolving any merge conflicts smartly since you are basically serving the orchestrator role and have full context to our goals, work given, work achieved, and desired outcomes.
-- After editing `AGENTS.md`, run `bash scripts/sync-agent-rules.sh` to regenerate platform-specific instruction files.
-- After editing `.claude/skills/clone-website/SKILL.md`, run `node scripts/sync-skills.mjs` to regenerate the skill for all platforms.
-
-# Website Inspection Guide
-
-## Priority (read first): media & motion
-
-Launchframe clones live pages for a **visual** result. Two things most often separate a convincing build from a hollow one:
-
-### 1. Images & video (do this before obsessing over utility classes)
-
-- [ ] **Every `<img>`** — `src` / `srcset` / `currentSrc`, `sizes`, `loading`, `decoding`, `alt`, intrinsic dimensions
-- [ ] **`<picture>` / `<source>`** — resolution switches, art direction, `type` (WebP/AVIF)
-- [ ] **Every `<video>`** — `src` + nested `<source>`, **poster**, `autoplay`, `loop`, `muted`, `playsinline`, `controls`
-- [ ] **Background images** — `background-image` on ancestors (hero stacks are often **layers** of img + gradient + PNG mockup)
-- [ ] **Lazy / below-fold** — scroll the page once before asset discovery so `data-src` / lazy-loaded URLs resolve if the site uses them
-- [ ] **Download** — mirror into `public/images/` and `public/videos/` with stable paths; list failures in `docs/research/EXTRACTION_LIMITATIONS.md`
-
-If automation hits a bot wall, **do not pretend extraction succeeded** — capture what you can from successful fetches and document gaps.
-
-### 2. Motion (prefer Framer Motion in this repo)
-
-- [ ] **Entrance** — fade/slide/scale on mount or on **scroll into view** (note threshold / `margin`)
-- [ ] **Stagger** — children animating in sequence (hero bullets, card grids)
-- [ ] **Scroll-linked** — progress, parallax, pinned sections (may combine with CSS `animation-timeline` or libs)
-- [ ] **Gestures** — drag, pan, hover follow (often Framer Motion)
-- [ ] **Implementation rule** — use **`framer-motion`** for anything beyond trivial single-property CSS `transition`. Record **duration, easing, delay, stagger**, and **trigger** (scroll, hover, tap) in specs.
-
-### 3. Idea-tailored illustration & motifs *(production landings)*
-
-When the reference page is **sparse** (mostly type + gray boxes) or after a **rebrand** the UI still reads generic, illustration is required — and it must be **unique to the SaaS idea** (`launchframe.config.json#idea`), not reusable wallpaper.
-
-- [ ] **Metaphor list** — 3–6 nouns/verbs derived from `idea`; every bespoke asset maps to ≥ one entry
-- [ ] **Uniqueness check** — If the scene works unchanged for another product category, revise
-- [ ] **Inline SVG** — hero shapes, dividers, card mini-scenes; note `viewBox`, **`currentColor`** vs fixed fills, **Idea tie-in** sentence per asset
-- [ ] **Pixel art / sprites** — only when character reinforces the metaphor; palette hex table; `imageRendering` / grid discipline
-- [ ] **Motif thread** — recurring element echoing hero + OG + favicon **for this product**, not a random geometric pattern
-- [ ] **Accent tokens** — primary/secondary roles aligned with idea personality (extract from reference or define in `:root`)
-- [ ] **Motion tiers A–E** — document with **reduced-motion** fallback (`prefers-reduced-motion`)
-
-See **`AGENTS.md` → Production polish for marketing landings** for tier definitions and folders (`src/components/marketing/art/`, `public/images/marketing/`).
-
----
-
-## How to Reverse-Engineer Any Website
-
-This guide outlines what to capture when inspecting a target website via Chrome MCP or browser DevTools.
-
-## Phase 1: Visual Audit
-
-### Screenshots to Capture
-- [ ] Every distinct page — desktop, tablet, mobile
-- [ ] Dark mode variants (if applicable)
-- [ ] Light mode variants (if applicable)
-- [ ] Key interaction states (hover, active, open menus, modals)
-- [ ] Loading/skeleton states
-- [ ] Empty states
-- [ ] Error states
-- [ ] **Video frames** — capture a frame mid-play for reference if motion is subtle
-- [ ] **Hero / full-bleed** — wide crops where raster layers are easy to miss
-
-### Design Tokens to Extract
-- [ ] **Colors** — background, text (primary/secondary/muted), accent, border, hover, error, success, warning
-- [ ] **Typography** — font family, sizes (h1-h6, body, caption, label), weights, line heights, letter spacing
-- [ ] **Spacing** — padding/margin patterns (look for a scale: 4px, 8px, 12px, 16px, 24px, 32px, etc.)
-- [ ] **Border radius** — buttons, cards, avatars, inputs
-- [ ] **Shadows/elevation** — card shadows, dropdown shadows, modal overlay
-- [ ] **Breakpoints** — when does the layout shift? (inspect with DevTools responsive mode)
-- [ ] **Icons** — which icon library? custom SVGs? sizes?
-- [ ] **Avatars** — sizes, shapes, fallback behavior
-- [ ] **Buttons** — all variants (primary, secondary, ghost, icon-only, danger)
-- [ ] **Inputs** — text fields, textareas, selects, checkboxes, toggles
-
-## Phase 2: Component Inventory
-
-For each distinct UI component, document:
-1. **Name** — what would you call this component?
-2. **Structure** — what HTML elements / child components does it contain?
-3. **Variants** — does it have different sizes, colors, or states?
-4. **States** — default, hover, active, disabled, loading, error, empty
-5. **Responsive behavior** — how does it change at different breakpoints?
-6. **Interactions** — click, hover, focus, keyboard navigation
-7. **Animations** — transitions, entrance/exit, micro-interactions — **`framer-motion` vs CSS** and exact timing
-
-### Common Components to Look For
-- Navigation (top bar, sidebar, bottom bar)
-- Cards / list items
-- Buttons and links
-- Forms and inputs
-- Modals and dialogs
-- Dropdowns and menus
-- Tabs and segmented controls
-- Avatars and user badges
-- Loading skeletons
-- Toast notifications
-- Tooltips and popovers
-- **Video / Lottie / canvas** blocks (do not substitute with static mockups without documenting why)
-
-## Phase 3: Layout Architecture
-
-- [ ] **Grid system** — CSS Grid? Flexbox? Fixed widths?
-- [ ] **Column layout** — how many columns at each breakpoint?
-- [ ] **Max-width** — main content area max-width
-- [ ] **Sticky elements** — header, sidebar, floating buttons
-- [ ] **Z-index layers** — navigation, modals, tooltips, overlays
-- [ ] **Scroll behavior** — infinite scroll, pagination, virtual scrolling
-
-## Phase 4: Technical Stack Analysis
-
-- [ ] **Framework** — React? Vue? Angular? Check `__NEXT_DATA__`, `__NUXT__`, `ng-version`
-- [ ] **CSS approach** — Tailwind (utility classes), CSS Modules, Styled Components, Emotion, vanilla CSS
-- [ ] **State management** — Redux (check DevTools), React Query, Zustand, Pinia
-- [ ] **API patterns** — REST, GraphQL (check network tab for `/graphql` requests)
-- [ ] **Font loading** — Google Fonts, self-hosted, system fonts
-- [ ] **Image strategy** — CDN, lazy loading, srcset, WebP/AVIF — **mirror URLs you are allowed to fetch**
-- [ ] **Animation library** — site may use GSAP, Lottie, Rive, or CSS only — **in the Next.js clone, default to Framer Motion** unless a different lib is required for parity
-
-## Phase 5: Documentation Output
-
-After inspection, create these files in `docs/research/`:
-1. `DESIGN_TOKENS.md` — All extracted colors, typography, spacing
-2. `COMPONENT_INVENTORY.md` — Every component with structure notes
-3. **`MEDIA_MANIFEST.md`** — (recommended) Table of every image/video/poster URL → local `public/` path or “blocked”
-4. `LAYOUT_ARCHITECTURE.md` — Page layouts, grid system, responsive behavior
-5. `INTERACTION_PATTERNS.md` — Animations: **CSS vs Framer Motion**, transitions, hover states
-6. `TECH_STACK_ANALYSIS.md` — What the site uses and our chosen equivalents (Framer Motion for React animation)
+<!-- AUTO-GENERATED from AGENTS.md — do not edit directly.
+     Run `bash scripts/sync-agent-rules.sh` to regenerate. -->
+
+---
+description: Project conventions for AI Website Clone Template
+alwaysApply: true
+---
+<!-- BEGIN:nextjs-agent-rules -->
+# This is NOT the Next.js you know
+
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.
+<!-- END:nextjs-agent-rules -->
+
+# Website Reverse-Engineer Template
+
+## What This Is
+A reusable template for reverse-engineering any website into a clean, modern Next.js codebase using AI coding agents. The Next.js + shadcn/ui + Tailwind v4 base is pre-scaffolded — just run `/clone-website <url1> [<url2> ...]`.
+
+## Tech Stack
+- **Framework:** Next.js 16 (App Router, React 19, TypeScript strict)
+- **UI:** shadcn/ui (Radix primitives, Tailwind CSS v4, `cn()` utility)
+- **Icons:** Lucide React (default — will be replaced/supplemented by extracted SVGs)
+- **Styling:** Tailwind CSS v4 with oklch design tokens
+- **Deployment:** Vercel
+
+## Commands
+- `npm run dev` — Start dev server
+- `npm run build` — Production build
+- `npm run lint` — ESLint check
+- `npm run typecheck` — TypeScript check
+- `npm run check` — Run lint + typecheck + build
+
+## Code Style
+- TypeScript strict mode, no `any`
+- Named exports, PascalCase components, camelCase utils
+- Tailwind utility classes, no inline styles
+- 2-space indentation
+- Responsive: mobile-first
+
+## Design Principles
+- **Pixel-perfect emulation** — match the target's spacing, colors, typography exactly
+- **No personal aesthetic changes during emulation phase** — match 1:1 first, customize later
+- **Real content** — use actual text and assets from the target site, not placeholders
+- **Beauty-first** — every pixel matters
+
+## Project Structure
+```
+src/
+  app/              # Next.js routes
+  components/       # React components
+    ui/             # shadcn/ui primitives
+    icons.tsx       # Extracted SVG icons as React components
+  lib/
+    utils.ts        # cn() utility (shadcn)
+  types/            # TypeScript interfaces
+  hooks/            # Custom React hooks
+public/
+  images/           # Downloaded images from target site
+  videos/           # Downloaded videos from target site
+  seo/              # Favicons, OG images, webmanifest
+docs/
+  research/         # Inspection output (design tokens, components, layout)
+  design-references/ # Screenshots and visual references
+scripts/            # Asset download scripts
+```
+
+## MOST IMPORTANT NOTES
+- When launching Claude Code agent teams, ALWAYS have each teammate work in their own worktree branch and merge everyone's work at the end, resolving any merge conflicts smartly since you are basically serving the orchestrator role and have full context to our goals, work given, work achieved, and desired outcomes.
+- After editing `AGENTS.md`, run `bash scripts/sync-agent-rules.sh` to regenerate platform-specific instruction files.
+- After editing `.claude/skills/clone-website/SKILL.md`, run `node scripts/sync-skills.mjs` to regenerate the skill for all platforms.
+
+# Website Inspection Guide
+
+## How to Reverse-Engineer Any Website
+
+This guide outlines what to capture when inspecting a target website via Chrome MCP or browser DevTools.
+
+## Phase 1: Visual Audit
+
+### Screenshots to Capture
+- [ ] Every distinct page — desktop, tablet, mobile
+- [ ] Dark mode variants (if applicable)
+- [ ] Light mode variants (if applicable)
+- [ ] Key interaction states (hover, active, open menus, modals)
+- [ ] Loading/skeleton states
+- [ ] Empty states
+- [ ] Error states
+
+### Design Tokens to Extract
+- [ ] **Colors** — background, text (primary/secondary/muted), accent, border, hover, error, success, warning
+- [ ] **Typography** — font family, sizes (h1-h6, body, caption, label), weights, line heights, letter spacing
+- [ ] **Spacing** — padding/margin patterns (look for a scale: 4px, 8px, 12px, 16px, 24px, 32px, etc.)
+- [ ] **Border radius** — buttons, cards, avatars, inputs
+- [ ] **Shadows/elevation** — card shadows, dropdown shadows, modal overlay
+- [ ] **Breakpoints** — when does the layout shift? (inspect with DevTools responsive mode)
+- [ ] **Icons** — which icon library? custom SVGs? sizes?
+- [ ] **Avatars** — sizes, shapes, fallback behavior
+- [ ] **Buttons** — all variants (primary, secondary, ghost, icon-only, danger)
+- [ ] **Inputs** — text fields, textareas, selects, checkboxes, toggles
+
+## Phase 2: Component Inventory
+
+For each distinct UI component, document:
+1. **Name** — what would you call this component?
+2. **Structure** — what HTML elements / child components does it contain?
+3. **Variants** — does it have different sizes, colors, or states?
+4. **States** — default, hover, active, disabled, loading, error, empty
+5. **Responsive behavior** — how does it change at different breakpoints?
+6. **Interactions** — click, hover, focus, keyboard navigation
+7. **Animations** — transitions, entrance/exit animations, micro-interactions
+
+### Common Components to Look For
+- Navigation (top bar, sidebar, bottom bar)
+- Cards / list items
+- Buttons and links
+- Forms and inputs
+- Modals and dialogs
+- Dropdowns and menus
+- Tabs and segmented controls
+- Avatars and user badges
+- Loading skeletons
+- Toast notifications
+- Tooltips and popovers
+
+## Phase 3: Layout Architecture
+
+- [ ] **Grid system** — CSS Grid? Flexbox? Fixed widths?
+- [ ] **Column layout** — how many columns at each breakpoint?
+- [ ] **Max-width** — main content area max-width
+- [ ] **Sticky elements** — header, sidebar, floating buttons
+- [ ] **Z-index layers** — navigation, modals, tooltips, overlays
+- [ ] **Scroll behavior** — infinite scroll, pagination, virtual scrolling
+
+## Phase 4: Technical Stack Analysis
+
+- [ ] **Framework** — React? Vue? Angular? Check `__NEXT_DATA__`, `__NUXT__`, `ng-version`
+- [ ] **CSS approach** — Tailwind (utility classes), CSS Modules, Styled Components, Emotion, vanilla CSS
+- [ ] **State management** — Redux (check DevTools), React Query, Zustand, Pinia
+- [ ] **API patterns** — REST, GraphQL (check network tab for `/graphql` requests)
+- [ ] **Font loading** — Google Fonts, self-hosted, system fonts
+- [ ] **Image strategy** — CDN, lazy loading, srcset, WebP/AVIF
+- [ ] **Animation library** — Framer Motion, GSAP, CSS transitions only
+
+## Phase 5: Documentation Output
+
+After inspection, create these files in `docs/research/`:
+1. `DESIGN_TOKENS.md` — All extracted colors, typography, spacing
+2. `COMPONENT_INVENTORY.md` — Every component with structure notes
+3. `LAYOUT_ARCHITECTURE.md` — Page layouts, grid system, responsive behavior
+4. `INTERACTION_PATTERNS.md` — Animations, transitions, hover states
+5. `TECH_STACK_ANALYSIS.md` — What the site uses and our chosen equivalents