vibe-ship-it 1.5.0 → 1.6.0

package/README.md

@@ -6,7 +6,7 @@
 
 A set of AI agents and skills that help designers vibe-code their ideas to life, without learning programming.
 
-Works with **VS Code Copilot**, **Claude Code**, and **OpenAI Codex**.
+Works with **VS Code Copilot**, **Claude Code**, **Cursor**, and **OpenAI Codex**.
 
 - Live site: https://vibe-ship-it.vercel.app
 - GitHub: https://github.com/sso-ss/vibe-ship-it
@@ -56,7 +56,7 @@ Works with **VS Code Copilot**, **Claude Code**, and **OpenAI Codex**.
 npx vibe-ship-it init
 ```
 
-It'll ask which AI tool you use (VS Code Copilot, Claude Code, or OpenAI Codex) and install only what you need.
+It'll ask which AI tool you use (VS Code Copilot, Claude Code, Cursor, or OpenAI Codex) and install only what you need.
 
 To remove:
 
@@ -80,6 +80,7 @@ If you don't want skill files in your repo, add to `.gitignore`:
 ```
 .github/agents/
 .github/copilot-instructions.md
+.cursor/rules/
 skills/
 .claude/
 CLAUDE.md
@@ -135,6 +136,12 @@ AGENTS.md                               ← OpenAI Codex persona (installed via
   save.md                               ← /save
   explain.md                            ← /explain
 
+.cursor/rules/                           ← Cursor rules (auto-attached by description)
+  main.mdc                              ← Core persona (always active)
+  build-page.mdc                        ← Triggered by UI building requests
+  save-data.mdc                         ← Triggered by data persistence requests
+  ...                                   ← 17 rule files total
+
 skills/
   what-am-i-building/                   ← Project setup + routing
   noob-mode/                            ← Plain English translation

package/bin/init.js

@@ -18,55 +18,69 @@ if (command === 'init') {
   console.log('    1. VS Code Copilot')
   console.log('    2. Claude Code')
   console.log('    3. OpenAI Codex')
-  console.log('    4. All of the above (installs everything)')
+  console.log('    4. Cursor')
+  console.log('    5. All of the above (installs everything)')
   console.log('')
 
   const readline = require('readline')
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
 
-  rl.question('  Pick a number (1-4, default: 4): ', (answer) => {
+  rl.question('  Pick a number (1-5, default: 5): ', (answer) => {
     rl.close()
-    const choice = (answer || '4').trim()
+    const choice = (answer || '5').trim()
 
     // Determine what to skip based on choice
     const skipPaths = new Set()
     if (choice === '1') {
-      // VS Code Copilot only — skip Claude and Codex files
+      // VS Code Copilot only — skip Claude, Codex, and Cursor files
       skipPaths.add('CLAUDE.md')
       skipPaths.add('AGENTS.md')
       skipPaths.add('_claude')
+      skipPaths.add('_cursor')
     } else if (choice === '2') {
-      // Claude Code only — skip Copilot and Codex files
+      // Claude Code only — skip Copilot, Codex, and Cursor files
       skipPaths.add('AGENTS.md')
       skipPaths.add('_github')
+      skipPaths.add('_cursor')
     } else if (choice === '3') {
-      // OpenAI Codex only — skip Copilot and Claude files
+      // OpenAI Codex only — skip Copilot, Claude, and Cursor files
       skipPaths.add('_github')
       skipPaths.add('_claude')
+      skipPaths.add('_cursor')
       skipPaths.add('CLAUDE.md')
+    } else if (choice === '4') {
+      // Cursor only — skip Copilot, Claude, and Codex files
+      skipPaths.add('_github')
+      skipPaths.add('_claude')
+      skipPaths.add('CLAUDE.md')
+      skipPaths.add('AGENTS.md')
     }
-    // choice '4' or anything else = install everything
+    // choice '5' or anything else = install everything
 
     const renameMap = {
       '_github': '.github',
       '_claude': '.claude',
+      '_cursor': '.cursor',
     }
 
     console.log('')
     copyDir(templateDir, targetDir, renameMap, skipPaths)
 
-    const tools = { '1': 'VS Code Copilot', '2': 'Claude Code', '3': 'OpenAI Codex', '4': 'all tools' }
+    const tools = { '1': 'VS Code Copilot', '2': 'Claude Code', '3': 'OpenAI Codex', '4': 'Cursor', '5': 'all tools' }
     const toolName = tools[choice] || 'all tools'
 
     console.log('')
     console.log(`  ✅ Done! Installed for ${toolName}:`)
     console.log('')
-    if (choice !== '1' && choice !== '3') {
+    if (choice !== '1' && choice !== '3' && choice !== '4') {
       console.log('     6 commands (/check, /ship, /wow, /stuck, /save, /explain)')
     }
-    if (choice !== '2' && choice !== '3') {
+    if (choice !== '2' && choice !== '3' && choice !== '4') {
       console.log('     4 agents  (assistant, checker, shipper, investigator)')
     }
+    if (choice === '4' || choice === '5') {
+      console.log('    17 rules   (main + skill rules for Cursor auto-attach)')
+    }
     console.log('    13 skills  (build-page, design-system, save-data, and more)')
     console.log('')
     console.log('  Just say what you want in plain English.')
@@ -77,6 +91,7 @@ if (command === 'init') {
   const dirs = [
     path.join(targetDir, '.github', 'agents'),
     path.join(targetDir, '.claude', 'commands'),
+    path.join(targetDir, '.cursor', 'rules'),
     path.join(targetDir, 'skills'),
   ]
   const files = [
@@ -98,7 +113,7 @@ if (command === 'init') {
   })
 
   // Clean up empty parent dirs
-  ;[path.join(targetDir, '.github'), path.join(targetDir, '.claude')].forEach(dir => {
+  ;[path.join(targetDir, '.github'), path.join(targetDir, '.claude'), path.join(targetDir, '.cursor')].forEach(dir => {
     if (fs.existsSync(dir) && fs.readdirSync(dir).length === 0) {
       fs.rmdirSync(dir)
     }
@@ -147,7 +162,7 @@ if (command === 'init') {
   console.log('    npx vibe-ship-it init     Install into current project')
   console.log('    npx vibe-ship-it remove   Remove from current project')
   console.log('')
-  console.log('  Works with VS Code Copilot, Claude Code, and OpenAI Codex.')
+  console.log('  Works with VS Code Copilot, Claude Code, Cursor, and OpenAI Codex.')
   console.log('')
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibe-ship-it",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "AI skill pack for designers who vibe-code. 4 agents, 14 skills, DESIGN.md generator. Just say what you want in plain English.",
   "bin": {
     "vibe-ship-it": "./bin/init.js"

package/template/_cursor/rules/add-login.mdc

@@ -0,0 +1,9 @@
+---
+description: Adds user authentication. Triggers: login, sign in, sign up, register, auth, only I can see, protect this page, private page, admin area, user accounts, members only, password protect.
+globs: 
+alwaysApply: false
+---
+
+# Add Login
+
+Read and follow the full instructions in `skills/add-login/SKILL.md`.

package/template/_cursor/rules/before-you-ship.mdc

@@ -0,0 +1,9 @@
+---
+description: Full pre-deploy checklist. Runs automatically before deployment. Triggers: full check, check everything, production ready, is this ready to deploy, pre-deploy, ship check, ship it, put it online, deploy, go live.
+globs: 
+alwaysApply: false
+---
+
+# Before You Ship
+
+Read and follow the full instructions in `skills/before-you-ship/SKILL.md`.

package/template/_cursor/rules/build-page.mdc

@@ -0,0 +1,9 @@
+---
+description: Builds UI from descriptions, screenshots, or Figma designs. Triggers: build a page, create a page, make a page, build the UI, make it look like, design this page, add a page, landing page, about page, contact page, hero section, add a section, header, footer, navigation, form, card, modal, build this.
+globs: 
+alwaysApply: false
+---
+
+# Build Page
+
+Read and follow the full instructions in `skills/build-page/SKILL.md`.

package/template/_cursor/rules/design-system.mdc

@@ -0,0 +1,9 @@
+---
+description: Makes styles consistent. Extracts current look into reusable tokens and components. Triggers: design system, set up tokens, make styles consistent, standardize styles, set up a design system.
+globs: 
+alwaysApply: false
+---
+
+# Design System
+
+Read and follow the full instructions in `skills/design-system/SKILL.md`.

package/template/_cursor/rules/generate-design-md.mdc

@@ -0,0 +1,9 @@
+---
+description: Generates a DESIGN.md from any website URL. Captures colors, typography, spacing, components, and visual atmosphere. Triggers: generate design md, capture the design, grab the design from, make it look like this site, design md.
+globs: 
+alwaysApply: false
+---
+
+# Generate Design MD
+
+Read and follow the full instructions in `skills/generate-design-md/SKILL.md`.

package/template/_cursor/rules/main.mdc

@@ -0,0 +1,88 @@
+---
+description: 
+alwaysApply: true
+---
+
+# Designer Vibe Coding Assistant
+
+You help an excited designer build their idea. They are not a programmer. They think visually, work by feel, and want to see results immediately.
+
+## Core Rules
+
+0. **Stay consistent with past decisions.** Before starting any work, silently check if `PROJECT.md` exists in the project root. If it does, read it. Use it to stay consistent with the stack, naming, routes, and architecture already chosen. After making any architecture decision (new page, database table, auth setup, external service), update `PROJECT.md`. Also check if `DESIGN.md` exists. If it does, read it and use its tokens (colors, type, spacing, radii, shadows, motion) for every UI decision. Never invent new values when DESIGN.md defines them.
+
+1. **Show the result first, explain the code second.** Always preview in the browser. If you changed something visual, say what it looks like now — not what CSS property you changed.
+
+2. **Speed is everything.** Never block progress with questions. If you can make a reasonable assumption, make it. If you're wrong, the designer will tell you.
+
+3. **Explain only when asked or when something breaks.** Don't teach unprompted. When you do explain, use 1–2 sentences max. Use analogies to physical things.
+
+4. **When they're stuck, fix it first, explain after.** Detect frustration (short messages, repeated errors, "this doesn't work"). Fix silently. Show working result. Then briefly say what was wrong.
+
+5. **Make things look impressive by default.** Never generate ugly starter code. Use good typography, spacing, and color from the start. When in doubt, make it look like a real product, not a tutorial.
+
+6. **Never introduce complexity unless asked.** No folder restructuring, no design patterns, no state management libraries, no "you should really use X instead." Keep it simple until simple breaks.
+
+7. **Never enforce build order.** If they want to build page 3 before page 1, let them. If they want login after building 5 pages, accommodate without refactoring lectures.
+
+8. **No emoji or dashes in generated copy.** Never use emoji, em dash, or double dash (--) in any user-facing text, UI copy, headings, or content you generate. Use colons, commas, periods, or parentheses instead. The only exception is if the designer explicitly asks for emoji.
+
+## Language Rules
+
+- Database table = "spreadsheet"
+- Row = "entry" or "line"
+- Column/field = "column" (designers know spreadsheets)
+- Git branch = "a copy to try changes on without touching the original"
+- Git commit = "saving a snapshot with a note"
+- API = "a way for your app to talk to a service"
+- Server action = "code that runs when someone submits a form"
+- Environment variable = "a secret setting stored on the server, not in your code"
+- Deploy = "put it online so anyone with the link can see it"
+- Component = "a reusable piece of your page"
+- Route = "a page at a specific URL"
+
+## Default Stack (Web)
+
+When building a website or web app, default to:
+- **Framework:** Next.js (App Router)
+- **Styling:** Tailwind CSS
+- **Database + Auth + Storage:** Supabase
+- **Email:** Resend
+- **Deploy:** Vercel
+
+Don't mention these names unless the designer asks. Just use them.
+
+## Behavior Modes
+
+### Building (default)
+Handle UI construction and backend connections. Build ↔ connect loop without interruption. This is where the designer spends 80% of their time.
+
+### Checking (when user says "check it" / "is this ready")
+Switch to review mode. Do NOT edit files during checking. Run quick-check or before-you-ship skill. Report findings clearly, then switch back to building mode to fix anything.
+
+### Shipping (when user says "ship it" / "put it online")
+Run before-you-ship checklist first — this is non-negotiable even if the designer says "just ship it." Show what will go live. Ask for explicit confirmation. Deploy. Provide URL and undo instructions.
+
+## Skills
+
+When a task matches one of the skills below, read the full SKILL.md file from `skills/` and follow those instructions.
+
+| They say | Skill to read |
+|---|---|
+| "Save it" / "store it" / "remember it" | `skills/save-data/SKILL.md` |
+| "Login" / "sign in" / "only I can see" | `skills/add-login/SKILL.md` |
+| "Send email" / "notify me" | `skills/send-email/SKILL.md` |
+| "Upload" / "add a photo" | `skills/upload-file/SKILL.md` |
+| "Show me all the..." / "dashboard" | `skills/show-data/SKILL.md` |
+| "Make it look better" / "it looks boring" | `skills/make-it-wow/SKILL.md` |
+| "Set up a design system" / "set up tokens" | `skills/design-system/SKILL.md` |
+| "Make it look like [url]" / "grab the design" | `skills/generate-design-md/SKILL.md` |
+| "Ship it" / "put it online" | `skills/before-you-ship/SKILL.md` |
+| "Check it" / "is this ready?" | `skills/quick-check/SKILL.md` |
+| "This doesn't work" / "ugh" / "stuck" | `skills/unstuck/SKILL.md` |
+| "Build a page" / "landing page" / "form" | `skills/build-page/SKILL.md` |
+| "What does that mean?" / "I don't understand" | `skills/noob-mode/SKILL.md` |
+| "I want to build..." / "new project" | `skills/what-am-i-building/SKILL.md` |
+| "Make an app" / "iPhone" / "Android" | `skills/platforms/mobile-expo/SKILL.md` |
+| "Figma plugin" / "extend Figma" | `skills/platforms/figma-plugin/SKILL.md` |
+| Building a web project | `skills/platforms/web-nextjs/SKILL.md` |

package/template/_cursor/rules/make-it-wow.mdc

@@ -0,0 +1,9 @@
+---
+description: Instant visual polish. Makes site look premium with animations, better typography, modern effects. Triggers: make it look better, polish, make it premium, it looks boring, make it pop, spice it up, wow, make it beautiful.
+globs: 
+alwaysApply: false
+---
+
+# Make It Wow
+
+Read and follow the full instructions in `skills/make-it-wow/SKILL.md`.

package/template/_cursor/rules/noob-mode.mdc

@@ -0,0 +1,9 @@
+---
+description: Plain-English translation layer. Explains technical things simply. Triggers: what does that mean, I don't understand, confused, explain everything, noob mode, what is that, explain like I'm five.
+globs: 
+alwaysApply: false
+---
+
+# Noob Mode
+
+Read and follow the full instructions in `skills/noob-mode/SKILL.md`.

package/template/_cursor/rules/platform-figma-plugin.mdc

@@ -0,0 +1,9 @@
+---
+description: Figma Plugin API and TypeScript conventions for Figma plugin development. Auto-applied when working on Figma plugin files.
+globs: ["manifest.json", "src/plugin/**", "src/ui/**"]
+alwaysApply: false
+---
+
+# Figma Plugin Platform
+
+Read and follow the full instructions in `skills/platforms/figma-plugin/SKILL.md`.

package/template/_cursor/rules/platform-mobile-expo.mdc

@@ -0,0 +1,9 @@
+---
+description: React Native, Expo, Supabase, and EAS conventions for mobile app projects. Auto-applied when working on mobile app files.
+globs: ["app/**/*.native.*", "expo/**", "app.json"]
+alwaysApply: false
+---
+
+# Mobile (Expo) Platform
+
+Read and follow the full instructions in `skills/platforms/mobile-expo/SKILL.md`.

package/template/_cursor/rules/platform-web-nextjs.mdc

@@ -0,0 +1,9 @@
+---
+description: Next.js App Router, Tailwind CSS, Supabase, and Vercel conventions for web projects. Auto-applied when working on web project files.
+globs: ["app/**", "pages/**", "components/**", "next.config.*"]
+alwaysApply: false
+---
+
+# Web (Next.js) Platform
+
+Read and follow the full instructions in `skills/platforms/web-nextjs/SKILL.md`.

package/template/_cursor/rules/quick-check.mdc

@@ -0,0 +1,9 @@
+---
+description: Fast 4-item quality check. Triggers: check it, is this ready, does it look ok, quick check, any issues, look for problems, is it broken, test it.
+globs: 
+alwaysApply: false
+---
+
+# Quick Check
+
+Read and follow the full instructions in `skills/quick-check/SKILL.md`.

package/template/_cursor/rules/save-data.mdc

@@ -0,0 +1,9 @@
+---
+description: Saves form data to a database. Triggers: save, store, persist, remember, keep the data, save to database, save the form, store submissions, save what they type, save entries, record, track.
+globs: 
+alwaysApply: false
+---
+
+# Save Data
+
+Read and follow the full instructions in `skills/save-data/SKILL.md`.

package/template/_cursor/rules/send-email.mdc

@@ -0,0 +1,9 @@
+---
+description: Sends emails from your app. Triggers: send email, email notification, notify me, confirmation email, alert me, welcome email, email when someone, receipt email.
+globs: 
+alwaysApply: false
+---
+
+# Send Email
+
+Read and follow the full instructions in `skills/send-email/SKILL.md`.

package/template/_cursor/rules/show-data.mdc

@@ -0,0 +1,9 @@
+---
+description: Displays saved data as lists, tables, cards, or dashboards. Triggers: show me all the, list all, dashboard, display, table of, view submissions, show entries, show data.
+globs: 
+alwaysApply: false
+---
+
+# Show Data
+
+Read and follow the full instructions in `skills/show-data/SKILL.md`.

package/template/_cursor/rules/unstuck.mdc

@@ -0,0 +1,9 @@
+---
+description: Detects frustration and fixes problems fast. Triggers: stuck, this doesn't work, broken, help, ugh, what the hell, why, not working, it broke, error, can't figure out, I give up, frustrated, nothing happens, blank page, won't load, keeps crashing.
+globs: 
+alwaysApply: false
+---
+
+# Unstuck
+
+Read and follow the full instructions in `skills/unstuck/SKILL.md`.

package/template/_cursor/rules/upload-file.mdc

@@ -0,0 +1,9 @@
+---
+description: Handles file and image uploads. Triggers: upload, add a photo, file upload, image upload, drag and drop, profile picture, attach file, add images.
+globs: 
+alwaysApply: false
+---
+
+# Upload File
+
+Read and follow the full instructions in `skills/upload-file/SKILL.md`.

package/template/_cursor/rules/what-am-i-building.mdc

@@ -0,0 +1,9 @@
+---
+description: Figures out what you're building and sets up the project. Triggers: I want to build, new project, I have an idea, I need a website, I need an app, start a project, what should I build.
+globs: 
+alwaysApply: false
+---
+
+# What Am I Building
+
+Read and follow the full instructions in `skills/what-am-i-building/SKILL.md`.

package/template/skills/generate-design-md/SKILL.md

@@ -15,7 +15,7 @@ Takes a website URL and produces a complete DESIGN.md file -- a plain-text desig
 4. Analyze the visual atmosphere and design philosophy
 5. Detect the page structure (sections, grids, layout patterns)
 6. Generate three files:
-   - `DESIGN.md` -- the complete design system (8 sections)
+   - `DESIGN.md` -- the complete design system (9 sections)
    - Tailwind config extension -- tokens mapped to utility classes
    - CSS variables -- tokens as custom properties in globals.css
 7. Drop them in the project
@@ -72,12 +72,56 @@ Pull these from ALL collected sources (external CSS + inline styles + style bloc
 | Fonts | `font-family`, `@font-face`, Google Fonts URL params (`?family=Inter:wght@300;400;700`), Typekit kit IDs |
 | Type scale | `font-size`, `font-weight`, `line-height`, `letter-spacing` -- collect ALL unique values and sort |
 | Spacing | `padding`, `margin`, `gap` -- collect unique values, find the base unit (most common divisor) |
-| Radii | `border-radius` -- collect all unique values across components |
+| Radii | `border-radius` -- collect per-component (see Radius Precision below) |
 | Shadows | `box-shadow` -- capture full declarations including multi-layer stacks |
 | Borders | `border` shorthand and individual properties |
 | Transitions | `transition`, `animation`, `@keyframes` declarations |
 | Breakpoints | `@media` queries -- extract all width breakpoints |
 
+#### Radius Precision
+
+Border-radius is the token most often wrong because CSS text alone is ambiguous: variable references (`var(--radius)`), utility classes (`rounded-xl`), and shorthand (`8px 8px 0 0`) all hide the actual computed value. Use these techniques in order of reliability:
+
+**1. Resolve CSS variables.** If you see `border-radius: var(--radius-md)`, find the variable definition in `:root` or the CSS variable block and substitute the literal value. Chain through aliases: `--radius-md: var(--radius-base)` means you need `--radius-base` too.
+
+**2. Map utility classes.** If the HTML uses Tailwind or a utility-first framework, map class names to known values:
+| Class | Value |
+|-------|-------|
+| `rounded-none` | 0px |
+| `rounded-sm` | 2px (0.125rem) |
+| `rounded` | 4px (0.25rem) |
+| `rounded-md` | 6px (0.375rem) |
+| `rounded-lg` | 8px (0.5rem) |
+| `rounded-xl` | 12px (0.75rem) |
+| `rounded-2xl` | 16px (1rem) |
+| `rounded-3xl` | 24px (1.5rem) |
+| `rounded-full` | 9999px |
+
+If the site uses a custom Tailwind config the values may differ. Check CSS custom properties for overrides like `--radius: 0.625rem` (Shadcn/ui pattern).
+
+**3. Group by component.** Different components use different radii. Always record WHICH component a radius belongs to:
+- Buttons: typically `radius-sm` or `radius-md`
+- Cards / panels: typically `radius-md` or `radius-lg`
+- Inputs: typically matches button radius
+- Modals / sheets: typically `radius-lg` or `radius-xl`
+- Badges / pills: often `radius-full` (9999px)
+- Avatars: `radius-full` for circles, `radius-md` for rounded squares
+- Dropdowns / menus: typically `radius-md`
+- Tooltips: typically `radius-sm`
+
+When two components use the same numeric value, that's an intentional design system choice. Note it. When they differ by component, that IS the radius scale.
+
+**4. DevTools precision pass (optional).** If the fetched CSS is heavily variable-based, JS-rendered, or the radius values look ambiguous, ask the designer to run the DevTools extractor script in their browser:
+1. Open the target site in Chrome/Safari/Firefox
+2. Open DevTools console (right-click > Inspect > Console)
+3. Paste the extractor script (available at the project's `public/extract.js`)
+4. The script reads `getComputedStyle()` on every visible element and groups radii by component type (button, card, input, modal, badge, etc.)
+5. Result is copied to clipboard as JSON
+
+The `radiusByComponent` object in the script output gives the exact computed radius for each component type, with occurrence counts. This is ground truth, since it reads the browser's final rendered values after all CSS variable resolution, utility class application, and specificity battles.
+
+When the designer pastes this JSON, use `radiusByComponent` as the authoritative source for the Border Radius table in DESIGN.md. It overrides any values inferred from CSS text.
+
 ### Step 3: Verify, don't guess
 
 **Extracted** = you found the exact value in HTML, CSS, or inline styles. Mark these with confidence.
@@ -103,7 +147,64 @@ From the raw tokens, identify:
 - **Spacing rhythm**: Is it 4px-based? 8px-based? What's the scale?
 - **Component signatures**: How do buttons look? Cards? Inputs? Navigation?
 - **Shadow philosophy**: Flat? Subtle elevation? Heavy depth? Shadow-as-border?
-- **Shape language**: Sharp corners? Rounded? Pills? Mixed?
+- **Shape language**: Map each component type to its specific radius. Are buttons and inputs the same? Are cards larger? Any use of asymmetric radii (e.g. `8px 8px 0 0`)? Does the radius scale follow a pattern (e.g. 4/8/12/16)?
+
+#### Font Classification
+
+Separate extracted fonts into three buckets:
+- **Body font**: the font used on most text. Look for names containing "Text", "Body", or "Sans" (without "Display").
+- **Heading font**: used for titles. Look for names containing "Display", "Headline", "Title".
+- **Mono font**: for code/data. Names containing "Mono", "Code", "Consol", "Courier".
+
+**Filter out icon fonts** before assigning roles. Skip any font with "Awesome", "Material", "Icon", "Symbol", "Glyph", "Icomoon", "Feather", "Ionicons", "Remixicon", "Lucide", or "Bootstrap Icon" in the name. These are icon fonts, not text fonts.
+
+If the site uses only one text font for everything, note it as both body and heading. If there are two distinct non-icon fonts, the more common one is body, the other is heading.
+
+#### Accent Color Detection
+
+The accent color must be intentional, not a stray focus ring or outline:
+- **Saturation > 40%** required. Low-saturation colors are grays, not brand colors.
+- **Source must be text or background**, not border. Border colors often inherit browser defaults (blue focus rings, outline colors).
+- **Monochrome sites** (Uber, Nike) have no accent. The primary button is dark/black, not colored. Don't force an accent when there isn't one.
+- **Check CSS variables**: `--accent`, `--brand`, `--color-primary`, `--color-button-primary` often hold the brand color.
+
+#### Button Detection
+
+Sites use different button styles. Detect in this priority:
+1. **Chromatic buttons**: colored background (saturation > 40%). This is the accent/CTA.
+2. **Dark/black buttons**: common on monochrome sites (Nike, Puma, Uber, Vercel). Brightness < 60.
+3. **Any visible button**: non-transparent, non-white background.
+
+**Skip utility buttons** when looking for the primary CTA: "Skip to content", "Search", "Close", "Menu", "My account", "next/prev".
+
+#### Card Style Detection
+
+Cards come in distinct patterns. Detect which one the site uses:
+- **Shadow cards**: no border, `box-shadow` at rest. Common on SaaS sites (Stripe, Linear).
+- **Bordered cards**: `border` visible, no shadow at rest. Shadow appears on hover. Common on e-commerce (Airbnb).
+- **No-container cards**: just a rounded image with text below, no wrapping element. No border, no shadow, no background. Common on media/marketplace sites (Airbnb listings, Mobbin).
+- **Inset cards**: `box-shadow: inset` as border technique (Vercel).
+
+Card radius cap: anything over 32px is likely a search bar or hero element, not a card. Default to 12px.
+
+#### Dropdown Detection
+
+Nav dropdown menus are the best source for dropdown styling because every site has one and they're styled consistently. Detection priority:
+1. **Nav menu panels**: look for `[role="menu"]`, `[role="listbox"]`, or class patterns (`dropdown`, `menu-panel`, `submenu`, `popover`, `flyout`, `mega-menu`) inside `<nav>` or `<header>`.
+2. **Hidden panels**: most dropdowns are `display:none` until hover. Their styles are still readable via `getComputedStyle()`.
+3. **Page-wide fallback**: search the whole page for the same selectors.
+
+Dropdown radius cap: max 24px. Dropdowns are tight UI, never pill-shaped.
+
+#### Pill Detection
+
+Only values >= 999px count as pills, NOT percentage values like `50%` or `100%`. The value `50%` creates circles (avatars, icons), not pills. The value `border-radius: 9999px` or `border-radius: 1600px` creates pills.
+
+When a site uses pills AND no explicit button radius is detected, assume buttons are pills too.
+
+#### Bot Protection
+
+If the headless browser lands on a challenge page instead of the real site, detect it by checking the page title or first heading for phrases like: "just a moment", "checking your browser", "security check", "access denied", "attention required", "what happened", "please verify", "captcha". Return a clear error telling the user to use the DevTools paste method instead.
 
 ### Step 5: Interpret the Atmosphere
 
@@ -118,7 +219,7 @@ Write this as a short, opinionated paragraph -- not a list of CSS values.
 
 ## Output Format
 
-The DESIGN.md follows an 8-section structure optimized for AI agents. Every section earns its place -- no redundancy, no prose padding.
+The DESIGN.md follows a 9-section structure optimized for AI agents. Every section earns its place -- no redundancy, no prose padding.
 
 ```markdown
 # DESIGN.md -- [Site Name]
@@ -199,12 +300,14 @@ priority-rule: external-css > style-blocks > inline-style > known
 - Section gap: [value]
 
 ### Border Radius
-| Token | Value | Used on |
-|-------|-------|---------|
-| `radius-sm` | [px] | [inputs, inline code] |
-| `radius-md` | [px] | [buttons, cards] |
-| `radius-lg` | [px] | [modals, hero cards] |
-| `radius-full` | [px/9999px] | [badges, pills, avatars] |
+| Token | Value | Used on | Source |
+|-------|-------|---------|--------|
+| `radius-sm` | [px] | [inputs, inline code, tooltips] | [extracted/variable-resolved/class-mapped/devtools] |
+| `radius-md` | [px] | [buttons, cards, dropdowns] | |
+| `radius-lg` | [px] | [modals, hero cards, large panels] | |
+| `radius-full` | [px/9999px] | [badges, pills, avatars] | |
+
+[Map every component to its radius token. If buttons use `radius-md` and cards also use `radius-md`, say so. If they differ, that IS the scale]
 
 ## 5. Depth & Motion
 
@@ -226,7 +329,53 @@ priority-rule: external-css > style-blocks > inline-style > known
 | `easing` | [curve] | Default easing function |
 [Note any distinctive motion patterns: staggered entrance, parallax, spring physics, scroll-triggered]
 
-## 6. Components
+## 6. Page Structure
+
+### Header
+```
+[ element placement diagram ]
+height: [value] | position: [sticky/fixed/absolute/static] | bg: [value] | [backdrop-blur if present]
+```
+
+### Page Flow
+
+The page has [N] sections in this order:
+
+**1. [Section Name]** [note if section has a tinted/dark background]
+- Heading: [word count, size from type scale, alignment]
+- Subheading/label: [position relative to heading (above/below), style (uppercase, small, etc.)]
+- Body: [sentence count, approximate word count, alignment]
+- CTA: [button count, button labels pattern, style variants used]
+- Media: [image/video/illustration placement relative to text]
+- Layout: [stacked/split/grid], [alignment], max-width: [value if constrained]
+- Card pattern: [describe what's inside vs outside the card -- e.g. "image inside, text below"]
+- Item count: [how many cards/items in this section]
+
+**2. [Section Name]**
+[Same structure. Include every section on the page.]
+
+[Continue for ALL sections...]
+
+### Footer
+```
+[bg color/style]
+[ element placement diagram ]
+[column count, link count, content summary]
+```
+
+### Layout Patterns
+- Content alignment: [centered / left-aligned / mixed -- note which sections differ]
+- Content max-width: [value for text-heavy sections like hero, CTA]
+- Grid columns: [list each grid and its column count, e.g. "features: 3-col, pricing: 3-col, testimonials: 2-col"]
+- Grid responsive behavior: [what column count becomes on mobile]
+- Card gaps: [value]
+- Section vertical padding: [value or range]
+- Section backgrounds: [which sections break from the default bg, and what they use]
+- Heading hierarchy: [which type scale role each section heading uses -- e.g. "all section headings use H1 (56px) except component preview which uses H2 (32px)"]
+
+[Detect from DOM tree -- semantic elements (`<nav>`, `<header>`, `<section>`, `<footer>`), grid/flex containers, column counts, heading hierarchy, `text-align`, `max-width` on content wrappers.]
+
+## 7. Components
 
 ### Buttons
 | Property | Primary | Secondary | Ghost |
@@ -243,36 +392,89 @@ priority-rule: external-css > style-blocks > inline-style > known
 | Hover | [specific CSS changes] | [specific CSS changes] |
 | Focus | [focus ring value] | [focus ring value] |
 
-### Cards
+### Inputs
+| Property | Value |
+|----------|-------|
+| border | `[val]` |
+| radius | `[val]` |
+| padding | `[val]` |
+| focus | `[val]` |
+| error | [styling] |
+| label | [placement and style] |
+
+### Dropdowns
 | Property | Value |
 |----------|-------|
 | background | `[val]` |
 | border | `[val]` |
 | radius | `[val]` |
 | shadow | `[val]` |
-| padding | `[val]` |
-| hover | [behavior] |
+| max-height | `[val]` |
+| item-padding | `[val]` |
+| item-hover | `[val]` |
+| item-radius | `[val]` |
+| separator | `[val]` |
+| animation | [enter/exit behavior] |
 
-### Inputs
+### Cards
 | Property | Value |
 |----------|-------|
+| background | `[val]` |
 | border | `[val]` |
 | radius | `[val]` |
+| shadow | `[val]` |
 | padding | `[val]` |
-| focus | `[val]` |
-| error | [styling] |
-| label | [placement and style] |
+| hover | [behavior] |
 
 ### Navigation
 [Structure, font treatment, active indicator, sticky behavior]
 
+### Links
+| Property | Value |
+|----------|-------|
+| color | `[val]` |
+| underline | [always / hover-only / none] |
+| hover | [color change, underline, opacity] |
+| visited | `[val]` (omit if same as default) |
+
+### Badges / Tags
+| Property | Value |
+|----------|-------|
+| background | `[val]` |
+| color | `[val]` |
+| padding | `[val]` |
+| radius | `[val]` |
+| font-size | `[val]` |
+| font-weight | `[val]` |
+| variants | [list color variants if present: success, warning, danger, neutral] |
+
+### Tabs
+| Property | Value |
+|----------|-------|
+| active-indicator | [underline / background / border -- describe style] |
+| active-color | `[val]` |
+| inactive-color | `[val]` |
+| padding | `[val]` |
+| gap | `[val]` |
+
+### Modals / Dialogs
+| Property | Value |
+|----------|-------|
+| backdrop | `[val]` (e.g. rgba overlay, blur) |
+| background | `[val]` |
+| radius | `[val]` |
+| shadow | `[val]` |
+| padding | `[val]` |
+| max-width | `[val]` |
+| animation | [enter/exit behavior] |
+
 ### Icons (if identifiable)
 [Style: line/filled/duo-tone, stroke weight, size grid, corner style]
 
 ### Signature Patterns
 [1-3 components unique to this site. The things someone would point at and say "that looks like [site name]." e.g. Vercel's workflow pipeline, Stripe's gradient cards, Linear's command palette.]
 
-## 7. States
+## 8. States
 
 | State | Treatment |
 |-------|-----------|
@@ -284,7 +486,7 @@ priority-rule: external-css > style-blocks > inline-style > known
 | Empty | [How empty states are styled -- illustration, muted text, CTA] |
 | Error | [Color, border, icon, message placement] |
 
-## 8. Rules
+## 9. Rules
 
 ### Do
 - [6-8 specific, actionable rules WITH values]
@@ -410,31 +612,6 @@ Add to `globals.css` (or the project's main CSS file):
 
 If the file already has `:root` variables, merge without overwriting.
 
-### 3. Page Structure (if detectable)
-
-Analyze the reference site's HTML structure and add a `## Page Structure` section at the end of DESIGN.md:
-
-```markdown
-## Page Structure
-
-Detected layout pattern from [site]:
-
-1. **Nav:** Sticky header, logo left, links center, CTA right
-2. **Hero:** Full-width, large heading centered, subtitle below, 2 buttons
-3. **Metrics:** 4-column stat grid with large numbers
-4. **Features:** 3-column card grid, icon + title + description per card
-5. **Testimonials:** 2-column quote cards with avatar + company
-6. **CTA:** Centered heading + button, full-width section
-7. **Footer:** Logo, link columns, copyright
-
-Grid patterns:
-- Feature grids: 3 columns on desktop, 1 on mobile
-- Card gaps: 16-24px
-- Section padding: 80-96px vertical
-```
-
-Detect this from the DOM tree -- look at semantic elements (`<nav>`, `<header>`, `<section>`, `<footer>`), grid/flex containers, column counts, and heading hierarchy. This gives the build-page skill a blueprint when the designer says "build me a landing page like that."
-
 ### After creating all files, say:
 - "Your design reference is ready. Tailwind config and CSS variables are set up. Any page you build now follows [site name]'s style."
 
@@ -442,7 +619,7 @@ Do not explain every section. The designer doesn't need a walkthrough.
 
 ## What Not To Do
 
-- Do not ask which sections to include -- generate all 8
+- Do not ask which sections to include -- generate all 9
 - Do not generate a partial file and ask if they want more
 - Do not copy copyrighted content (logos, illustrations, copy text) -- only extract visual tokens
 - Do not require any tools beyond web fetching -- no browser automation, no Figma, no screenshots