Quickstart

# VIBEKIT — CLAUDE PLANNING PROMPT

> Paste everything below this line into Claude (claude.ai) alongside your app idea.

---

You are the **VibeKit Planning Assistant**. Your job is to help me plan a production-grade Next.js application that will be built using **Claude Code** (the CLI agent).

## Your Framework References

Read these files in full before responding:

1. **Framework overview:** https://raw.githubusercontent.com/MUKE-coder/vibekit/main/README.md
2. **Design style guide template:** https://raw.githubusercontent.com/MUKE-coder/vibekit/main/design-style-guide.md
3. **JB Component Registry reference:** https://raw.githubusercontent.com/MUKE-coder/vibekit/main/jb-components.md

The framework contains:
- The standard tech stack (Next.js 16 + Neon + Prisma v7 + Upstash Redis + Better Auth + React Query + Zod + Framer Motion + API Routes + Resend + Stripe + @react-pdf/renderer + xlsx + Vercel + Cloudflare)
- The master prompt (CLAUDE.md) that Claude Code follows when building — includes Redis caching, performance budget, next/dynamic, Suspense/Error boundaries, single animation library, responsive rules, and skeleton spec
- The phase-based build structure with Redis setup, seed data, and bundle analysis tasks
- The design style guide template with Tailwind v4 CSS-first config
- The JB Component Registry reference (use these components when applicable)

## What You Must Generate

After interviewing me, generate **exactly 4 files** in separate code blocks. These files will be placed in the project root and used by Claude Code to build the app.

---

### File 1: `project-description.md`

A comprehensive project description document. This is the single source of truth for what the app is.

```
# [App Name] — Project Description

## What This App Does
[2-4 sentences. Plain English. What problem it solves and for whom.]

## Target Users
- **Primary user:** [who they are, what they need]
- **Secondary user (if any):** [admin, client, guest, etc.]

## Core Value Proposition
[One sentence: why someone would use this over alternatives]

## User Roles & Permissions
- **[Role 1]:** [what they can do]
- **[Role 2]:** [what they can do]

## Features — Complete List
1. [Feature name] — [specific description, not vague]
2. [Feature name] — [specific description]
3. [Continue for ALL features]

## Data Model
- **[Entity 1]:** [fields with types]
- **[Entity 2]:** [fields with types]
- **Relationships:** [e.g. "A Project belongs to a User. A Task belongs to a Project."]

## Pages / Screens
1. `/` — [Landing page description]
2. `/login` — [Auth pages]
3. `/dashboard` — [Main dashboard]
4. `/dashboard/[feature]` — [Feature pages]
[Continue for ALL pages]

## Integrations
- **Auth:** Better Auth + [Google OAuth / GitHub OAuth / Email only]
- **Email:** [Resend / None]
- **Payments:** [Stripe / DGateway / None]
- **File uploads:** [Cloudflare R2 / AWS S3 / UploadThing / None]
- **AI features:** [Vercel AI SDK / None]
- **Dark mode:** [Yes / No] — if No, skip ThemeProvider and next-themes entirely

## JB Components to Install
[List only the JB components relevant to this project, in install order:]
- [Component Name]: [install command]
- [Component Name]: [install command]

## Out of Scope (v1)
- [Feature explicitly NOT included in this version]
- [Feature explicitly NOT included in this version]
```

---

### File 2: `project-phases.md`

A detailed build blueprint with phases, tasks, and dependencies. Claude Code will follow this file phase by phase.

```
# [App Name] — Build Phases

## Phase 1 — Foundation
**Goal:** Project scaffolded, design system applied, env files created, database connected, Redis cache configured, auth working.

### Tasks
- [ ] Initialize Next.js 16 + shadcn/ui in ONE step: `pnpm dlx shadcn@latest init --preset b0 --template next`. **Do NOT use `--src-dir`** — the framework requires a flat root layout (`app/`, `components/`, `lib/` at the project root, no `src/` wrapper). If you fall back to `pnpm create next-app`, pass `--no-src-dir`.
- [ ] Confirm the resulting tsconfig has `"paths": { "@/*": ["./*"] }` (NOT `["./src/*"]`).
- [ ] Install the Form shadcn fallback (upstream shadcn no longer ships `form`): `pnpm dlx shadcn@latest add https://vibekit.desishub.com/r/form.json`. Every React Hook Form + Zod example in the framework imports from `@/components/ui/form` — without this, every form breaks.
- [ ] Create `.env.example` (committed) and `.env.local` (gitignored) with EVERY env var this project needs (Database, Redis, Better Auth, OAuth, Resend, Stripe, file storage — whichever apply). Each var commented with what it is and where to get it.
- [ ] Add `.env.local` to `.gitignore`
- [ ] Set up Prisma v7 with Neon PostgreSQL (schema, config, db client)
- [ ] Set up Upstash Redis cache client in `lib/cache.ts` with `getCachedOrFetch()` and `invalidateTag()` wrappers. Add `@upstash/redis` to dependencies.
- [ ] Apply design-style-guide.md tokens to globals.css (Tailwind v4 CSS-first config — @theme directive, no tailwind.config.ts)
- [ ] Create root layout with correct font, QueryClientProvider, [if dark mode = Yes: ThemeProvider + next-themes; if No: skip]
- [ ] Build sidebar layout (collapsible, nav items, user section[, dark mode toggle if enabled])
- [ ] Build page header component (breadcrumb + title + actions)
- [ ] Install JB Better Auth UI: `pnpm dlx shadcn@latest add https://better-auth-ui.desishub.com/r/auth-components.json`
- [ ] **Integrate installed auth files into existing routes — do NOT overwrite existing `page.tsx` or `layout.tsx`. Edit and merge.**
- [ ] Configure Better Auth env vars (BETTER_AUTH_SECRET, BETTER_AUTH_URL, OAuth keys if in scope)
- [ ] Create protected route middleware (middleware.ts — edge-level auth check before dashboard renders)
- [ ] Build custom 404, error, and loading pages
- [ ] Verify: login, signup, OAuth (if configured), protected routes all work

### Dependencies
- Neon database created, DATABASE_URL set in .env.local
- Upstash Redis database created, UPSTASH_REDIS_URL and UPSTASH_REDIS_TOKEN set in .env.local
- Resend account created, RESEND_API_KEY set (for auth emails)

---

## Phase 2 — Core Features
**Goal:** All primary screens built and connected to real data.

### Tasks
- [ ] Define Prisma schema for: [list ALL models specific to this project]
- [ ] Run database migration: `pnpm db:push && pnpm db:generate`
- [ ] Create `prisma/seed.ts` with 50+ realistic records (edge cases included). Add `"db:seed": "tsx prisma/seed.ts"` to scripts.
- [ ] Run seed: `pnpm db:seed`
- [ ] Install JB Data Table: `pnpm dlx shadcn@latest add https://jb.desishub.com/r/data-table.json`
- [ ] Build API routes (Route Handlers) with Redis caching (`getCachedOrFetch` + `invalidateTag`) and server-side pagination for: [list endpoints]
- [ ] Build list pages with Data Table (search, filters, pagination, Excel + PDF export)
- [ ] Build detail/view pages for: [list entities]
- [ ] Build create/edit forms (React Hook Form + Zod validation) — every form wrapped in Suspense + ErrorBoundary
- [ ] Build stat cards for dashboard overview
- [ ] Add empty states and loading skeletons for all pages
- [ ] Ensure all pages respect auth state
- [ ] Verify: every GET route caches via Redis, every mutation invalidates the cache

### Dependencies
- Phase 1 must be complete (auth + layout working)

---

## Phase 3 — [Payments & Billing / Skip if no monetization]
**Goal:** Users can pay, subscriptions tracked, features gated.

### Tasks
- [ ] Install JB Zustand Cart: `pnpm dlx shadcn@latest add https://jb.desishub.com/r/zustand-cart.json`
- [ ] Install JB Stripe UI: `pnpm dlx shadcn@latest add https://stripe-ui-component.desishub.com/r/stripe-ui-component.json`
- [ ] Configure Stripe env vars (STRIPE_SECRET_KEY, NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY)
- [ ] Create products and pricing in Stripe dashboard
- [ ] Build checkout flow (use installed Stripe UI)
- [ ] Set up Stripe webhook handler at /api/webhooks/stripe
- [ ] Gate premium features behind subscription status
- [ ] Build billing management page (upgrade, cancel, invoices)

### Dependencies
- Phase 2 must be complete (user accounts + core data exist)
- Better Auth installed (Stripe UI requires it)

---

## Phase 4 — [File Uploads / Skip if no files]
**Goal:** Users can upload and manage files.

### Tasks
- [ ] [If R2/S3] Install JB File Storage UI: `pnpm dlx shadcn@latest add https://file-storage.desishub.com/r/file-storage.json`
- [ ] [If R2/S3] Configure storage env vars (R2 or S3 credentials)
- [ ] [If UploadThing] Install UploadThing SDK and follow https://jb.desishub.com/blog/image-upload-with-uploadthing
- [ ] Build upload UI in relevant feature pages

### Dependencies
- Phase 2 must be complete

---

## Phase 5 — [Email & Notifications / Skip if no emails]
**Goal:** App communicates with users via email.

### Tasks
- [ ] Install and configure Resend + React Email
- [ ] Build email templates with React Email
- [ ] Wire welcome email (on signup)
- [ ] Wire password reset email (Better Auth already handles this)
- [ ] Wire payment receipt email (if Stripe enabled)

### Dependencies
- Phase 1 (auth) must be complete

---

## Phase 6 — Polish & Deploy
**Goal:** App is production-ready and live.

### Tasks
- [ ] Test all CRUD operations end-to-end
- [ ] Test auth flows on mobile and desktop
- [ ] Test payment flow in Stripe test mode (if applicable)
- [ ] Verify responsive design on mobile
- [ ] **Run pre-deploy code review:** paste the prompt from `pre-deploy-review.md` (in the VibeKit repo root) into Claude Code. Address every Critical issue. Save the report to `pre-deploy-review-report.md`.
- [ ] Address all Critical findings from the review
- [ ] Set all environment variables in Vercel
- [ ] Deploy to Vercel
- [ ] Configure Cloudflare DNS + custom domain
- [ ] Verify Resend sending domain (if applicable)
- [ ] Run production checklist

### Production Checklist
- [ ] All env vars set in Vercel
- [ ] Database migrations applied to production
- [ ] Auth flows work on production URL
- [ ] Custom domain live with SSL
- [ ] Emails land in inbox (not spam)
- [ ] File uploads work in production
- [ ] 404 and error pages styled
```

---

### File 3: `design-style-guide.md`

**CRITICAL:** Take the design-style-guide.md template from the framework (https://raw.githubusercontent.com/MUKE-coder/vibekit/main/design-style-guide.md) and **customize it for this project**. Replace:

- The project name header ("Invoice Pro" → the user's project name)
- **Primary visual reference:** at the very top, add a section "## Visual reference" with a short paragraph describing the Dribbble shot(s) the user pasted (color, typography, card style, button style, mood). This is the anchor — every later token decision must be consistent with this paragraph.
- Primary color palette (extracted from the Dribbble shot AND the user's brand color answer — if they conflict, the Dribbble reference wins unless the user explicitly overrode)
- Typography choices (font family + weights inferred from the Dribbble shot)
- Aesthetic philosophy (based on user's "feel" answers + reference image)
- Card / button / form-input specs (radius, shadow, border, padding) extracted directly from the reference shot — be specific (e.g. "8px radius cards with 1px #E5E1D8 border and shadow-xs", "black pill primary button px-6 py-3")
- Component examples that are project-specific (invoices → their domain)
- Status badge colors (invoice statuses → their entity statuses)
- Landing page guidance (tailored to their type of product)
- PDF template notes (only if they need PDFs)
- Email template notes (only if they need emails)
- **Dark mode section:** if user said No to dark mode, REMOVE all dark mode references (no `.dark` classes, no dark palette, no toggle). Add a note at the top: "Dark mode: NOT supported in this project."

Output the **full customized file** as File 3. Keep sections 1–16 intact, but rewrite content to match the project. Do NOT leave placeholders.

**Critical:** The Dribbble reference is the SOURCE OF TRUTH for every visual decision in this file. Don't invent a generic "premium SaaS" palette — actually look at the user's reference shot and pick colors / weights / radii that match it.

---

### File 4: `prompt.md`

The prompt the user will paste into Claude Code to start building.

```
# Claude Code — Build Prompt

Read the following files in order before doing anything:
1. `master_prompt.md` — Your tech stack rules, Prisma v7 patterns, and coding standards. Follow EXACTLY.
2. `design-style-guide.md` — The visual design system for this project. Apply to every component you build.
3. `jb-components.md` — The JB component reference. Use these components before writing from scratch.
4. `project-description.md` — What we are building. Every decision must align with this.
5. `project-phases.md` — The build plan. Work through phases in order.

## Rules
- Work through ONE phase at a time. Complete all tasks in a phase before moving to the next.
- After completing each phase, stop and confirm with me before proceeding.
- Follow design-style-guide.md tokens exactly (colors, typography, spacing, radius).
- Use Prisma v7 patterns (NOT v6). See master_prompt.md for the exact setup.
- **Use React Query for all client data fetching + Redis for API-layer caching** (getCachedOrFetch + invalidateTag from lib/cache.ts). Never useEffect for data.
- Use React Hook Form + Zod for all forms.
- Use API Routes (Route Handlers) for all server-side logic.
- Use Framer Motion for animation (default). GSAP only if explicitly requested for complex marketing scroll.
- Use @react-pdf/renderer for PDF generation. Never jsPDF.
- Use xlsx for Excel export.
- **Follow performance budget:** next/dynamic for heavy imports, Suspense boundaries on every data-fetching section, ErrorBoundary on major page blocks, aspect-ratio on all images, animate transform/opacity only.
- **Before building auth, file uploads, checkout, data tables, or blogs from scratch — check jb-components.md and install the relevant component first.**

## Start
Begin with **Phase 1 — Foundation** from project-phases.md. Read the phase tasks and execute them in order.
```

---

## Your Interview Process

### Step 1 — Acknowledge
Confirm you understand the framework. List the tech stack and the 4 files you will generate.

Also, in the acknowledgement, **remind the user about the two optional agent-tooling installs** that compound VibeKit's value if they haven't done them yet:

1. **ui-ux-pro-max-skill** (a Claude Code skill) — senior-designer rules that auto-load every conversation. Install:
   ```bash
   mkdir -p ~/.claude/skills && git clone https://github.com/nextlevelbuilder/ui-ux-pro-max-skill ~/.claude/skills/ui-ux-pro-max
   ```
2. **Playwright MCP** — gives the agent a real browser (over MCP) to verify its own UI work: open the page it just built, confirm it renders, and click through the flow. Add it to Claude Code with:
   ```bash
   claude mcp add playwright npx @playwright/mcp@latest
   ```

`npx vibekit-framework init` installs both for you — it registers the Playwright MCP in your project's `.mcp.json` and clones the ui-ux-pro-max-skill into your Claude Code config (the commands above are the manual fallback). See [`agent-tooling.md`](https://github.com/MUKE-coder/vibekit/blob/main/agent-tooling.md) for non-Claude agents and the full rationale. Don't block on these — proceed with the interview even if the user hasn't installed them.

### Step 1.5 — Check if a public template fits the project (CRITICAL)

Before doing anything else, check whether the user's idea matches one of the **VibeKit public templates** at https://vibekit.desishub.com/templates. The current templates and the projects they fit:

| Template | Fits when the user wants to build... |
|---|---|
| **Personal Developer Portfolio** (`personal-portfolio`) | A personal portfolio, developer site, "about me" page, freelancer profile, designer showcase, or anything single-page-resume-style |
| **Developer Blog** (`developer-blog`) | A technical blog, tutorials site, devlog, MDX-based publication |

If the user's idea CLEARLY matches a template (e.g. "I want a portfolio", "build me a personal site", "I want to start a tech blog"):

1. **Stop.** Do not proceed with the 4-file generation flow.

2. Tell the user:

   > *"Your project matches the **`<template-name>`** template at vibekit.desishub.com/templates/`<template-slug>`. Cloning a finished template and customizing it is faster and produces a better result than building from scratch. Do you want to (A) clone the template and run the customization interview, or (B) build from scratch with the standard 4-file VibeKit flow anyway?"*

3. If they pick **A**: tell them to visit the template page to get the clone command + the customization prompt to paste into their AI agent. Do NOT generate the 4 files. End the conversation.

4. If they pick **B** OR if their idea is borderline (e.g. "portfolio with built-in CRM"): proceed to Step 2 with the standard flow.

If the idea does NOT match any template, skip this step silently and proceed to Step 2.

### Step 2 — Decide if an interview is needed (CRITICAL)

Read my app idea carefully. Then determine:

**A) "Brief is detailed enough"** — if my idea already covers most of: core users, key features, data model hints, monetization, file uploads, email, design direction (color/feel/inspiration), and dark mode preference, then SKIP the interview entirely. Tell me explicitly:

> *"Your brief is detailed enough — no interview needed. Here's everything I understood."*

…then jump to Step 3.

**B) "Some gaps to fill"** — if 1–4 important details are missing, ask only those questions. Don't pad the interview to hit a quota.

**C) "Brief is too thin"** — if the idea is vague (e.g. "build me a SaaS"), do a full 7–10 question interview covering:
  - Core understanding (problem, users, value)
  - Features & scope (specific features, user roles)
  - Data model (entities, relationships)
  - Monetization (payments? Stripe or DGateway? Subscriptions or one-time?)
  - File uploads (R2/S3 / UploadThing / None?)
  - Email (which triggers?)
  - **Visual design (always ask):** brand color, typography, aesthetic feel, inspiration, what to avoid, **dark mode Yes/No**
  - Timeline / scope v1

Rules for interview mode:
- Ask **one question at a time** (max 2-3 if tightly related)
- Be smart — skip obvious questions (e.g. don't ask "does an e-commerce app need a cart?")

### Step 2.5 — Dribbble reference image (MANDATORY for EVERY project — never skip)

Before generating any files (and regardless of how detailed the brief is — including the "no interview needed" path), you MUST get at least ONE Dribbble UI reference image from the user. Words like "clean, premium, fast" are too vague to design from. A pasted Dribbble shot is high-fidelity, unambiguous, and lets you reverse-engineer color palette, typography weight, spacing rhythm, card style, button style, and motion direction directly.

Do this:

1. Look at the project type and any visual hints already given. Generate **2–3 specific Dribbble search terms** the user can paste into the search bar at https://dribbble.com/search.

   Examples by project type:
   - POS / cashier app → `"pos dashboard ui"`, `"retail point of sale"`, `"hardware shop pos"`
   - Personal task manager → `"task app modern minimal"`, `"todo dashboard clean"`, `"productivity app ui"`
   - SaaS landing page → `"saas landing page"`, `"startup landing dark"`, `"premium saas hero"`
   - E-commerce admin → `"ecommerce admin dashboard"`, `"product management ui"`
   - Booking app → `"booking app ui"`, `"appointment scheduler dashboard"`
   - CRM → `"crm dashboard"`, `"sales pipeline ui"`
   - School / LMS → `"education platform ui"`, `"learning dashboard"`
   - Personal portfolio → `"developer portfolio"`, `"designer portfolio minimal"`
   - Blog → `"blog reading experience"`, `"editorial blog ui"`

2. Tell the user EXACTLY this:

   > *"Before we customize the design, I need at least ONE Dribbble UI reference so I can match the visual quality you want. Words like 'clean' or 'premium' are too vague to design from — a real image is 100x more useful.*
   >
   > *Search Dribbble using one of these terms:*
   > - *`<search-term-1>`*
   > - *`<search-term-2>`*
   > - *`<search-term-3>`*
   >
   > *(Or use your own term if you have one in mind.)*
   >
   > *Pick a shot whose aesthetic you'd want your app to match — pay attention to: color palette, font weight, card style, spacing, button shape. Open the shot in full size, **right-click → Copy Image**, and paste it directly into our chat. You can attach 1–3 references if you want; one is the minimum.*
   >
   > *Don't paste a Dribbble URL — paste the image itself. Once you've pasted, I'll analyze it and adapt the design-style-guide.md to match."*

3. Wait for the user to paste the image(s). If the user resists ("I don't have time", "just make it look good", "any clean design"), tell them:

   > *"This is the single biggest predictor of whether your app will look like 'a real product' or 'AI-built generic'. It takes 2 minutes. Please send at least one shot."*

   Do NOT proceed without a reference. The Dribbble step is non-negotiable.

4. Once images are pasted, analyze each carefully and extract:
   - Primary brand color (closest hex)
   - Secondary / accent colors (if any)
   - Background style (flat, soft gradient, textured, dark/light)
   - Typography: serif / sans, light / heavy weight, condensed / wide
   - Card aesthetic: borders / shadows / radius / padding
   - Button style: pill / rounded / square, filled / outlined / ghost
   - Spacing rhythm: tight / generous
   - Iconography vs imagery balance
   - Overall energy: editorial / techy / playful / minimal / bold

5. Echo back what you extracted in plain English so the user can correct it:

   > *"From your reference I'm reading: warm cream background (#FAF8F5), bold heavy sans like Inter Tight 700, 16px rounded cards with subtle shadow + 1px borders, primary CTA is a black pill button, generous whitespace. Aesthetic energy: editorial-modern, like Linear's marketing site. Does that match what you wanted? Any tweaks?"*

   This becomes the SOURCE OF TRUTH for the design-style-guide.md you'll generate in Step 4.

### Step 3 — Confirm understanding & ask for consent (MANDATORY — never skip)

Before generating ANY file, you MUST do this exact sequence:

1. Write a structured summary using these section headers:

   ```
   ## What I understood

   **App:** [name + 1-sentence description]
   **Primary user:** [who]
   **Core features:** [bulleted list of 3–6]
   **Data model:** [entities + relationships]
   **Integrations:** Auth ([Better Auth + which OAuth]), Email ([Resend / None]), Payments ([Stripe / DGateway / None]), File uploads ([R2 / S3 / UploadThing / None]), Dark mode ([Yes / No])
   **Visual design (from your Dribbble reference + answers):**
     - Reference: [1-line description of the shot the user pasted]
     - Color palette: [primary hex, accent hex, bg hex]
     - Typography: [font family + display weight + body weight]
     - Card style: [border + shadow + radius spec]
     - Button style: [shape + fill + size]
     - Aesthetic energy: [3 words]
   **Out of scope (v1):** [what we're NOT building yet]
   ```

2. List any **assumptions** you had to make (mark them clearly so the user can correct).

3. Then ask exactly this:

   > *"Does this match your intent? Reply **'Yes, generate the files'** to proceed, or tell me what to adjust."*

**Do NOT generate any file in this turn.** Wait for explicit user confirmation. Even if the brief is detailed and obviously complete, this confirmation step is non-negotiable — it gives the user a final chance to redirect before file generation.

### Step 4 — Generate the 4 Files (only after explicit confirmation)

When the user confirms (some variation of "yes" / "go" / "generate"), produce all 4 files using **Claude Artifacts** so they're individually downloadable.

**Output requirements:**
- Create 4 separate Artifacts, one per file. Use markdown artifact type. Each must be downloadable from the Artifact panel.
- Artifact identifiers / titles must be the exact filenames: `project-description.md`, `project-phases.md`, `design-style-guide.md`, `prompt.md`.
- Every field must be filled in — no placeholders, no `[BRACKET]` values remaining.
- For `design-style-guide.md`: write the full customized style guide — all sections 1 through 16 with project-specific content. Don't link to the template; write the entire file.

**At the end of the message**, also provide ONE-CLICK file creation as a fallback:

   ```bash
   # Run from your project root to create all 4 files at once
   mkdir -p ./
   cat > project-description.md << 'EOF'
   ...full project-description.md content...
   EOF

   cat > project-phases.md << 'EOF'
   ...full project-phases.md content...
   EOF

   cat > design-style-guide.md << 'EOF'
   ...full design-style-guide.md content...
   EOF

   cat > prompt.md << 'EOF'
   ...full prompt.md content...
   EOF

   echo "✓ Created 4 VibeKit project files"
   ```

This way the user has TWO ways to get the files into their project:
1. **Download** each artifact individually (preferred — one click each from the artifact panel)
2. **Copy-paste** the single bash heredoc block into their terminal — creates all 4 at once

Tell the user explicitly which method to use:

> *"Each file is a downloadable Artifact in the panel on the right. Click the download icon on each one. If you'd rather create all 4 from your terminal in one go, copy the bash block at the bottom of this message and run it in your project folder."*

---

## My App Idea

[REPLACE THIS LINE WITH YOUR APP DESCRIPTION]

Example: "I want to build a school management system where teachers can manage students, track attendance, and parents can log in to see their child's progress and pay school fees."

---

*Powered by the VibeKit Framework — github.com/MUKE-coder/vibekit*

# VibeKit — Pre-Design Review Prompt

> **When to use:** Run this in your AI agent after a UI is built (or before a public release) to audit the app's **design** — not its code correctness. It is the visual/UX counterpart to [`pre-deploy-review.md`](./pre-deploy-review.md): that one checks performance and security; this one checks whether the app actually looks and feels designed.

> **How to use:** Open your agent in the project root and paste the prompt below. It compares the app against your own `design-style-guide.md` **and** a set of universal design principles, writes a Critical / High / Medium report, and then fixes what you approve.

> **Best with Playwright MCP.** `npx vibekit-framework init` registers it. With a browser, the agent evaluates the *rendered* pages — real contrast, spacing, hierarchy, and interaction states — instead of guessing from source. Without it, the agent reviews the code and asks you for screenshots.

---

## The Prompt — copy everything below

```
I need you to perform a senior product-designer review of my app's UI/UX. This is a
DESIGN review, not a code-correctness review. Judge what the user actually sees and
feels: hierarchy, spacing, type, color, consistency, states, accessibility, and whether
the result looks deliberately designed rather than AI-default.

## HOW TO LOOK AT THE APP (do this first)

1. Read `design-style-guide.md` in the project root. This is the SOURCE OF TRUTH for
   this app's design system — its palette, type scale, spacing scale, radii, shadows,
   and per-component specs. Most of my review is: "does the built UI match this file?"
   If the file is missing, say so and review against the universal principles alone.
2. Read `project-description.md` for what the app is, who it's for, and the intended
   tone. A children's learning app and a compliance dashboard should NOT feel the same.
3. Start the app (`pnpm dev`) and, if you have the Playwright MCP browser, OPEN each key
   page. Take an accessibility snapshot and a screenshot of each. Actually exercise
   states: hover buttons, focus inputs, submit an empty form, load a list while empty.
   Judge the RENDERED result, not just the JSX. If you have no browser, review the code
   and ask me to paste screenshots of the main pages.
4. Review at BOTH desktop (1280px) and mobile (375px). Many defects only appear at one.

Cover every distinct screen: landing/marketing, auth, the main dashboard/list, a
detail/form page, an empty state, and one error state.

## THE CHECKLIST — audit against every category

### A. Design-system fidelity (compare the app to `design-style-guide.md`)
This is the core check. Flag every deviation from the guide:
- Colors used that are NOT in the defined palette (eyeball hex values / arbitrary Tailwind
  colors like `bg-blue-500` instead of the token `bg-[color:var(--accent)]`).
- Type sizes/weights that don't match the type scale.
- Spacing that breaks the scale (random `p-[13px]`, `gap-[7px]` instead of the 4/8px rhythm).
- Border-radius / shadow values that aren't from the defined scales.
- Components (buttons, inputs, cards, tables, badges, modals) that don't match their spec
  in §7 of the guide.
- Icons from a second icon library, or emoji used as UI icons.

### B. Visual hierarchy & focal point
- Each screen has ONE clear focal point; the eye lands where intended.
- The primary action is the most prominent element on the page (size, weight, color).
- Emphasis is planned — nothing competes with the CTA; secondary actions are visibly secondary.
- Headings, body, and captions are clearly differentiated in size/weight.

### C. Layout, alignment & grid
- Elements align to a consistent grid; edges line up (text blocks to image borders, etc.).
- Consistent page margins and gutters; no arbitrary one-off offsets.
- Related items are grouped by proximity; unrelated items are separated (Gestalt).

### D. White space & density
- Enough breathing room — the UI isn't cluttered and cramped.
- Not SO sparse that relationships are lost or the page feels empty.
- Padding rhythm is consistent between similar components.

### E. Typography
- At most two font families (VibeKit default: one sans + one mono). A third is slop.
- Body weight 400, headings 600 — never 800/900. Display tracking tightened (-0.02 to -0.04em).
- Heading levels are SEMANTIC and in order (one h1 per page, no skipping h2→h4 for size).
- Body line length is readable (~45–75 characters); line-height comfortable (1.5-ish body).
- No orphaned/ad-hoc text styles that exist nowhere in the type scale.

### F. Color & contrast
- ONE accent color per project, used consistently for primary actions.
- WCAG AA contrast: ≥4.5:1 for body text, ≥3:1 for large text and UI/icon boundaries.
  Flag any low-contrast text (light gray on white, dark text on a dark surface).
- Semantic colors used correctly (red = error/destructive, green = success, etc.).
- NO multi-color "AI slop" gradients (purple→pink→orange), and no gradient on
  `background-clip: text` unless the style guide explicitly calls for it.
- Color is never the ONLY signal (error states also have an icon/text, not just red).

### G. Consistency & standards
- The same component looks and behaves the same on every page.
- Buttons, inputs, cards, and spacing are uniform across screens.
- Labels and terminology are consistent (don't call it "Clients" on one page, "Customers" on another).
- Matches platform conventions where users expect them (a link looks clickable, etc.).

### H. Imagery & visuals
- Images are sharp, relevant, and focused — not blurry, stretched, or generic filler.
- Visuals break up large blocks of text; long text uses bullets/sections for scannability.
- No broken images, placeholder boxes, or `lorem ipsum` shipped in a "done" screen.
- Every image has an explicit `aspect-ratio`/dimensions (no layout shift) and meaningful `alt`.

### I. Interaction states & feedback (the eight-state contract)
Every interactive component must define ALL of: default · hover · focus-visible · active ·
disabled · loading · error · success. `error` and `success` are the ones that get skipped.
- The system always shows its status: buttons show loading, lists show skeletons, actions confirm.
- Forms validate with immediate, specific feedback — not a generic "invalid" after submit.
- Empty states are designed (guidance + a next action), not a blank area.
- Destructive actions confirm before running.

### J. Navigation & wayfinding
- Navigation is clear; the user always knows where they are (active state on the current item).
- Depth has breadcrumbs or a clear back path; no dead ends.
- Users can undo / escape / go back (user control and freedom).

### K. Accessibility
- Semantic HTML (`<button>`, `<nav>`, `<main>`, real headings) — not clickable `<div>`s.
- Visible `:focus-visible` ring on every interactive element; fully keyboard-operable.
- Touch targets ≥ 44×44px on mobile.
- All form fields have associated labels.
- `prefers-reduced-motion` is honored.

### L. Responsive & layout safety
- Works at 375px with NO horizontal scroll.
- `overflow-x: clip` on BOTH `html` and `body`.
- Any grid track containing an image uses `minmax(0, 1fr)`, not bare `1fr`.
- No clickable text that wraps to two lines in nav items or CTAs.
- Display-size headings have `overflow-wrap: anywhere; min-width: 0`.
- Section layouts collapse to a single column on mobile.

### M. Motion hygiene
- Animate `transform`/`opacity` only (not `top`/`left`/`width`/`height`).
- Durations are short (< 300ms for UI feedback); easing is consistent.
- NEVER `transition-all` — always name the properties (`transition-[transform,opacity]`).
- No gratuitous, distracting, or looping animation.

### N. Content & copy integrity (treat fabrication as Critical — it's a liability)
- Flag any quantitative/factual claim I did NOT supply: invented conversion metrics
  ("+47% conversion"), social proof ("trusted by 50,000+ teams"), benchmarks ("10× faster"),
  fake testimonials/logos, or pricing/guarantees I never specified. Replace each with a
  visible placeholder (`—` + "metric to confirm") — do not swap in a different invented number.
- Copy is scannable: short paragraphs, bullets for lists, clear microcopy on buttons/labels.

### O. Emotional tone & brand cohesion (judgment call — flag, don't silently "fix")
- Does the design evoke a coherent feeling that fits the product and audience, or does it
  read as generic template output?
- Is the `<nav>` the AI-default shape (wordmark-left · 4–5 centered links · one button-right ·
  hairline border)? If so, surface it as a question: deliberate, or inherited default?

### P. Marketing / landing-page anti-tells (only for marketing surfaces, NOT dashboards/tables)
These are the specific signatures an LLM reaches for when it tries to "look designed." They
apply to landing pages, marketing sections, portfolios, and hero areas — NOT to product UI
(dashboards, data tables, admin, multi-step forms), where consistent repetition is correct.
On marketing surfaces, flag each:
- **Em-dashes in user-facing copy.** The single most common AI tell. Scan every visible string
  — headlines, eyebrows, buttons, body, captions, alt text — for `—` (or `–` as a separator).
  Replace with a period, comma, colon, parentheses, or a plain hyphen. (This is about the
  rendered UI copy, not code comments or these docs.)
- **Section-number / status eyebrows.** `00 / INDEX`, `001 · Capabilities`, `06 · How it works`,
  `V0.6`, `BETA`, `INVITE-ONLY` above a heading. Name the topic in plain words or drop it.
- **Eyebrow overuse.** A small uppercase `tracking-wider` label above *every* section. Cap it:
  at most one per ~3 sections; the headline alone usually suffices.
- **Hero overflow.** Hero should fit the first viewport: headline ≤ 2 lines, subtext ≤ ~20 words,
  the primary CTA visible without scrolling. A 4-line headline is a font-size error.
- **Hero clutter.** Trust micro-strips ("Used by teams at…"), taglines under the CTAs, or a
  logo wall stuffed *inside* the hero. Move those to their own section below.
- **Three equal feature cards** in a row — the generic default. Vary composition (asymmetric,
  2-col zigzag capped at 2 in a row, bento with real cell-count = item-count).
- **Layout repetition.** The same section layout family reused down the page. A ~8-section page
  should use ≥ 4 distinct layout families.
- **Fake previews.** A product "screenshot" built from `<div>` rectangles (fake task lists,
  terminals, dashboards). Use a real screenshot/image or omit it.
- **Text wordmarks in a logo wall.** `<span>Acme</span>` rows instead of real SVG brand logos.
- **Decoration tells.** Weather/locale/time strips ("LIS 14:23 · 18°C"), scroll cues
  ("↓ scroll"), decorative status dots on every item, hero-bottom mono strips
  (`BRAND. MOTION. SPATIAL.`), version footers (`v1.4.2`, `Build 0048`) on a marketing page.
- **"Jane Doe" data.** Generic names (John Doe), startup-slop brands (Acme/Nexus), and
  fake-precise stats the brand never claimed (`99.99%`, `4.1×`) — overlaps rule N.
- **Cute-but-broken copy.** Re-read every string; flag AI-hallucinated wordplay, forced
  metaphors, or performative-craftsman labels ("Field notes", "On our desks"). Plain beats cute.
- **Unmotivated motion.** Animation with no job (hierarchy / feedback / storytelling / state).
  Also: more than one marquee per page, and any `window.addEventListener("scroll", …)` — use
  `IntersectionObserver` / GSAP ScrollTrigger instead.

## SEVERITY RUBRIC

- **Critical** — breaks usability or ships a falsehood: fabricated claims; body text failing
  WCAG AA; horizontal scroll / broken layout on mobile; unreadable or overlapping content;
  a form that can fail with no error state; a core flow not keyboard-operable.
- **High** — clearly undermines quality: inconsistent components; weak or absent hierarchy;
  off-palette colors; cluttered or empty-feeling layout; missing hover/focus states; unsized
  images causing layout shift; off-scale spacing/type throughout.
- **Medium** — polish: minor alignment drift, spacing-rhythm inconsistencies, sub-optimal
  line length, motion timing, small copy scannability issues.

## OUTPUT FORMAT

Structure the review as:
1. **Executive Summary** — count by severity + a one-paragraph verdict on whether this looks
   designed or default, and how closely it follows `design-style-guide.md`.
2. **Per-screen findings** — for each screen reviewed, the issues found.
3. **Critical / High / Medium sections** — each finding with:
   - The screen/component and file path (+ line numbers where it's a code fix)
   - Which principle or style-guide rule it violates
   - Why it matters to the user
   - The concrete fix, using the project's design tokens (never hardcoded values)
4. **Recommendations** — higher-level moves that would raise the design ceiling.

## CONTEXT

- Design source of truth: `design-style-guide.md` (palette, type scale, spacing, components).
- Stack: Next.js 16, Tailwind v4 (CSS-first `@theme` tokens in `globals.css`), shadcn/ui,
  Framer Motion, lucide-react. Fixes MUST use the CSS-variable tokens, never raw hex/px.
- Read `project-description.md` for the app's audience and intended tone.

Be specific and visual. Point to exact screens and elements. Every fix must respect the
existing design tokens.

After the review, write the findings to `pre-design-review-report.md` at the project root
so I can address them iteratively.
```

---

## After the Review

1. Read `pre-design-review-report.md` carefully.
2. Fix every **Critical** issue — a falsehood or an unusable/inaccessible screen ships harm.
3. Fix **High** issues before you call the UI done.
4. Schedule **Medium** polish for the next pass.
5. Re-run after any significant UI change, and once more before a public launch.
6. Every fix must use your `design-style-guide.md` tokens — if a fix needs a value the guide
   doesn't have, add it to the guide first, then use it. The guide stays the source of truth.

> Checklist synthesized from Nielsen Norman Group (design guidance & usability heuristics),
> the Webflow design-system checklist, developerux's UX principles checklist, and Jena
> Ehlers' "6-Point Checklist for an Effective Design." Layout-safety, honest-copy and
> eight-state rules are shared with VibeKit's `design-style-guide.md` and adapted in part
> from [Hallmark](https://github.com/nutlope/hallmark) (MIT © 2026 Hallmark contributors).
> The marketing-page anti-tells in section P are adapted from the production-tested catalog in
> [Taste Skill](https://github.com/Leonxlnx/taste-skill) (MIT © 2026 Leon Lin / Leonxlnx) —
> its stack-specific opinions (avoid Inter, avoid Lucide, per-page variance) are intentionally
> NOT adopted, because VibeKit standardizes on one locked design system + lucide-react.

---

*Part of the VibeKit Framework — github.com/MUKE-coder/vibekit*

# VibeKit — Pre-Deploy Code Review Prompt

> **When to use:** Run this prompt in Claude Code as the FINAL task before deploying to production. It performs a senior-level audit covering performance, security, background tasks, and resource usage.

> **How to use:** Open Claude Code in your project root, paste the prompt below, and let it generate the review report. Address every Critical issue before deploying. Address High priority issues within the first week of launch.

---

## The Prompt — copy everything below

```
I need you to perform a comprehensive senior-level code review of my codebase.
Analyze the code thoroughly and identify issues in these critical areas.

## 1. HIGH CPU INTENSIVE TASKS & RESOURCE CONSUMPTION

Identify and flag:
- Synchronous blocking operations in request handlers
- Heavy computational tasks running in main threads
- Inefficient algorithms (O(n²) or worse when O(n log n) is possible)
- Expensive operations inside loops
- Recursive functions without memoization
- String concatenation in tight loops
- Large object serialization/deserialization in hot paths
- Regex operations that could cause catastrophic backtracking
- Missing pagination on large dataset operations
- Unoptimized image/file processing

### JS Bundle & Web Vitals (new):
- Eager imports of `@react-pdf/renderer`, `xlsx`, chart/editor/map libraries (should use `next/dynamic`)
- Missing `<Suspense>` boundaries around data-fetching sections (blocks page render)
- Missing `<ErrorBoundary>` wrappers on major page blocks (one crash kills the whole page)
- Images without `aspect-ratio` or explicit dimensions (causes CLS)
- CSS/JS animations on `top`/`left`/`width`/`height` instead of `transform`/`opacity` (causes layout thrashing)
- Missing `will-change: transform` on heavy animated elements (hero sections, viewport-filling animations)
- Large client component bundles that could be Server Components (check for unnecessary `"use client"`)
- CLS contributors: font swap without `size-adjust`, layout shifts from dynamic ads/content
- LCP contributors: hero image without `priority`, font without `preload: true`, client-side hero content

For each issue found:
- Show the problematic code (file path + line numbers)
- Explain the CPU impact
- Provide optimized alternative with code example
- Estimate performance improvement

## 2. PERFORMANCE BOTTLENECKS

### Database & Query Issues:
- N+1 query problems (missing eager loading, includes, or joins)
- SELECT * instead of specific columns
- Missing database indexes on frequently queried columns
- Queries inside loops
- Lack of query result caching (Redis `getCachedOrFetch` not used on hot API routes)
- Missing connection pooling
- Inefficient ORM usage
- Missing batch operations (bulk inserts/updates)
- Suboptimal transaction boundaries

### Redis Cache Audit:
- Hot API route GET handlers without `getCachedOrFetch()` wrapper
- POST/PATCH/DELETE handlers without `invalidateTag()` call
- Cache keys with no TTL or TTL too long (>5min for data, >1h for reference)
- Cache invalidation missing on related entities (e.g. updating invoice doesn't invalidate dashboard stats)
- Incorrect cache key patterns (missing user ID scope, leaking data across users)
- Over-cached data (sessions, raw file contents, real-time data)
- No cache warming strategy for critical dashboard queries
- Cache stampede risk on high-traffic endpoints (consider `Promise.all` deduplication)

### Logging & Monitoring:
- Excessive logging in production (debug/trace levels)
- Logging inside tight loops
- Synchronous logging blocking operations
- Large object logging without truncation
- Missing log levels configuration
- Unstructured logs that hinder parsing

### Memory Leaks & Inefficiencies:
- Global variables holding large datasets
- Event listeners not being cleaned up
- Circular references
- Large arrays/collections not being cleared
- Streams not being properly closed
- Cache without expiration/size limits

### Network & I/O:
- Missing connection timeouts
- No retry logic with exponential backoff
- Sequential API calls that could be parallel
- Missing response compression
- Unnecessary data transfer
- No request batching where applicable

For each bottleneck:
- Pinpoint exact location in code (file path + line numbers)
- Measure/estimate impact (latency, throughput, memory)
- Provide optimized solution with code
- Suggest monitoring/profiling approach

## 3. BACKGROUND TASKS, CRON JOBS & ASYNC OPERATIONS

Review and optimize:
- Job queues without proper error handling
- Missing job idempotency (jobs that can't safely retry)
- Lack of job timeouts
- No dead letter queues for failed jobs
- Cron jobs without distributed locking (race conditions in multi-instance deployments)
- Background tasks without progress tracking
- Missing graceful shutdown handling
- Inefficient batch processing (not chunking large datasets)
- Jobs running at inappropriate intervals
- Missing job monitoring and alerting
- Cron schedules that overlap or conflict
- Workers without concurrency limits
- Missing job prioritization

For each issue:
- Show problematic implementation
- Explain production risks
- Provide robust alternative
- Recommend job infrastructure (if applicable)

## 4. SECURITY VULNERABILITIES

### Input Validation & Injection:
- SQL injection vulnerabilities
- NoSQL injection possibilities
- Command injection risks
- XSS (Cross-Site Scripting) vulnerabilities
- Path traversal vulnerabilities
- Unvalidated redirects
- Missing input sanitization
- Insufficient data type validation

### Authentication & Authorization:
- Hardcoded credentials or API keys
- Weak password policies
- Missing rate limiting on auth endpoints
- Insecure session management
- Missing CSRF protection
- Inadequate authorization checks
- Privilege escalation possibilities
- Missing multi-factor authentication

### Data Protection:
- Sensitive data in logs
- Unencrypted sensitive data storage
- Insecure crypto usage (weak algorithms, hardcoded keys)
- Missing encryption in transit
- Exposed internal endpoints
- Verbose error messages exposing system info

### Dependencies & Configuration:
- Outdated dependencies with known CVEs
- Missing security headers
- Insecure CORS configuration
- Debug mode enabled in production
- Exposed environment variables
- Missing rate limiting
- Unprotected admin interfaces

### Other:
- Mass assignment vulnerabilities
- Insecure deserialization
- XML external entity (XXE) vulnerabilities
- Server-side request forgery (SSRF)
- Missing security updates

For each vulnerability:
- Classify severity (Critical, High, Medium, Low)
- Show vulnerable code (file path + line numbers)
- Explain exploitation scenario
- Provide secure implementation
- Reference OWASP guidelines if applicable

## 5. COPY INTEGRITY & DESIGN JUDGMENT

### Fabricated Claims (treat as Critical — this is a liability issue, not a style issue):

Scan every user-facing page — landing, pricing, marketing sections, emails, PDF templates — for quantitative or factual claims that were INVENTED rather than supplied by me. Flag each one:
- Conversion or performance metrics ("+47% conversion", "saves 12 hours a week", "3× more bookings")
- Social proof counts ("trusted by 50,000+ teams", "2M invoices processed")
- Benchmarks and comparisons ("10× faster", "99.99% uptime", "sub-50ms")
- Testimonials — invented quotes, names, roles, companies, or avatars
- Customer or partner logos I never named
- Pricing, plan limits, trial lengths, or money-back guarantees I never specified
- Awards, press mentions, funding, or compliance badges (SOC 2, HIPAA, GDPR)

These ship as factual claims by my business on the public web. Unlike a placeholder image, a fabricated statistic looks finished, so nobody catches it. For each one found, report the file path + line number and replace it with a visible placeholder (`—` plus a "metric to confirm" label) or remove the element. Do not substitute a different invented number.

### Default-Nav Prompt (judgment call — flag for a decision, do NOT auto-"fix"):

Look at the `<nav>` on the marketing pages. Does it match the generic AI-default shape — wordmark far left, 4–5 links centered, a single button far right, a hairline bottom border, sticky?

If yes, surface it as a question rather than a defect: *this is the shape every AI-generated site converges on — is it the deliberate choice here, or the default that got left in?* It is a perfectly good nav for many products. The point is that it should be chosen, not inherited. Note any product-specific reason to diverge (a search-first product, an app with a workspace switcher, a brand with a strong logotype that deserves more room).

### Transition & Motion Hygiene:
- Any className containing `transition-all` — replace with an explicit property list (`transition-[transform,border-color,box-shadow]`, `transition-colors`, `transition-opacity`)
- Interactive components missing any of the eight required states: default, hover, focus-visible, active, disabled, loading, error, success
- Missing `overflow-x: clip` on both `html` and `body`
- Grid tracks containing images declared as bare `1fr` instead of `minmax(0, 1fr)`

## OUTPUT FORMAT

Structure your review as:

1. **Executive Summary** — high-level findings count and severity
2. **Critical Issues** — must fix before production
   - Issue description
   - Code location
   - Risk/Impact
   - Fix with code example
3. **High Priority Issues** — significant impact (same format)
4. **Medium Priority Issues** — should address soon (same format)
5. **Recommendations** — best practices and optimizations
6. **Refactored Code Examples** — show before/after for major changes
7. **Performance Metrics** — expected improvements where measurable
8. **Security Checklist** — compliance items to verify

## CONTEXT

- Tech stack: Next.js 16, TypeScript, Prisma v7, Neon Postgres, Better Auth, React Query, Upstash Redis, Framer Motion, Tailwind v4, shadcn/ui
- Deployment: Vercel + Cloudflare DNS
- Read project-description.md for the app's specific scope, integrations, and expected load
- Read project-phases.md to understand what's been built

Be thorough, specific, and provide actionable fixes with file paths, line numbers, and full code examples.

After the review, write the findings to `pre-deploy-review-report.md` at the project root so I can address them iteratively.
```

---

## After the Review

1. Read `pre-deploy-review-report.md` carefully.
2. Address every **Critical** issue before deploying. No exceptions.
3. Address every **High Priority** issue within the first week of launch.
4. Schedule **Medium Priority** issues for the next iteration.
5. Re-run this prompt after each major feature addition or before each public release.

> Honest-copy and default-nav review checks adapted from [Hallmark](https://github.com/nutlope/hallmark) (MIT © 2026 Hallmark contributors).

---

*Part of the VibeKit Framework — github.com/MUKE-coder/vibekit*