Vibe Coding Best Practices

❌ Don't do this:

"Build a complete e-commerce site with products, cart, and checkout"

✅ Do this instead:

Turn 1: "Create the layout shell - Header, Footer, Sidebar, MainContent"
Turn 2: "Build a ProductCard component with image, title, price, add-to-cart"
Turn 3: "Create a CartDrawer that slides in from the right"
Turn 4: "Build a CheckoutForm with validation"
Turn 5: "Connect all components with state management"

Example design system prompt:

"Create a design system configuration:

Colors:
- Primary: #3b82f6 (blue)
- Secondary: #8b5cf6 (purple)
- Success: #10b981 (green)
- Error: #ef4444 (red)
- Neutral: grays from 50-900

Typography:
- Headings: Inter font, bold
- Body: Inter font, regular
- Scale: 12px, 14px, 16px, 20px, 24px, 32px, 48px

Spacing:
- Use 4px base unit (4, 8, 12, 16, 24, 32, 48, 64)

Border Radius:
- sm: 4px, md: 8px, lg: 12px, xl: 16px

Shadows:
- sm, md, lg elevations

Create this as Tailwind config and CSS variables."

"Create a UserProfile component with TypeScript.

Props interface:
interface UserProfileProps {
  user: {
    id: string;
    name: string;
    email: string;
    avatar?: string;
    role: 'admin' | 'user' | 'guest';
    joinedAt: Date;
  };
  onEdit?: () => void;
  isEditable?: boolean;
}

Include prop validation and JSDoc comments."

Always include:

• • "Make it fully keyboard accessible (Tab, Enter, Escape navigation)"
• • "Add proper ARIA labels and roles"
• • "Ensure screen reader compatibility"
• • "Use semantic HTML elements"
• • "Maintain WCAG 2.1 AA contrast ratios"
• • "Include focus visible states"

"Create a ProductList component that handles:

Loading state:
- Show skeleton loaders while fetching
- Use 6 skeleton cards in a grid

Error state:
- Show error message if fetch fails
- Include retry button
- Log error to console

Empty state:
- Show friendly message if no products
- Suggest actions (browse categories, clear filters)

Success state:
- Render product grid
- Include pagination if >20 items"

• →"Use React.memo to prevent unnecessary re-renders"
• →"Implement lazy loading for images with intersection observer"
• →"Use useMemo for expensive calculations"
• →"Debounce search input with 300ms delay"
• →"Virtualize long lists (>100 items) with react-window"

"Create a LoginForm component with Vitest tests.

Test cases:
- Renders email and password fields
- Shows validation errors for invalid email
- Disables submit when form is invalid
- Calls onSubmit with correct data
- Shows loading state during submission
- Displays API error messages

Use React Testing Library and user-event."

• "Add JSDoc comments explaining each prop"
• "Include usage example in the component file"
• "Add inline comments for complex logic"
• "Generate README.md with component API docs"
• "Create Storybook stories showing all variants"

src/
  components/
    ui/           # Design system components
    features/     # Feature-specific components
    layouts/      # Page layouts
  hooks/          # Custom React hooks
  lib/            # Utilities and helpers
  types/          # TypeScript types
  api/            # API client and endpoints
  stores/         # State management
  styles/         # Global styles, themes
  __tests__/      # Test files

• ✓No hardcoded values (use constants or env vars)
• ✓Proper error handling (try/catch, error boundaries)
• ✓Accessibility attributes present
• ✓TypeScript types are specific (not 'any')
• ✓Loading and error states handled
• ✓Mobile responsive (test in DevTools)
• ✓No console.logs or debug code
• ✓Dependencies are actually needed

"Create a ProductPage component for an e-commerce site.

Tech stack:
- Next.js 14 with App Router
- TypeScript (strict mode)
- Tailwind CSS
- React Query for data fetching

Features:
- Image gallery with zoom on hover
- Product title, price, description
- Size/color variant selector
- Quantity picker
- Add to cart button
- Related products section
- Customer reviews

Requirements:
- SEO: Proper meta tags, JSON-LD structured data
- Performance: Image optimization, lazy load below fold
- Accessibility: Keyboard navigation, ARIA labels, focus management
- Mobile: Touch-friendly, responsive grid
- Error handling: Handle out of stock, fetch errors
- Loading: Skeleton loaders for all sections

State:
- Use Zustand for cart
- React Query for product data
- Local state for selected variant

Types:
interface Product {
  id: string;
  name: string;
  price: number;
  salePrice?: number;
  description: string;
  images: string[];
  variants: { size: string; color: string; stock: number }[];
  reviews: Review[];
  relatedProducts: string[];
}

Include:
- TypeScript types file
- Unit tests for variant selection logic
- Storybook story
- README with component API"