@kennethsolomon/shipkit 3.1.0 → 3.3.0

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

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

package/skills/sk:mvp/references/landing-page.md

@@ -0,0 +1,236 @@
+# Landing Page — SaaS Section Patterns
+
+Structure and patterns for the mandatory MVP landing page.
+
+---
+
+## Required Sections (in order)
+
+Every landing page must include ALL of these sections. Do not skip any.
+
+### 1. Navbar
+
+```
+[Logo/Name]          [Features] [Pricing] [Waitlist]     [Join Waitlist →]
+```
+
+- Sticky at top with backdrop blur.
+- Logo or product name (text logo is fine — use display font).
+- 2-4 nav links that scroll to sections (anchor links).
+- CTA button on the right that scrolls to waitlist section.
+- Mobile: collapse to hamburger.
+
+### 2. Hero Section
+
+```
+┌─────────────────────────────────────────────────┐
+│                                                 │
+│        [small eyebrow badge or label]           │
+│                                                 │
+│     Big Bold Headline That Sells               │
+│     the Benefit, Not the Feature               │
+│                                                 │
+│     A subheadline that elaborates in 1-2        │
+│     sentences. Specific, not vague.             │
+│                                                 │
+│     [Primary CTA Button]  [Secondary Link]      │
+│                                                 │
+│     ┌─────────────────────────────────┐         │
+│     │   Hero visual / app preview /   │         │
+│     │   illustration / gradient box   │         │
+│     └─────────────────────────────────┘         │
+│                                                 │
+└─────────────────────────────────────────────────┘
+```
+
+- **Headline**: Benefit-driven ("Ship faster" not "Project management tool"). 5-10 words max.
+- **Subheadline**: Explain what it does and for whom. 1-2 sentences.
+- **CTA**: Action verb + outcome ("Join the waitlist", "Get early access", "Start free").
+- **Visual**: App screenshot mockup, abstract gradient, or SVG illustration. Never leave empty.
+- **Eyebrow**: Optional small badge above headline ("Now in beta", "For developers", "AI-powered").
+
+### 3. Social Proof Bar
+
+```
+Trusted by 500+ early adopters
+[Logo] [Logo] [Logo] [Logo] [Logo]
+```
+
+- Single line below hero.
+- Use placeholder company names/logos (styled as gray text or simple SVG shapes).
+- Alternatively: "Join 500+ people on the waitlist" with a count (fake but plausible).
+- Keep subtle — muted colors, small text.
+
+### 4. Features Grid
+
+```
+┌──────────┐ ┌──────────┐ ┌──────────┐
+│  🎯 Icon │ │  ⚡ Icon │ │  🔒 Icon │
+│  Title   │ │  Title   │ │  Title   │
+│  2-line  │ │  2-line  │ │  2-line  │
+│  desc    │ │  desc    │ │  desc    │
+└──────────┘ └──────────┘ └──────────┘
+```
+
+- 3-6 features in a grid (3 columns desktop, 1 mobile).
+- Each card: icon/emoji + title (3-5 words) + description (1-2 sentences).
+- Icons: use emoji or simple SVG. Heroicons or Lucide if the stack supports it.
+- Feature text must match the key features from Step 1.
+
+### 5. How It Works
+
+```
+Step 1              Step 2              Step 3
+  ①                   ②                   ③
+Sign up          Connect your         See results
+and set up       data source          in minutes
+your account     in one click
+```
+
+- 3 steps (rarely 4). Numbered or with icons.
+- Each step: number/icon + title + 1-sentence description.
+- Optional: connecting line or arrow between steps.
+- Explains the user journey from signup to value.
+
+### 6. Pricing
+
+```
+┌──────────┐  ┌──────────────┐  ┌──────────┐
+│  Free    │  │  Pro ⭐       │  │Enterprise│
+│  $0/mo   │  │  $29/mo      │  │  Custom  │
+│          │  │              │  │          │
+│  • 3 feat│  │  • All free  │  │  • All   │
+│  • Basic │  │  • 5 more    │  │  • Custom│
+│          │  │  • Priority  │  │  • SLA   │
+│ [Start]  │  │ [Get Pro]    │  │ [Contact]│
+└──────────┘  └──────────────┘  └──────────┘
+```
+
+- 2-3 tiers. Middle tier highlighted (border, scale, badge).
+- Prices should be fake but realistic for the product type.
+- Each tier: name, price, feature list (5-7 items), CTA button.
+- Free tier CTA → waitlist. Paid tier CTAs → waitlist (it's an MVP).
+- All buttons route to the waitlist since nothing is real yet.
+
+### 7. Testimonials
+
+```
+┌──────────────────────────────────┐
+│  "This changed how I work..."    │
+│                                  │
+│  [Avatar]  Jane Smith            │
+│            CTO, TechCo           │
+└──────────────────────────────────┘
+```
+
+- 2-3 testimonial cards. Carousel or grid.
+- Each: quote (1-3 sentences), name, role/company, avatar placeholder.
+- Generate realistic-sounding quotes that align with the product's value prop.
+- Avatars: use gradient circles with initials, or `ui-avatars.com` service.
+- Mark clearly in code comments that these are placeholder testimonials.
+
+### 8. Waitlist / CTA Section
+
+```
+┌─────────────────────────────────────────────────┐
+│                                                 │
+│     Ready to try {Product}?                     │
+│     Join the waitlist for early access.          │
+│                                                 │
+│     [email@example.com        ] [Join →]        │
+│                                                 │
+│     ✓ No spam. We'll only email you when        │
+│       we launch.                                │
+│                                                 │
+└─────────────────────────────────────────────────┘
+```
+
+- Prominent section near bottom (but before footer).
+- Headline: compelling CTA ("Ready to X?", "Be the first to try").
+- Email input + submit button on one line (desktop), stacked (mobile).
+- Trust line below: "No spam" or "Join X others".
+- States:
+  - **Default**: input + button enabled.
+  - **Loading**: button shows spinner, input disabled.
+  - **Success**: replace form with "You're on the list! We'll notify you at {email}."
+  - **Error**: show error message below input (invalid email, server error).
+
+### 9. Footer
+
+```
+{Product Name}                    Features | Pricing | Waitlist
+Built with ♥                     © 2026 {Product}. All rights reserved.
+```
+
+- Simple. Product name, nav links (repeat from navbar), copyright.
+- Optional: social links (use # placeholders).
+- Dark or muted background to separate from content.
+
+---
+
+## Waitlist Backend Patterns
+
+### Backend Stacks (Next.js, Nuxt, Laravel)
+
+**API Route Pattern:**
+
+```
+POST /api/waitlist
+Body: { "email": "user@example.com" }
+
+→ Validate email format (regex or built-in validator)
+→ Read waitlist.json from disk (create if doesn't exist)
+→ Check for duplicate email
+→ Append { email, timestamp, source: "landing-page" }
+→ Write back to waitlist.json
+→ Return { success: true, message: "You're on the list!" }
+
+Errors:
+→ Invalid email: 400 { success: false, message: "Please enter a valid email." }
+→ Duplicate: 200 { success: true, message: "You're already on the list!" }
+→ Server error: 500 { success: false, message: "Something went wrong. Try again." }
+```
+
+**waitlist.json format:**
+```json
+{
+  "entries": [
+    {
+      "email": "user@example.com",
+      "timestamp": "2026-03-18T10:30:00Z",
+      "source": "landing-page"
+    }
+  ]
+}
+```
+
+The waitlist.json file should be in a non-public location:
+- Next.js: project root `./waitlist.json` (outside `public/`)
+- Nuxt: project root `./waitlist.json`
+- Laravel: `storage/app/waitlist.json`
+
+### Static Stacks (React + Vite)
+
+**Formspree Pattern:**
+
+```html
+<form action="https://formspree.io/f/{your-form-id}" method="POST">
+  <input type="email" name="email" required />
+  <button type="submit">Join Waitlist</button>
+</form>
+```
+
+- Handle submission via JavaScript fetch for better UX (show loading/success states).
+- Add a code comment: `// Replace {your-form-id} with your Formspree form ID — create one free at formspree.io`
+- Handle Formspree's response format for success/error states.
+
+---
+
+## Copywriting Guidelines
+
+- **Headlines**: Lead with the benefit, not the feature. "Save 10 hours a week" > "Task management tool".
+- **Subheadlines**: Be specific about who and what. "For freelancers who juggle too many clients" > "For everyone".
+- **CTAs**: Action verb + outcome. "Get early access" > "Submit". "Join the waitlist" > "Sign up".
+- **Feature descriptions**: Problem → solution format. "Stop losing track of invoices. Auto-track every payment in real time."
+- **Tone**: Match the product. B2B SaaS = professional but warm. Dev tools = casual and direct. Consumer = friendly and energetic.
+- **Never use**: "Revolutionize", "leverage", "synergy", "disrupt", "cutting-edge" (overused startup jargon).

package/skills/sk:mvp/references/stacks/laravel.md

@@ -0,0 +1,321 @@
+# Laravel + Blade + Tailwind — Stack Reference
+
+## Scaffold
+
+```bash
+composer create-project laravel/laravel {project-name}
+cd {project-name}
+npm install
+```
+
+Laravel ships with Tailwind and Vite out of the box (Laravel 11+).
+
+## Directory Structure
+
+```
+{project-name}/
+├── resources/
+│   ├── views/
+│   │   ├── layouts/
+│   │   │   ├── landing.blade.php      ← landing page layout
+│   │   │   └── app.blade.php          ← app layout (sidebar)
+│   │   ├── components/
+│   │   │   ├── landing/
+│   │   │   │   ├── navbar.blade.php
+│   │   │   │   ├── hero.blade.php
+│   │   │   │   ├── features.blade.php
+│   │   │   │   ├── how-it-works.blade.php
+│   │   │   │   ├── pricing.blade.php
+│   │   │   │   ├── testimonials.blade.php
+│   │   │   │   ├── waitlist-form.blade.php
+│   │   │   │   └── footer.blade.php
+│   │   │   ├── app/
+│   │   │   │   ├── sidebar.blade.php
+│   │   │   │   └── {feature components}
+│   │   │   └── ui/
+│   │   │       ├── button.blade.php
+│   │   │       ├── input.blade.php
+│   │   │       ├── card.blade.php
+│   │   │       └── modal.blade.php
+│   │   ├── landing.blade.php          ← landing page
+│   │   ├── dashboard.blade.php        ← dashboard
+│   │   ├── {feature-1}.blade.php
+│   │   ├── {feature-2}.blade.php
+│   │   └── settings.blade.php
+│   ├── css/
+│   │   └── app.css                    ← Tailwind directives + custom vars
+│   └── js/
+│       └── app.js                     ← Vite entry + Alpine.js for interactivity
+├── routes/
+│   └── web.php                        ← all routes
+├── app/
+│   └── Http/
+│       └── Controllers/
+│           └── WaitlistController.php
+├── storage/
+│   └── app/
+│       └── waitlist.json              ← email storage (auto-created)
+├── public/
+│   └── {compiled assets}
+├── tailwind.config.js
+├── vite.config.js
+└── package.json
+```
+
+## Routes
+
+`routes/web.php`:
+
+```php
+use App\Http\Controllers\WaitlistController;
+
+// Landing page
+Route::view('/', 'landing');
+
+// App pages
+Route::view('/dashboard', 'dashboard');
+Route::view('/{feature-1}', '{feature-1}');
+Route::view('/{feature-2}', '{feature-2}');
+Route::view('/settings', 'settings');
+
+// Waitlist API
+Route::post('/api/waitlist', [WaitlistController::class, 'store']);
+```
+
+## Layouts
+
+### Landing Layout (`resources/views/layouts/landing.blade.php`)
+
+```blade
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{{ $title ?? '{Product Name}' }}</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link href="https://fonts.googleapis.com/css2?family={DisplayFont}:wght@400;600;700;800&family={BodyFont}:wght@400;500;600&display=swap" rel="stylesheet">
+    @vite(['resources/css/app.css', 'resources/js/app.js'])
+</head>
+<body class="bg-bg text-fg font-body antialiased">
+    {{ $slot }}
+</body>
+</html>
+```
+
+### App Layout (`resources/views/layouts/app.blade.php`)
+
+```blade
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{{ $title ?? '{Product Name}' }}</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link href="https://fonts.googleapis.com/css2?family={DisplayFont}:wght@400;600;700;800&family={BodyFont}:wght@400;500;600&display=swap" rel="stylesheet">
+    @vite(['resources/css/app.css', 'resources/js/app.js'])
+</head>
+<body class="bg-bg text-fg font-body antialiased">
+    <div class="flex min-h-screen">
+        <x-app.sidebar />
+        <main class="flex-1 p-6 lg:p-8">
+            {{ $slot }}
+        </main>
+    </div>
+</body>
+</html>
+```
+
+## Tailwind Config
+
+`tailwind.config.js`:
+
+```js
+export default {
+  content: [
+    './resources/**/*.blade.php',
+    './resources/**/*.js',
+  ],
+  theme: {
+    extend: {
+      colors: {
+        bg: 'var(--color-bg)',
+        fg: 'var(--color-fg)',
+        accent: 'var(--color-accent)',
+        muted: 'var(--color-muted)',
+      },
+      fontFamily: {
+        display: ['{DisplayFont}', 'serif'],
+        body: ['{BodyFont}', 'sans-serif'],
+      },
+    },
+  },
+}
+```
+
+CSS variables in `resources/css/app.css`:
+
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+:root {
+  --color-bg: #xxxxxx;
+  --color-fg: #xxxxxx;
+  --color-accent: #xxxxxx;
+  --color-muted: #xxxxxx;
+}
+```
+
+## Interactivity with Alpine.js
+
+Install Alpine.js for lightweight interactivity (modals, toasts, form states):
+
+```bash
+npm install alpinejs
+```
+
+`resources/js/app.js`:
+
+```js
+import Alpine from 'alpinejs'
+window.Alpine = Alpine
+Alpine.start()
+```
+
+## Waitlist Controller
+
+`app/Http/Controllers/WaitlistController.php`:
+
+```php
+<?php
+
+namespace App\Http\Controllers;
+
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Storage;
+
+class WaitlistController extends Controller
+{
+    public function store(Request $request)
+    {
+        $request->validate([
+            'email' => 'required|email',
+        ]);
+
+        $email = $request->input('email');
+        $path = 'waitlist.json';
+
+        // Read or create
+        $data = Storage::exists($path)
+            ? json_decode(Storage::get($path), true)
+            : ['entries' => []];
+
+        // Check duplicate
+        $exists = collect($data['entries'])->contains('email', $email);
+        if ($exists) {
+            return response()->json(['success' => true, 'message' => "You're already on the list!"]);
+        }
+
+        // Append
+        $data['entries'][] = [
+            'email' => $email,
+            'timestamp' => now()->toISOString(),
+            'source' => 'landing-page',
+        ];
+
+        Storage::put($path, json_encode($data, JSON_PRETTY_PRINT));
+
+        return response()->json(['success' => true, 'message' => "You're on the list!"]);
+    }
+}
+```
+
+## Blade Component Patterns
+
+### Anonymous Components (preferred for UI)
+
+`resources/views/components/ui/button.blade.php`:
+
+```blade
+@props(['variant' => 'primary', 'size' => 'md'])
+
+@php
+$classes = match($variant) {
+    'primary' => 'bg-accent text-white hover:opacity-90',
+    'secondary' => 'border border-accent text-accent hover:bg-accent/10',
+    'ghost' => 'text-fg hover:bg-muted/20',
+};
+$sizes = match($size) {
+    'sm' => 'px-4 py-2 text-sm',
+    'md' => 'px-6 py-3 text-base',
+    'lg' => 'px-8 py-4 text-lg',
+};
+@endphp
+
+<button {{ $attributes->merge(['class' => "$classes $sizes rounded-xl font-medium transition-all duration-200"]) }}>
+    {{ $slot }}
+</button>
+```
+
+Usage: `<x-ui.button variant="primary">Join Waitlist</x-ui.button>`
+
+### Landing Page
+
+`resources/views/landing.blade.php`:
+
+```blade
+<x-layouts.landing>
+    <x-landing.navbar />
+    <x-landing.hero />
+    <x-landing.features />
+    <x-landing.how-it-works />
+    <x-landing.pricing />
+    <x-landing.testimonials />
+    <x-landing.waitlist-form />
+    <x-landing.footer />
+</x-layouts.landing>
+```
+
+### Waitlist Form with Alpine.js
+
+```blade
+<div x-data="{ email: '', status: 'idle', message: '' }">
+    <form @submit.prevent="
+        status = 'loading';
+        fetch('/api/waitlist', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', 'X-CSRF-TOKEN': '{{ csrf_token() }}' },
+            body: JSON.stringify({ email })
+        })
+        .then(r => r.json())
+        .then(d => { status = 'success'; message = d.message; })
+        .catch(() => { status = 'error'; message = 'Something went wrong.'; })
+    ">
+        <template x-if="status !== 'success'">
+            <div class="flex gap-3">
+                <input x-model="email" type="email" placeholder="you@example.com" required
+                       class="flex-1 px-4 py-3 rounded-lg border focus:ring-2 focus:ring-accent" />
+                <x-ui.button type="submit" x-bind:disabled="status === 'loading'">
+                    <span x-show="status !== 'loading'">Join Waitlist</span>
+                    <span x-show="status === 'loading'">Joining...</span>
+                </x-ui.button>
+            </div>
+        </template>
+        <p x-show="status === 'success'" x-text="message" class="text-green-600 font-medium"></p>
+        <p x-show="status === 'error'" x-text="message" class="text-red-500 text-sm mt-2"></p>
+    </form>
+</div>
+```
+
+## Dev Server
+
+```bash
+# Run both in separate terminals (or use Concurrently)
+php artisan serve          # http://localhost:8000
+npm run dev                # Vite dev server for assets
+```
+
+Or use Laravel Herd if available (auto-serves at `{project-name}.test`).