@kennethsolomon/shipkit 3.2.0 → 3.3.0

package/README.md

@@ -102,7 +102,7 @@ Brainstorm → Plan → Branch → [Schema] → Write Tests → Implement → Co
 | 19 | `/sk:smart-commit` | Auto-skip if already clean |
 | 20 | **`/sk:review`** | **GATE** — Review + Simplify — 0 issues including nitpicks |
 | 21 | `/sk:smart-commit` | Auto-skip if already clean |
-| 22 | **`/sk:e2e`** | **GATE** — E2E Tests — all end-to-end tests must pass |
+| 22 | **`/sk:e2e`** | **GATE** — E2E Tests — prefers Playwright CLI when config detected, falls back to agent-browser; all scenarios must pass |
 | 23 | `/sk:smart-commit` | Auto-skip if already clean |
 | 24 | `/sk:update-task` | Mark done, log completion |
 | 25 | `/sk:finish-feature` | Changelog + PR |
@@ -196,6 +196,12 @@ Requirement changes → /sk:change → re-enter at correct step
 | `/sk:debug` | Structured bug investigation: reproduce → isolate → fix |
 | `/sk:hotfix` | Emergency fix workflow — skips design and TDD |
 
+### Prototyping
+
+| Command | Description |
+|---------|-------------|
+| `/sk:mvp` | Generate a complete MVP from a single idea prompt — landing page with waitlist + working app with fake data. Supports Next.js, Nuxt, Laravel, React+Vite. Optional Pencil MCP design phase and Playwright MCP visual validation. |
+
 ### Quality Gates
 
 | Command | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kennethsolomon/shipkit",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "A structured workflow toolkit for Claude Code.",
   "keywords": [
     "claude",

package/skills/sk:e2e/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sk:e2e
-description: "Run E2E behavioral verification using agent-browser as the final quality gate before finalize. Tests the complete, reviewed, secure implementation from a user's perspective."
+description: "Run E2E behavioral verification as the final quality gate before finalize. Prefers Playwright CLI when playwright.config.ts is detected; falls back to agent-browser otherwise. Tests the complete, reviewed, secure implementation from a user's perspective."
 ---
 
 # /sk:e2e
@@ -22,22 +22,97 @@ Read these files to understand what to test:
 - `tasks/findings.md` — design decisions and expected behaviors
 - `tasks/progress.md` — implementation notes
 
-### 2. Check agent-browser is Available
+### 2. Detect E2E Runner
+
+Check which runner is available, in priority order:
+
+**Priority 1 — Playwright (preferred)**
+
+```bash
+ls playwright.config.ts 2>/dev/null || ls playwright.config.js 2>/dev/null
+```
+
+If a Playwright config exists → use Playwright CLI (Step 3a). This is the preferred path because:
+- Uses headless Chromium (no conflict with system Chrome)
+- No additional global install required (`@playwright/test` in devDeps)
+- Test files in `e2e/` or `tests/e2e/` are picked up automatically
+- `webServer` in `playwright.config.ts` auto-starts the dev server
+
+**Playwright config requirements** (verify before running):
+- `headless: true` must be set under `use:`
+- `channel: undefined` (or omitted) — must NOT be `'chrome'` or `'msedge'` to avoid system browser conflicts
+- `webServer.reuseExistingServer: true` — avoids double-starting the dev server
+
+If config has `channel: 'chrome'` or `headless: false`, warn:
+> "playwright.config.ts uses system Chrome or headed mode — this may conflict with a running browser. Consider setting `headless: true` and `channel: undefined`."
+
+**Priority 2 — agent-browser (fallback)**
 
 ```bash
 agent-browser --version
 ```
 
-If not found, instruct the user:
+Only use `agent-browser` if NO `playwright.config.ts` / `playwright.config.js` exists.
+
+If `agent-browser` is also not found, AND no Playwright config exists:
+
 ```
-agent-browser is required. Install it:
+Neither Playwright nor agent-browser is configured. To fix permanently:
+
+Option A (recommended) — Playwright:
+  npm install -D @playwright/test
+  npx playwright install chromium
+  # Create playwright.config.ts with headless: true, channel: undefined
+
+Option B — agent-browser:
   npm install -g agent-browser
-  agent-browser install   # downloads Chrome (~100MB)
+  agent-browser install
+
 Then re-run /sk:e2e.
 ```
-Stop if not available.
+Stop if neither runner is available.
+
+### 3a. Run E2E via Playwright CLI
+
+Locate test files:
+```bash
+ls e2e/ 2>/dev/null
+ls tests/e2e/ 2>/dev/null
+find . -name "*.spec.ts" -not -path "*/node_modules/*"
+```
+
+If spec files exist, run them:
+```bash
+npx playwright test --reporter=list
+```
+
+To run a specific file:
+```bash
+npx playwright test e2e/my-feature.spec.ts --reporter=list
+```
+
+To run with visible output on failure:
+```bash
+npx playwright test --reporter=list 2>&1
+```
+
+**Interpreting results:**
+- Exit code 0 = all tests passed
+- Exit code 1 = one or more tests failed (output includes which tests and why)
+- Each failing test shows: test name, expected vs. actual, screenshot path (if `trace: 'on-first-retry'` is set)
+
+If no spec files exist → derive scenarios from `tasks/todo.md` acceptance criteria and write them to `e2e/<feature>.spec.ts` before running. Follow the test file patterns already present in the project (check `e2e/helpers/` for shared utilities).
 
-### 3. Detect Local Server
+After running, record for each test:
+- Test name / suite
+- Result: PASS or FAIL
+- On FAIL: error message and relevant snapshot
+
+Skip to **Step 5 (Report Results)**.
+
+### 3b. Detect Local Server (agent-browser path only)
+
+Only needed if using agent-browser (Playwright's `webServer` handles this automatically).
 
 Determine what URL to test against:
 - Check for a dev server command in `package.json` scripts (`dev`, `start`)
@@ -46,7 +121,7 @@ Determine what URL to test against:
 - If a server is already running (check common ports: 3000, 5173, 8000, 8080), use it
 - If no server is running, start one in the background and note the URL
 
-### 4. Locate E2E Test Files
+### 4. Locate E2E Test Files (agent-browser path only)
 
 Find E2E test scenarios written during the Write Tests step:
 ```bash
@@ -56,7 +131,7 @@ ls tests/e2e/ 2>/dev/null
 
 If no E2E test files exist, derive scenarios from `tasks/todo.md` acceptance criteria and `tasks/findings.md`.
 
-### 5. Run E2E Scenarios
+### 4b. Run E2E Scenarios via agent-browser
 
 For each scenario, use agent-browser following this core pattern:
 
@@ -90,9 +165,10 @@ For each scenario, record:
 - Result: PASS or FAIL
 - On FAIL: what was expected vs. what was found (include snapshot excerpt)
 
-### 6. Report Results
+### 5. Report Results
 
 ```
+E2E Runner: Playwright CLI  (or: agent-browser)
 E2E Results:
   PASS  [scenario name]
   PASS  [scenario name]
@@ -130,6 +206,81 @@ If failures remain after fixes:
 
 ---
 
+## Playwright Setup Reference
+
+When setting up Playwright for the first time in a project:
+
+```bash
+npm install -D @playwright/test
+npx playwright install chromium
+```
+
+Minimal `playwright.config.ts` (headless, no system Chrome conflict):
+
+```ts
+import { defineConfig, devices } from '@playwright/test'
+
+export default defineConfig({
+  testDir: './e2e',
+  fullyParallel: true,
+  retries: process.env.CI ? 2 : 0,
+  reporter: 'list',
+  use: {
+    baseURL: process.env.PLAYWRIGHT_BASE_URL ?? 'http://localhost:3000',
+    headless: true,          // REQUIRED — avoids system Chrome conflict
+    trace: 'on-first-retry',
+  },
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'], channel: undefined }, // REQUIRED — use Playwright's Chromium, not system Chrome
+    },
+  ],
+  webServer: {
+    command: 'npm run dev',  // or 'php artisan serve', 'yarn dev', etc.
+    url: 'http://localhost:3000',
+    reuseExistingServer: true,
+    timeout: 120_000,
+  },
+})
+```
+
+E2E test helpers go in `e2e/helpers/`. Auth helper pattern:
+
+```ts
+// e2e/helpers/auth.ts
+import { Page } from '@playwright/test'
+
+export async function signIn(page: Page, email: string, password: string) {
+  await page.goto('/login')
+  await page.getByLabel(/email/i).fill(email)
+  await page.getByLabel(/password/i).fill(password)
+  await page.getByRole('button', { name: /sign in|log in/i }).click()
+  await page.waitForURL('/dashboard', { timeout: 15_000 })
+}
+
+export const TEST_USERS = {
+  regular: {
+    email: process.env.E2E_USER_EMAIL ?? '',
+    password: process.env.E2E_USER_PASSWORD ?? '',
+  },
+  admin: {
+    email: process.env.E2E_ADMIN_EMAIL ?? '',
+    password: process.env.E2E_ADMIN_PASSWORD ?? '',
+  },
+}
+```
+
+Test credentials go in `.env.local` (never hardcoded):
+```
+E2E_USER_EMAIL=...
+E2E_USER_PASSWORD=...
+E2E_ADMIN_EMAIL=...
+E2E_ADMIN_PASSWORD=...
+```
+
+---
+
 ## Model Routing
 
 Read `.shipkit/config.json` from the project root if it exists.

package/skills/sk:mvp/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: sk:mvp
+description: Generate a complete MVP validation app from a prompt — landing page with waitlist + working app with fake data. Use this skill when the user wants to quickly validate a product idea, build a proof of concept, create a landing page with email collection, scaffold an MVP, build a prototype for market validation, or test if an idea is worth pursuing. Produces a full working codebase locally.
+compatibility: Optional — Pencil MCP (for visual mockups), Playwright MCP (for visual validation)
+---
+
+# /sk:mvp — MVP Validation App Generator
+
+Generate a complete, aesthetically polished MVP from a single idea prompt. Outputs a landing page with waitlist email collection + a working app with fake data. Purpose: validate market interest before investing in a full build.
+
+## Hard Rules
+
+- Generate ALL code locally — never deploy, push, or publish anything.
+- Landing page is MANDATORY for every MVP. Never skip it.
+- Use FAKE data only — no real databases, no auth systems, no third-party API integrations.
+- Every page must be functional: buttons navigate, forms submit, modals open/close.
+- Design must be distinctive and polished — never use default Tailwind colors or generic layouts. Read `references/design-system.md` for aesthetic guidelines.
+- Keep the app secure enough (no XSS, no open redirects) but don't over-engineer security for a prototype.
+
+---
+
+## Step 1 — Gather the Idea
+
+Ask the user to describe their product idea. If not already provided, ask:
+
+> **What's your product idea? Describe it in 1-3 sentences — what does it do and who is it for?**
+
+Extract from their answer:
+- **Product name** (or ask them to pick one)
+- **One-line value proposition**
+- **Target audience**
+- **Key features** (3-5 core features for the app)
+
+Confirm your understanding before proceeding.
+
+---
+
+## Step 2 — Pick a Tech Stack
+
+Present these preset options:
+
+> **Pick a tech stack:**
+>
+> 1. **Next.js + Tailwind** — React ecosystem, SSR, API routes built-in
+> 2. **Nuxt + Tailwind** — Vue ecosystem, SSR, server routes built-in
+> 3. **Laravel + Blade + Tailwind** — PHP ecosystem, full backend, Blade templates
+> 4. **React + Vite + Tailwind** — Lightweight SPA, no backend (waitlist via Formspree)
+>
+> Or type your own stack (I'll adapt).
+
+Once the user picks, note the selection and load the corresponding reference file in Step 6.
+
+---
+
+## Step 3 — Optional Design Phase (Pencil MCP)
+
+Check if the user invoked with `--pencil` flag or ask:
+
+> **Would you like to design the UI visually in Pencil before coding? (Requires Pencil app + MCP) (y/n)**
+>
+> If no, I'll go straight to code generation with a great default design.
+
+### If YES — Pencil MCP Design Phase
+
+Follow this flow (adapted from sk:frontend-design):
+
+**3a. Find or create .pen file**
+- Check `docs/design/` for existing `.pen` file matching this MVP.
+- Existing: `open_document(filePath)` → skip to 3c.
+- None: `open_document('new')` → save to `docs/design/{product-slug}.pen`.
+
+**3b. Load design context**
+1. `get_guidelines(topic='landing-page')` — load landing page design rules.
+2. `get_style_guide_tags` → `get_style_guide(tags)` — pick tags matching the product's tone (e.g., modern, SaaS, minimal, bold).
+
+**3c. Set color palette as variables**
+Decide a distinctive color palette based on the product's tone and audience. Call `set_variables` with the palette:
+```json
+{
+  "color-bg": "#xxxxxx",
+  "color-fg": "#xxxxxx",
+  "color-accent": "#xxxxxx",
+  "color-muted": "#xxxxxx"
+}
+```
+
+**3d. Build mockup screens**
+Use `batch_design` to create:
+1. Landing page frame — hero, features, pricing, waitlist section
+2. App main screen frame — dashboard or primary view
+3. App secondary screen frame — detail view or key interaction
+
+Work one frame per `batch_design` call. Apply the color variables and typography.
+
+**3e. Validate and iterate**
+After each frame: `get_screenshot` to inspect. If off: `snapshot_layout` → fix with `batch_design`. Iterate until the design matches the vision.
+
+**3f. Get user approval**
+Present screenshots and ask:
+> **Does this design direction look good? Any changes before I start coding?**
+
+Wait for approval. Apply feedback if given. Do not proceed to code without explicit approval.
+
+**3g. Record the design**
+Note the `.pen` file path. The design decisions (colors, typography, layout) carry forward into code generation.
+
+### If NO — Skip to Step 4
+
+Use the aesthetic guidelines from `references/design-system.md` to make distinctive design choices automatically. Briefly state the design direction chosen (color scheme, typography, layout style) so the user knows what to expect.
+
+---
+
+## Step 4 — Scaffold the Project
+
+Read the stack-specific reference file:
+- Next.js → `references/stacks/nextjs.md`
+- Nuxt → `references/stacks/nuxt.md`
+- Laravel → `references/stacks/laravel.md`
+- React + Vite → `references/stacks/react-vite.md`
+
+Run the scaffold command from the reference file. Then customize the Tailwind config with the chosen color palette and typography.
+
+---
+
+## Step 5 — Generate the Landing Page
+
+Read `references/landing-page.md` for section patterns and structure.
+
+Generate a complete landing page with these sections (all mandatory):
+
+1. **Navbar** — logo/product name + nav links (Features, Pricing, Waitlist) + CTA button
+2. **Hero** — headline (benefit-driven) + subheadline + primary CTA + hero visual/illustration area
+3. **Social proof bar** — "Trusted by X+" or logo strip (use placeholder logos)
+4. **Features grid** — 3-6 feature cards with icons, titles, descriptions (based on the key features from Step 1)
+5. **How it works** — 3-step process with numbered steps and descriptions
+6. **Pricing** — 2-3 tier cards (Free / Pro / Enterprise) with fake but realistic pricing
+7. **Testimonials** — 2-3 fake testimonial cards with names, roles, photos (use placeholder avatars)
+8. **Waitlist / CTA section** — email input + submit button + success message + form validation
+9. **Footer** — product name, links, copyright
+
+### Waitlist Email Collection
+
+**For stacks with backend (Next.js, Nuxt, Laravel):**
+- Create an API route that accepts POST `{ email }`.
+- Validate the email format server-side.
+- Read existing `waitlist.json`, append the new entry with timestamp, write back.
+- Return success/error JSON response.
+- Wire the landing page form to POST to this route via fetch.
+- Show success state ("You're on the list!") and error state on the form.
+
+**For static stacks (React + Vite):**
+- Use Formspree: form action points to `https://formspree.io/f/{form_id}`.
+- Add a comment/note telling the user to create a free Formspree account and replace `{form_id}`.
+- Handle success/error states client-side.
+
+---
+
+## Step 6 — Generate the App
+
+Generate a working multi-page app with:
+
+1. **Navigation** — sidebar or top nav with links to all pages. Active state highlighting.
+2. **Dashboard / Home** — summary cards, charts (use simple CSS/SVG charts or placeholder), recent activity list. All fake data.
+3. **Primary feature page** — the main thing the product does. Functional UI with fake data. Buttons, modals, forms all work (client-side only).
+4. **Secondary feature page** — a supporting feature. Table or list view with filtering/sorting (client-side).
+5. **Settings / Profile page** — simple form with fake prefilled data. Save button shows a toast/notification.
+
+### Design Standards (apply to every page)
+
+Read `references/design-system.md` and apply:
+- Distinctive color palette — never default Tailwind. Custom `tailwind.config` colors.
+- Thoughtful typography — use Google Fonts. Pair a display font with a body font.
+- Consistent spacing scale — use a rhythm (e.g., 4/8/12/16/24/32/48).
+- Polished components — rounded corners, shadows, hover states, transitions.
+- Responsive — must look good on mobile and desktop.
+- Fake data should feel realistic — use real-sounding names, numbers, dates.
+
+---
+
+## Step 7 — Visual Validation (Playwright MCP)
+
+After code generation is complete, validate the output visually.
+
+**If Playwright MCP is available:**
+
+1. Start the dev server (use the stack's dev command from the reference file).
+2. Use Playwright MCP to navigate to each page:
+   - Landing page (`/`)
+   - Dashboard (`/dashboard`)
+   - Each app page
+3. Take screenshots of each page at desktop (1280px) and mobile (375px) widths.
+4. Check for:
+   - Broken layouts (overlapping elements, overflow, misaligned sections)
+   - Missing content (empty sections, broken images, placeholder text not filled)
+   - Non-functional interactions (click buttons, submit forms, open modals)
+   - Visual consistency (colors match palette, typography is consistent)
+5. If issues found: fix them and re-validate.
+
+**If Playwright MCP is NOT available:**
+
+Tell the user:
+> Playwright MCP is not connected — skipping visual validation. Start the dev server with `{dev command}` and check the pages manually.
+
+---
+
+## Step 8 — Quality Loop
+
+If visual validation found issues:
+
+1. Fix the identified issues.
+2. Re-run Playwright validation (Step 7).
+3. Repeat until all pages pass — no broken layouts, all interactions work, design is consistent.
+
+Maximum 3 loop iterations. If issues persist after 3 loops, present remaining issues to the user and ask how to proceed.
+
+---
+
+## Step 9 — Present the Output
+
+Summarize what was generated:
+
+```
+## MVP Generated
+
+**Product:** {name}
+**Stack:** {stack}
+**Files:** {count} files generated
+
+### Landing Page
+- URL: http://localhost:{port}/
+- Sections: hero, features, pricing, waitlist, testimonials
+- Waitlist: {API route path or Formspree}
+
+### App Pages
+- Dashboard: http://localhost:{port}/dashboard
+- {Feature 1}: http://localhost:{port}/{path}
+- {Feature 2}: http://localhost:{port}/{path}
+- Settings: http://localhost:{port}/settings
+
+### Start the dev server
+{exact command to run}
+
+### What's next
+- Review the generated code and tweak the design to your liking
+- Replace placeholder content with your real copy
+- Replace fake data with real API integrations when ready
+- Deploy when you're happy with it
+```
+
+---
+
+## Model Routing
+
+Read `.shipkit/config.json` from the project root if it exists.
+
+- If `model_overrides["sk:mvp"]` is set, use that model — it takes precedence.
+- Otherwise use the `profile` field. Default: `balanced`.
+
+| Profile | Model |
+|---------|-------|
+| `full-sail` | opus (inherit) |
+| `quality` | opus (inherit) |
+| `balanced` | sonnet |
+| `budget` | sonnet |
+
+> `opus` = inherit (uses the current session model). When spawning sub-agents via the Agent tool, pass `model: "<resolved-model>"`.

package/skills/sk:mvp/references/design-system.md

@@ -0,0 +1,136 @@
+# Design System — MVP Aesthetic Guidelines
+
+Guidelines for generating visually distinctive MVPs that don't look like generic AI output.
+
+---
+
+## Core Principle
+
+Every MVP must look **intentionally designed**, not template-generated. The goal is to make visitors think "this looks legit" — good enough to trust with their email and time.
+
+---
+
+## Typography
+
+### Rules
+- Always use **two fonts**: one display/heading font + one body font.
+- Source from Google Fonts. Never use system fonts, Inter, Roboto, or Arial as the primary choice.
+- Vary choices between projects — do not converge on the same fonts repeatedly.
+
+### Suggested Pairings (rotate, don't default to #1)
+1. **DM Serif Display** + **DM Sans** — editorial, trustworthy
+2. **Playfair Display** + **Source Sans 3** — luxury, refined
+3. **Space Grotesk** + **Inter** — tech, modern (use sparingly, very common)
+4. **Sora** + **Nunito Sans** — friendly, approachable SaaS
+5. **Clash Display** + **Satoshi** — bold, contemporary
+6. **Fraunces** + **Commissioner** — warm, distinctive
+7. **Cabinet Grotesk** + **General Sans** — clean, startup
+8. **Bricolage Grotesque** + **Geist** — editorial tech
+
+### Scale
+Use a consistent type scale. Recommended base: `16px`.
+
+| Element | Size | Weight | Tracking |
+|---------|------|--------|----------|
+| H1 (hero) | 48-72px | 700-800 | -0.02em |
+| H2 (section) | 32-40px | 600-700 | -0.01em |
+| H3 (card title) | 20-24px | 600 | normal |
+| Body | 16-18px | 400 | normal |
+| Small/caption | 13-14px | 400-500 | 0.01em |
+
+---
+
+## Color
+
+### Rules
+- Never use default Tailwind color names without customization (`blue-500`, `gray-100` raw).
+- Define a custom palette in `tailwind.config` under `extend.colors`.
+- Every palette needs: background, foreground, primary accent, secondary accent, muted, border, success, error.
+- Commit to a mood — don't mix warm and cool randomly.
+
+### Palette Strategies (pick one per project)
+1. **Dark + neon accent** — dark bg (#0a0a0a), light text (#fafafa), vibrant accent (#6366f1 or #22d3ee)
+2. **Warm neutral + earth accent** — warm white (#faf9f6), dark text (#1a1a1a), terracotta/amber accent
+3. **Cool minimal** — pure white (#ffffff), slate text (#334155), single accent color
+4. **Bold saturated** — deep colored bg (#1e1b4b), contrasting text, bright accent
+5. **Soft pastel** — light tinted bg (#f0fdf4), dark text, pastel accent palette
+
+### Contrast
+- Text on background must meet WCAG AA (4.5:1 for body text, 3:1 for large text).
+- Test accent colors against both light and dark surfaces.
+
+---
+
+## Spacing
+
+Use a **4px base unit** with a consistent scale:
+
+| Token | Value | Use for |
+|-------|-------|---------|
+| `xs` | 4px | Icon gaps, tight padding |
+| `sm` | 8px | Inline spacing, compact cards |
+| `md` | 16px | Default padding, form gaps |
+| `lg` | 24px | Card padding, section content |
+| `xl` | 32px | Section gaps |
+| `2xl` | 48px | Between major sections |
+| `3xl` | 64px | Hero padding, page-level spacing |
+| `4xl` | 96px | Landing page section separation |
+
+### Layout Rhythm
+- Sections on the landing page should have `py-20` to `py-28` (80-112px) vertical padding.
+- Cards should have consistent `p-6` to `p-8` padding.
+- The max content width should be `max-w-6xl` or `max-w-7xl`, centered.
+
+---
+
+## Components
+
+### Buttons
+- Primary: filled with accent color, white text, `rounded-lg` or `rounded-xl`, `px-6 py-3`.
+- Secondary: outlined or ghost, accent color border/text.
+- Hover: subtle scale (`hover:scale-105`) or color shift. Add `transition-all duration-200`.
+- Never use default browser button styles.
+
+### Cards
+- Background slightly offset from page bg (e.g., white card on gray bg, or lighter card on dark bg).
+- Consistent `rounded-xl` or `rounded-2xl`.
+- Subtle shadow: `shadow-sm` or `shadow-md`. On dark themes use border instead.
+- Hover state for interactive cards: lift (`hover:-translate-y-1 hover:shadow-lg`).
+
+### Forms / Inputs
+- Inputs: `rounded-lg`, visible border, generous padding (`px-4 py-3`).
+- Focus state: accent-colored ring (`focus:ring-2 focus:ring-accent`).
+- Labels above inputs, not floating.
+- Error states: red border + error message below.
+
+### Navigation
+- Sticky/fixed navbar with blur backdrop (`backdrop-blur-md bg-white/80`).
+- Logo/name on left, links center or right, CTA button far right.
+- Mobile: hamburger menu with slide-in drawer or dropdown.
+
+---
+
+## Anti-Patterns — NEVER Do These
+
+1. **Default Tailwind colors** — `bg-blue-500 text-gray-700` without custom palette
+2. **System fonts** — `-apple-system, BlinkMacSystemFont` or `font-sans` without override
+3. **Flat layouts** — sections that all look the same width/padding/structure
+4. **Missing hover states** — buttons/links that don't respond to hover
+5. **Placeholder.com images** — use gradient boxes, SVG illustrations, or emoji as placeholders instead
+6. **Lorem ipsum** — generate realistic fake content based on the product context
+7. **Inconsistent spacing** — mixing random padding/margin values
+8. **Tiny click targets** — buttons and links must be minimum 44x44px touch targets
+9. **No visual hierarchy** — everything same size/weight, no emphasis
+10. **Generic hero** — "Welcome to [Product]" with no visual interest
+
+---
+
+## Responsive Design
+
+- **Mobile-first** approach — design for 375px width, enhance for desktop.
+- Breakpoints: `sm` (640px), `md` (768px), `lg` (1024px), `xl` (1280px).
+- Hero text scales down: 48px desktop → 32px mobile.
+- Feature grids: 3 columns desktop → 1 column mobile.
+- Navigation: full links desktop → hamburger mobile.
+- Cards: horizontal layout desktop → stacked mobile.
+- Always test that nothing overflows horizontally on mobile.