vibe-ship-it 1.0.0

package/template/skills/platforms/web-nextjs/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: web-nextjs
+description: "Next.js + Tailwind + Supabase + Vercel conventions. Loaded automatically when building a web project."
+---
+
+# Web Platform: Next.js
+
+The default web stack. Next.js App Router + Tailwind CSS + Supabase + Vercel.
+
+## Project Structure
+
+Explain to the designer as:
+> "Your project is organized into folders. Think of each folder as a room with a specific purpose."
+
+```
+src/
+  app/                    ← Pages (each folder = a page on your site)
+    page.tsx              ← Home page (yourdomain.com/)
+    layout.tsx            ← The wrapper around every page (nav, footer)
+    about/
+      page.tsx            ← About page (yourdomain.com/about)
+    contact/
+      page.tsx            ← Contact page (yourdomain.com/contact)
+    dashboard/
+      page.tsx            ← Dashboard (yourdomain.com/dashboard)
+    login/
+      page.tsx            ← Login page (yourdomain.com/login)
+    actions.ts            ← Server actions (code that saves data)
+  components/             ← Reusable pieces (navigation, footer, cards)
+  utils/
+    supabase/
+      server.ts           ← Server-side database connection
+      client.ts           ← Browser-side database connection
+  middleware.ts           ← Page protection (bouncer for private pages)
+
+public/                   ← Static files (images, favicon)
+.env.local                ← Secret settings (database keys, API keys)
+```
+
+## Key Conventions
+
+### Server vs Client Components
+
+Don't explain "server components" and "client components" in those terms. Say:
+
+- **Default (server):** "This code runs on the server before the page is sent to the visitor. Good for loading data from the database."
+- **`'use client'`:** "This code runs in the visitor's browser. Needed when things are interactive — forms, buttons that do stuff, anything that changes on screen."
+
+Rule of thumb:
+- Page shows data from database → server component (default, no directive)
+- Page has interactive elements (forms, modals, toggles) → add `'use client'` at the top
+
+### Server Actions
+
+Explain as: "Code that runs when someone submits a form."
+
+```typescript
+'use server'
+
+export async function doSomething(formData: FormData) {
+  // This runs on the server, not in the visitor's browser
+  // Safe to access the database here
+}
+```
+
+Connect to a form:
+```tsx
+<form action={doSomething}>
+```
+
+### Routing
+
+- Each folder in `app/` = a page
+- `page.tsx` = what shows at that URL
+- `layout.tsx` = wrapper (navigation, footer) that stays the same across pages
+- `loading.tsx` = what shows while the page is loading (optional)
+- `error.tsx` = what shows if something goes wrong (optional)
+
+### Styling (Tailwind)
+
+Don't explain Tailwind utility names. Just use them. If they ask:
+> "Tailwind uses short class names instead of writing CSS. `text-lg` means larger text, `bg-blue-500` means blue background. You don't need to memorize these — I'll pick the right ones."
+
+### Images
+
+Use Next.js Image component for optimization:
+```tsx
+import Image from 'next/image'
+
+<Image
+  src="/photo.jpg"
+  alt="Description"
+  width={800}
+  height={600}
+  className="rounded-lg"
+/>
+```
+
+For external images (Supabase Storage, Unsplash), add the domain to `next.config.ts`:
+```typescript
+const nextConfig = {
+  images: {
+    remotePatterns: [
+      { hostname: '*.supabase.co' },
+    ],
+  },
+}
+```
+
+### Environment Variables
+
+`.env.local` — local development only, never committed to git:
+```
+NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
+NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
+RESEND_API_KEY=re_xxx
+```
+
+- `NEXT_PUBLIC_` prefix = accessible in browser code
+- No prefix = server-only (for secrets like API keys)
+
+When deploying, these must be set on Vercel too.
+
+## Common Commands
+
+| Command | What it does |
+|---|---|
+| `npm run dev` | Start the development server (preview in browser) |
+| `npm run build` | Build for production (check for errors) |
+| `npx vercel` | Preview deployment |
+| `npx vercel --prod` | Production deployment |
+
+## Packages to Install as Needed
+
+| When | Package | Install |
+|---|---|---|
+| Database/Auth/Storage | Supabase | `npm install @supabase/supabase-js @supabase/ssr` |
+| Animations | Framer Motion | `npm install framer-motion` |
+| Email | Resend | `npm install resend` |
+| Icons | Lucide React | `npm install lucide-react` |
+| Date formatting | date-fns | `npm install date-fns` |
+
+Don't pre-install everything. Install when first needed.
+
+## Supabase Setup (One Time)
+
+1. Go to supabase.com and create a free project
+2. Go to Settings → API
+3. Copy the URL and anon key
+4. Create `.env.local` with those values
+
+> "You need a free Supabase account — that's where your data, logins, and file uploads live. Takes 2 minutes to set up."
+
+## Vercel Deployment
+
+1. `npx vercel` (first time: link to Vercel account)
+2. Set environment variables on Vercel dashboard
+3. `npx vercel --prod` for production
+
+> "When you want to put it online, I'll run one command. First time it'll ask you to connect your Vercel account — just follow the link."

package/template/skills/platforms/web-nextjs/references/tailwind-shortcuts.md

@@ -0,0 +1,97 @@
+# Tailwind CSS Quick Reference
+
+Common patterns for designers. Organized by what you want to achieve, not by CSS property name.
+
+## Spacing
+
+| Want | Class | What it does |
+|---|---|---|
+| Space between sections | `space-y-4` / `space-y-8` | Vertical gap between children |
+| Space inside a box | `p-4` / `p-8` / `px-4 py-8` | Padding (inside cushion) |
+| Space outside a box | `m-4` / `mx-auto` | Margin (outside spacing) |
+| Page side margins | `px-4 md:px-8` | Horizontal padding, wider on desktop |
+| Center content | `max-w-7xl mx-auto` | Max width + auto horizontal margins |
+| Section breathing room | `py-16 md:py-24` | Generous vertical padding |
+
+## Typography
+
+| Want | Class |
+|---|---|
+| Giant headline | `text-5xl md:text-7xl font-bold tracking-tight` |
+| Section heading | `text-3xl font-semibold` |
+| Subheading | `text-xl font-medium text-gray-600` |
+| Body text | `text-base leading-relaxed` |
+| Large body | `text-lg leading-relaxed` |
+| Small/caption | `text-sm text-gray-500` |
+| Light text | `text-gray-400` |
+| Bold | `font-bold` or `font-semibold` |
+
+## Layout
+
+| Want | Class |
+|---|---|
+| Side by side (2 cols) | `grid grid-cols-1 md:grid-cols-2 gap-8` |
+| Three columns | `grid grid-cols-1 md:grid-cols-3 gap-6` |
+| Flexbox row | `flex items-center gap-4` |
+| Flexbox column | `flex flex-col gap-4` |
+| Full screen height | `min-h-screen` |
+| Full width | `w-full` |
+| Centered everything | `flex items-center justify-center min-h-screen` |
+| Sticky header | `sticky top-0 z-50 bg-white/80 backdrop-blur` |
+
+## Colors
+
+| Want | Class |
+|---|---|
+| Background | `bg-white` / `bg-gray-50` / `bg-black` |
+| Text color | `text-gray-900` / `text-white` / `text-blue-600` |
+| Accent background | `bg-blue-500` / `bg-indigo-600` (adjust hue) |
+| Subtle card bg | `bg-gray-50` or `bg-white` |
+| Dark section | `bg-gray-900 text-white` |
+
+## Cards & Containers
+
+| Want | Class |
+|---|---|
+| Basic card | `bg-white rounded-xl p-6 shadow-sm border` |
+| Elevated card | `bg-white rounded-2xl p-8 shadow-lg` |
+| Glass effect | `bg-white/80 backdrop-blur rounded-xl border border-white/20` |
+| Outlined card | `border rounded-xl p-6` |
+
+## Buttons
+
+| Want | Class |
+|---|---|
+| Primary | `bg-black text-white px-6 py-2 rounded-lg hover:bg-gray-800 transition-colors` |
+| Secondary | `border px-6 py-2 rounded-lg hover:bg-gray-50 transition-colors` |
+| With hover lift | Add `hover:scale-[1.02] hover:shadow-lg transition-all` |
+| Disabled | Add `disabled:opacity-50 disabled:cursor-not-allowed` |
+
+## Images
+
+| Want | Class |
+|---|---|
+| Rounded | `rounded-lg` or `rounded-2xl` |
+| Circle (profile) | `rounded-full w-12 h-12 object-cover` |
+| Cover container | `w-full h-64 object-cover` |
+| Aspect ratio | `aspect-square` / `aspect-video` / `aspect-[4/3]` |
+
+## Responsive
+
+All classes can be prefixed for different screen sizes:
+- No prefix = mobile (default)
+- `md:` = tablet and up (768px+)
+- `lg:` = desktop (1024px+)
+
+Example: `text-2xl md:text-4xl lg:text-6xl` — heading grows on bigger screens.
+
+## Animation
+
+| Want | Class |
+|---|---|
+| Smooth transitions | `transition-all duration-300` |
+| Hover scale | `hover:scale-105 transition-transform` |
+| Hover lift | `hover:-translate-y-1 hover:shadow-xl transition-all` |
+| Fade in (custom) | See make-it-wow skill |
+| Spin | `animate-spin` (for loading indicators) |
+| Pulse | `animate-pulse` (for skeleton loading) |

package/template/skills/quick-check/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: quick-check
+description: "Fast 3-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'."
+---
+
+# Quick Check
+
+The fast quality check. 3 items. Takes under a minute. Good enough for "can I show my friend?"
+
+## The 3 Checks
+
+### 1. Does It Load?
+
+Open every page in the browser. Check:
+- No blank/white pages
+- No console errors (open dev tools → Console)
+- No visible "Error" or "500" or "404" on the page
+- Content actually renders (not just a loading spinner forever)
+
+✅ Pass: all pages show content
+❌ Fail: any page shows an error, stays blank, or shows a crash screen
+
+### 2. Does The Main Thing Work?
+
+Identify the PRIMARY user action (form submit, button click, navigation flow) and do it:
+- If there's a form → fill it out and submit. Does it save? Does it show confirmation?
+- If there's a CTA button → click it. Does it go somewhere?
+- If there's a login → try logging in. Does it work?
+- If it's a portfolio → do images load? Can you navigate between pages?
+
+✅ Pass: the main action completes successfully
+❌ Fail: the main action breaks, shows an error, or does nothing
+
+### 3. Mobile?
+
+Resize the browser to 375px width (iPhone SE). Check:
+- Text is readable (not overflowing or cut off)
+- Navigation is usable (hamburger menu works, or links are tappable)
+- No horizontal scroll
+- Content isn't overlapping
+
+✅ Pass: looks usable on a phone
+❌ Fail: layout is broken, text overflows, navigation is unusable
+
+## Report Format
+
+### All Good
+```
+✅ Quick check — looks good.
+
+1. ✅ All pages load fine
+2. ✅ Form submits and saves correctly
+3. ✅ Looks good on mobile
+
+Ready to show someone! 
+```
+
+### Issues Found
+```
+Quick check — found 1 thing:
+
+1. ✅ All pages load fine
+2. ✅ Form submits correctly
+3. ⚠️ Mobile: the headline text is too wide and gets cut off on phones
+
+This won't break anything, but it'll look off on smaller screens. 
+Want me to fix it?
+```
+
+### Serious Issue
+```
+Quick check — found a problem:
+
+1. ✅ All pages load
+2. ❌ The contact form submits but nothing happens — no confirmation, 
+   no data saved. The server action might not be connected.
+3. ✅ Mobile looks fine
+
+This means the main feature doesn't work yet. 
+Want me to fix it?
+```
+
+## Rules
+
+- NEVER skip a check
+- NEVER sugarcoat a broken main feature — be direct
+- DO minimize minor issues — "the footer spacing is 4px off" is not worth mentioning in a quick check
+- Always end with "Want me to fix it?" if issues are found
+- If everything passes, encourage: "Ready to show someone!" or "Looks good for a demo!"

package/template/skills/save-data/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: save-data
+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'."
+---
+
+# Save Data
+
+Makes forms actually save data. Handles the complete flow: create the database table, write the save function, connect it to the form, and test it.
+
+## The Spreadsheet Analogy
+
+Before creating anything, show the designer what their "spreadsheet" will look like:
+
+> "Here's what your data will look like — think of it as a spreadsheet:
+>
+> | name | email | message | submitted at |
+> |---|---|---|---|
+> | Jane Smith | jane@email.com | Hello! I'd like... | Apr 3, 2026 |
+> | Alex Kim | alex@email.com | Question about... | Apr 3, 2026 |
+>
+> Each time someone fills out the form, a new line gets added here."
+
+## Implementation Steps
+
+### Step 1: Create the Table
+
+Generate SQL for Supabase:
+
+```sql
+create table [table_name] (
+  id uuid default gen_random_uuid() primary key,
+  -- columns match the form fields
+  created_at timestamptz default now()
+);
+
+-- Enable Row Level Security
+alter table [table_name] enable row level security;
+
+-- Policy: anyone can insert (for public forms)
+create policy "Anyone can submit" on [table_name]
+  for insert with check (true);
+
+-- Policy: only authenticated users can read (for admin)
+create policy "Authenticated users can read" on [table_name]
+  for select using (auth.role() = 'authenticated');
+```
+
+Tell the designer:
+> "Go to your Supabase dashboard → SQL Editor → paste this and run it. That creates your spreadsheet."
+
+Or if Supabase CLI is set up, run it directly.
+
+### Step 2: Set Up Supabase Client
+
+If not already set up, create the Supabase client utilities:
+
+**`src/utils/supabase/server.ts`** — for server-side operations:
+```typescript
+import { createServerClient } from '@supabase/ssr'
+import { cookies } from 'next/headers'
+
+export async function createClient() {
+  const cookieStore = await cookies()
+  return createServerClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+    {
+      cookies: {
+        getAll() { return cookieStore.getAll() },
+        setAll(cookiesToSet) {
+          cookiesToSet.forEach(({ name, value, options }) =>
+            cookieStore.set(name, value, options)
+          )
+        },
+      },
+    }
+  )
+}
+```
+
+**`.env.local`** — environment variables:
+```
+NEXT_PUBLIC_SUPABASE_URL=your-project-url
+NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
+```
+
+Tell the designer:
+> "I need two settings from your Supabase dashboard — go to Settings → API and copy the URL and the anon key."
+
+### Step 3: Create the Server Action
+
+```typescript
+'use server'
+
+import { createClient } from '@/utils/supabase/server'
+
+export async function save[Name](formData: FormData) {
+  const supabase = await createClient()
+
+  const { error } = await supabase.from('[table_name]').insert({
+    // map form fields to columns
+  })
+
+  if (error) {
+    return { error: 'Something went wrong. Try again.' }
+  }
+
+  return { success: true }
+}
+```
+
+### Step 4: Connect to Form
+
+Add the action to the existing form:
+```tsx
+<form action={save[Name]}>
+  {/* existing fields */}
+  <button type="submit">Send</button>
+</form>
+```
+
+Add a success message:
+```tsx
+// Show confirmation after submit
+"Thanks! Your message was sent."
+```
+
+### Step 5: Test It
+
+> "Try filling out the form and clicking Send. Then check your Supabase dashboard — go to Table Editor → [table_name]. You should see your entry."
+
+## Platform Adaptations
+
+| Platform | Storage | Approach |
+|---|---|---|
+| Web (Next.js) | Supabase | Server actions + Supabase client (above) |
+| Mobile (Expo) | Supabase | Supabase JS client directly |
+| Prototype / quick test | localStorage | Just save to browser storage (no server needed) |
+| WordPress | WP REST API | Custom endpoint + database |
+
+## Multiple Forms
+
+If the project already has other saved data:
+- Reuse the existing Supabase client (don't create another one)
+- Create a new table for each distinct type of data
+- Create a new server action for each form
+
+## Common Issues
+
+| Problem | Fix |
+|---|---|
+| Form submits but no data appears | Check Supabase RLS policies — insert policy might be missing |
+| "Missing environment variable" | Check `.env.local` has the Supabase URL and key |
+| Data saves but page doesn't show confirmation | Add success state handling to the form |
+| Duplicate entries | Add a loading/disabled state to the submit button |

package/template/skills/send-email/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: send-email
+description: "Sends emails from your app. Triggers: 'send email', 'email notification', 'notify me', 'confirmation email', 'send a notification', 'email when', 'alert me', 'send message', 'email the user', 'welcome email', 'thank you email'."
+---
+
+# Send Email
+
+Sends emails when things happen — confirmations, notifications, welcome messages.
+
+## Default: Resend
+
+Simplest email API. Generous free tier (100 emails/day). Beautiful templates with React Email.
+
+### Step 1: Install
+
+```bash
+npm install resend
+```
+
+### Step 2: Get API Key
+
+> "Go to resend.com, create a free account, and copy your API key. I'll store it securely."
+
+Add to `.env.local`:
+```
+RESEND_API_KEY=re_your_api_key_here
+```
+
+### Step 3: Create Send Function
+
+`src/utils/email.ts`:
+```typescript
+import { Resend } from 'resend'
+
+const resend = new Resend(process.env.RESEND_API_KEY)
+
+export async function sendEmail({
+  to,
+  subject,
+  html,
+}: {
+  to: string
+  subject: string
+  html: string
+}) {
+  const { error } = await resend.emails.send({
+    from: 'Your App <onboarding@resend.dev>',
+    to,
+    subject,
+    html,
+  })
+
+  if (error) {
+    console.error('Email failed:', error)
+    return { success: false }
+  }
+
+  return { success: true }
+}
+```
+
+Note: `onboarding@resend.dev` is Resend's free testing address. For production, connect a custom domain in Resend dashboard.
+
+### Step 4: Connect to an Event
+
+Common patterns:
+
+**After form submission (notify the designer):**
+```typescript
+'use server'
+
+import { createClient } from '@/utils/supabase/server'
+import { sendEmail } from '@/utils/email'
+
+export async function saveContact(formData: FormData) {
+  const supabase = await createClient()
+  const name = formData.get('name') as string
+  const email = formData.get('email') as string
+  const message = formData.get('message') as string
+
+  // Save to database
+  await supabase.from('contacts').insert({ name, email, message })
+
+  // Notify you
+  await sendEmail({
+    to: 'you@youremail.com',
+    subject: `New message from ${name}`,
+    html: `
+      <h2>New contact form submission</h2>
+      <p><strong>From:</strong> ${name} (${email})</p>
+      <p><strong>Message:</strong></p>
+      <p>${message}</p>
+    `,
+  })
+
+  return { success: true }
+}
+```
+
+**Confirmation to the user:**
+```typescript
+// After saving, also email the person who submitted
+await sendEmail({
+  to: email,
+  subject: 'Thanks for reaching out!',
+  html: `
+    <h2>Got your message!</h2>
+    <p>Hi ${name}, thanks for getting in touch. 
+    I'll get back to you within 24 hours.</p>
+  `,
+})
+```
+
+### Step 5: Test It
+
+> "Submit your contact form. Check two things:
+> 1. You should get a notification email
+> 2. The person who submitted should get a confirmation
+> 
+> Note: With the free Resend account, emails might go to spam at first. That's normal for testing."
+
+## Email Templates
+
+Keep emails simple. Designers can style them later.
+
+**Minimal template:**
+```html
+<div style="font-family: sans-serif; max-width: 600px; margin: 0 auto; padding: 20px;">
+  <h2 style="color: #333;">Subject Here</h2>
+  <p style="color: #555; line-height: 1.6;">Content here.</p>
+  <hr style="border: none; border-top: 1px solid #eee; margin: 20px 0;" />
+  <p style="color: #999; font-size: 12px;">Sent from Your App</p>
+</div>
+```
+
+## Common Patterns
+
+| When | Email | To |
+|---|---|---|
+| Contact form submitted | "New message from [name]" | Designer (admin) |
+| Contact form submitted | "Thanks for reaching out!" | The visitor |
+| Booking created | "New booking: [date/time]" | Designer (admin) |
+| Booking created | "Your booking is confirmed" | The customer |
+| Order placed | "New order #[id]" | Designer (admin) |
+| Account created | "Welcome!" | New user |
+
+## Custom Domain (Production)
+
+For emails to not go to spam:
+1. Go to Resend dashboard → Domains
+2. Add your domain (e.g., yourbrand.com)
+3. Add the DNS records Resend gives you
+4. Update the `from` address: `'Your Name <hello@yourbrand.com>'`
+
+> "Right now emails come from a test address. When you're ready to go live, we'll connect your domain so emails come from you@yourbrand.com."
+
+## Common Issues
+
+| Problem | Fix |
+|---|---|
+| Email not received | Check spam folder. With free tier, emails often land in spam |
+| "API key invalid" | Check `.env.local` — the key should start with `re_` |
+| Email sends but looks ugly | Use the HTML template above instead of plain text |
+| Rate limited | Free tier is 100/day. Upgrade if needed |