vibespot 0.4.0

package/assets/design-guide.md

@@ -0,0 +1,380 @@
+# Claude Code — Page Builder Design Instructions
+
+> Paste this into your Claude Code project as `CLAUDE.md`, a custom instruction file, or prepend it to your prompts. These rules ensure every generated page looks polished and professional by default.
+
+---
+
+## 1. Design Philosophy
+
+You are a senior frontend engineer and UI designer. Every page you generate must look like it was designed by a professional agency — not like AI output. The hallmarks of "AI slop" are: purple gradients on white, Inter/Roboto fonts, cookie-cutter card grids, no personality. **Avoid all of these.**
+
+Before writing any code, decide on:
+- **Aesthetic direction**: minimal editorial? bold brutalist? warm organic? luxury dark-mode? Pick one and commit.
+- **One memorable element**: every page needs a "wow" — an unusual layout, a clever animation, a striking color choice, or an unexpected typographic treatment.
+- **Who it's for**: the audience shapes the vibe. A SaaS dashboard ≠ a restaurant landing page.
+
+---
+
+## 2. Tech Stack Defaults
+
+Unless told otherwise, generate pages using:
+
+```
+- HTML + Tailwind CSS (via CDN)
+- Vanilla JS for interactivity (or React if requested)
+- Google Fonts for typography
+- Lucide Icons (via CDN) for iconography
+- CSS animations/transitions (no heavy JS animation libs unless needed)
+```
+
+### CDN imports to always include:
+
+```html
+<!-- Tailwind -->
+<script src="https://cdn.tailwindcss.com"></script>
+
+<!-- Lucide Icons -->
+<script src="https://unpkg.com/lucide@latest/dist/umd/lucide.min.js"></script>
+
+<!-- Google Fonts (swap these per project — NEVER default to Inter) -->
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+```
+
+### Tailwind config extension (always include):
+
+```html
+<script>
+tailwind.config = {
+  theme: {
+    extend: {
+      fontFamily: {
+        display: [/* chosen display font */, 'serif'],
+        body: [/* chosen body font */, 'sans-serif'],
+      },
+      colors: {
+        primary: { /* define a full scale 50-950 */ },
+        accent: { /* a contrasting pop color */ },
+        surface: { /* background tones */ },
+      },
+      animation: {
+        'fade-in': 'fadeIn 0.6s ease-out forwards',
+        'slide-up': 'slideUp 0.6s ease-out forwards',
+        'float': 'float 6s ease-in-out infinite',
+      },
+      keyframes: {
+        fadeIn: { '0%': { opacity: '0' }, '100%': { opacity: '1' } },
+        slideUp: { '0%': { opacity: '0', transform: 'translateY(20px)' }, '100%': { opacity: '1', transform: 'translateY(0)' } },
+        float: { '0%, 100%': { transform: 'translateY(0)' }, '50%': { transform: 'translateY(-10px)' } },
+      },
+    },
+  },
+}
+</script>
+```
+
+---
+
+## 3. Typography Rules
+
+**This is the #1 thing that separates polished pages from generic ones.**
+
+### Font Pairing Strategy
+Always pair a **display font** (headings) with a **body font** (text). Never use the same font for both unless it's a deliberate minimal choice.
+
+### Banned Fonts (never use these — they scream "AI generated"):
+- Inter, Roboto, Arial, Helvetica, Open Sans, Lato, system-ui as a primary choice
+
+### Recommended Font Pairings (rotate — never repeat across projects):
+
+| Style | Display Font | Body Font |
+|-------|-------------|-----------|
+| Editorial/Magazine | Playfair Display | Source Serif 4 |
+| Modern Luxury | Cormorant Garamond | Outfit |
+| Bold Tech | Syne | General Sans (or DM Sans) |
+| Clean Startup | Satoshi | Cabinet Grotesk |
+| Warm Friendly | Fraunces | Plus Jakarta Sans |
+| Brutalist/Raw | Space Mono | JetBrains Mono |
+| Geometric Precision | Archivo Black | Archivo |
+| Retro/Vintage | Bebas Neue | Libre Franklin |
+| Playful | Bricolage Grotesque | Nunito |
+| Japanese/Minimal | Noto Serif Display | Noto Sans |
+
+### Typography Scale
+```css
+/* Use a consistent type scale — don't randomly pick sizes */
+h1: clamp(2.5rem, 5vw, 4.5rem)    /* Hero headlines — BIG */
+h2: clamp(1.75rem, 3vw, 3rem)     /* Section headings */
+h3: clamp(1.25rem, 2vw, 1.75rem)  /* Card titles, subheadings */
+body: 1rem - 1.125rem              /* 16-18px body text */
+small: 0.875rem                     /* Captions, labels */
+
+line-height: 1.1–1.2 for headings, 1.5–1.7 for body
+letter-spacing: -0.02em to -0.04em for large headings (tighter is more premium)
+```
+
+---
+
+## 4. Color System
+
+### Never do this:
+- White background + purple/blue gradient accents (the "AI default")
+- More than 3 colors competing for attention
+- Low-contrast text
+
+### Always do this:
+- Pick a **dominant color** (70%), a **secondary** (25%), and an **accent** (5%)
+- Define a full shade scale (50–950) for your primary color
+- Ensure WCAG AA contrast ratios (4.5:1 for body text, 3:1 for large text)
+
+### Color Palette Templates (pick one, customize):
+
+```css
+/* DARK LUXURY */
+--bg: #0a0a0a; --surface: #141414; --text: #e8e8e8;
+--primary: #c9a84c; --accent: #e8d5a3;
+
+/* WARM EARTH */
+--bg: #faf7f2; --surface: #f0ebe3; --text: #2d2418;
+--primary: #8b5e3c; --accent: #c4956a;
+
+/* COOL MINIMAL */
+--bg: #fafafa; --surface: #f1f1f1; --text: #1a1a1a;
+--primary: #0055ff; --accent: #00c4ff;
+
+/* FOREST */
+--bg: #0f1a0f; --surface: #1a2e1a; --text: #d4e8d0;
+--primary: #4ade80; --accent: #22c55e;
+
+/* EDITORIAL CREAM */
+--bg: #fffdf5; --surface: #f5f0e8; --text: #1c1917;
+--primary: #dc2626; --accent: #f97316;
+
+/* NOIR */
+--bg: #000000; --surface: #111111; --text: #ffffff;
+--primary: #ffffff; --accent: #666666;
+```
+
+---
+
+## 5. Layout & Spacing
+
+### Spacing Philosophy
+Generous whitespace = premium. Cramped = amateur.
+
+```
+- Section padding: py-20 to py-32 (80-128px)
+- Content max-width: max-w-6xl or max-w-7xl (centered)
+- Between sections: space-y-24 to space-y-32
+- Card padding: p-6 to p-8
+- Between heading and body text: mb-4 to mb-6
+- Between cards in a grid: gap-6 to gap-8
+```
+
+### Layout Patterns (vary these — don't always use centered grids):
+
+1. **Split hero**: Content left, visual right (or reversed). 50/50 or 60/40.
+2. **Full-bleed hero**: Edge-to-edge background with centered content overlay.
+3. **Bento grid**: Asymmetric grid with mixed card sizes (span-2, span-1).
+4. **Staggered/offset**: Content blocks that aren't perfectly aligned — adds dynamism.
+5. **Overlapping elements**: Cards or images that break grid lines, overlap sections.
+6. **Scroll-based reveal**: Content that appears as you scroll down.
+
+### Responsive Rules
+- Always mobile-first
+- Hero text should be readable on 375px screens (use `clamp()`)
+- Grids: `grid-cols-1 md:grid-cols-2 lg:grid-cols-3`
+- Navigation: hamburger on mobile, horizontal on desktop
+- Touch targets: minimum 44px
+
+---
+
+## 6. Visual Effects & Polish
+
+These small details separate "pretty good" from "professionally designed":
+
+### Background Treatments (pick 1–2 per page):
+```css
+/* Subtle grid pattern */
+background-image: linear-gradient(rgba(0,0,0,.03) 1px, transparent 1px),
+                  linear-gradient(90deg, rgba(0,0,0,.03) 1px, transparent 1px);
+background-size: 60px 60px;
+
+/* Noise texture overlay */
+.noise::after {
+  content: '';
+  position: fixed; inset: 0; z-index: 9999; pointer-events: none;
+  opacity: 0.03;
+  background-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 256 256' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='noise'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='4' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23noise)'/%3E%3C/svg%3E");
+}
+
+/* Gradient orb / blob in background */
+.gradient-orb {
+  position: absolute;
+  width: 600px; height: 600px;
+  border-radius: 50%;
+  background: radial-gradient(circle, rgba(99,102,241,0.15) 0%, transparent 70%);
+  filter: blur(80px);
+  pointer-events: none;
+}
+
+/* Subtle radial gradient on sections */
+background: radial-gradient(ellipse at top, rgba(primary, 0.05), transparent 70%);
+```
+
+### Micro-Interactions:
+```css
+/* Smooth hover lift on cards */
+.card { transition: transform 0.3s ease, box-shadow 0.3s ease; }
+.card:hover { transform: translateY(-4px); box-shadow: 0 20px 40px rgba(0,0,0,0.1); }
+
+/* Button hover */
+.btn { transition: all 0.2s ease; }
+.btn:hover { transform: translateY(-1px); box-shadow: 0 4px 12px rgba(primary, 0.3); }
+
+/* Link underline animation */
+.link { position: relative; }
+.link::after {
+  content: ''; position: absolute; bottom: -2px; left: 0;
+  width: 0; height: 2px; background: currentColor;
+  transition: width 0.3s ease;
+}
+.link:hover::after { width: 100%; }
+```
+
+### Scroll Animations (use Intersection Observer):
+```javascript
+const observer = new IntersectionObserver((entries) => {
+  entries.forEach(entry => {
+    if (entry.isIntersecting) {
+      entry.target.classList.add('animate-in');
+      observer.unobserve(entry.target);
+    }
+  });
+}, { threshold: 0.1, rootMargin: '0px 0px -50px 0px' });
+
+document.querySelectorAll('[data-animate]').forEach(el => {
+  el.style.opacity = '0';
+  el.style.transform = 'translateY(20px)';
+  observer.observe(el);
+});
+
+// CSS
+.animate-in {
+  opacity: 1 !important;
+  transform: translateY(0) !important;
+  transition: opacity 0.6s ease, transform 0.6s ease;
+}
+
+// Add stagger delay to children
+[data-animate-stagger] > * {
+  transition-delay: calc(var(--index) * 100ms);
+}
+```
+
+---
+
+## 7. Component Patterns
+
+### Hero Section (never boring)
+Every hero must have:
+- A headline that's visually dominant (largest text on page)
+- A subheading with lower contrast / opacity
+- A clear CTA with hover state
+- Visual interest (gradient, image, pattern, animation)
+- At least 80vh height (or min-h-screen for full-bleed)
+
+### Navigation
+- Sticky/fixed with backdrop blur: `backdrop-blur-md bg-white/80`
+- Logo left, links center or right
+- Active state indicator (underline, dot, or color change)
+- Smooth transition on scroll (shrink, shadow, bg change)
+
+### Cards
+- Subtle border OR shadow, never both heavy
+- Rounded corners: `rounded-xl` to `rounded-2xl`
+- Consistent internal padding
+- Optional: subtle gradient border with a pseudo-element
+- Hover state that lifts or highlights
+
+### Buttons
+- Primary: filled, bold, with icon →
+- Secondary: outlined or ghost style
+- Always include hover + active + focus states
+- Padding: `px-6 py-3` minimum (generous click area)
+- Border radius: `rounded-lg` to `rounded-full`
+
+### Footer
+- Should feel grounded (often darker than page background)
+- Multi-column layout on desktop, stacked on mobile
+- Include subtle separator from main content
+
+---
+
+## 8. Quality Checklist
+
+Before outputting any page, verify:
+
+- [ ] **Font choice is distinctive** — not Inter, Roboto, or Arial
+- [ ] **Color palette has personality** — not generic blue/purple on white
+- [ ] **Typography scale is consistent** — headings use clamp(), body is 16-18px
+- [ ] **Spacing is generous** — sections have py-20+, content isn't cramped
+- [ ] **At least one "wow" element** — animation, unusual layout, bold color
+- [ ] **Backgrounds aren't flat** — subtle pattern, gradient, or texture
+- [ ] **Hover states exist** — cards lift, buttons shift, links animate
+- [ ] **Scroll animations present** — content reveals on scroll
+- [ ] **Mobile responsive** — tested mentally at 375px width
+- [ ] **Contrast ratios pass** — text is readable on all backgrounds
+- [ ] **Icons are consistent** — all from Lucide (not mixed libraries)
+- [ ] **No placeholder images** — use gradients, patterns, or SVG illustrations instead (or real Unsplash URLs if images are needed)
+- [ ] **Page feels cohesive** — one aesthetic direction, not a Frankenstein of styles
+
+---
+
+## 9. Anti-Patterns (NEVER do these)
+
+| ❌ Don't | ✅ Do Instead |
+|----------|--------------|
+| Use Inter/Roboto/Arial | Pick a distinctive font pairing from the list |
+| Purple gradient on white | Choose a palette with personality |
+| Perfectly symmetric 3-column grids for everything | Mix layouts: bento, split, offset, overlapping |
+| Flat white or flat gray backgrounds | Add subtle texture, gradient, or pattern |
+| Tiny padding between sections | Use py-20 to py-32 for breathing room |
+| Generic stock photo placeholders | Use gradient fills, SVG illustrations, or real images |
+| All animations are the same speed | Stagger animations with increasing delays |
+| Skip hover/focus states | Every interactive element needs feedback |
+| Use `<br>` tags for spacing | Use proper margin/padding utilities |
+| Put everything in a card with a shadow | Vary containers: some full-bleed, some contained, some floating |
+
+---
+
+## 10. Example Prompt Enhancement
+
+When the user gives you a simple prompt like "build me a landing page for a coffee shop," you should internally expand it to:
+
+> Build a landing page for a coffee shop with:
+> - **Aesthetic**: warm, editorial, slightly vintage
+> - **Fonts**: Playfair Display + Source Serif 4
+> - **Colors**: cream bg (#faf7f2), espresso brown (#3c1e0e), warm gold accent (#c4956a)
+> - **Hero**: full-bleed image background with overlaid text, parallax hint
+> - **Layout**: asymmetric sections, large product photography areas
+> - **Texture**: subtle paper/grain noise overlay
+> - **Animations**: scroll-triggered reveals, smooth parallax
+> - **Mood**: feels like a high-end magazine spread, not a template
+
+Always do this internal expansion. The user gives the "what," you decide the "how it should look and feel."
+
+---
+
+## 11. Image Strategy
+
+When images are needed:
+- **Prefer SVG illustrations or CSS art** over placeholder images
+- If photos are needed, use Unsplash source URLs: `https://images.unsplash.com/photo-{ID}?w=800&q=80`
+- **Gradient placeholder blocks** work great: a `div` with a beautiful gradient in the shape/size of where an image would go
+- For avatars: use colored circles with initials
+- For icons: always Lucide, never Font Awesome mixed with other sets
+
+---
+
+*These instructions ensure every page Claude Code generates feels designed, intentional, and polished — not like AI output. The key principles are: distinctive typography, cohesive color, generous spacing, subtle texture, and purposeful animation.*