distromatch/design_guidelines.md

# DistroMatch Design Guidelines

## Design Philosophy
Create a premium, desktop-first "Tinder for Linux Distros" experience that feels cinematic and playful. Reject traditional survey-based tools in favor of visceral, swipe-based discovery using landscape desktop screenshots.

## Layout System

**Core Structure:**
- Single-page application with centered card stack as focal point
- Cards positioned in absolute center of viewport
- Use Tailwind spacing: p-4, p-6, p-8 for consistent padding
- Container max-width: 1200px for card stack area

**Card Dimensions:**
- Landscape orientation (16:9 aspect ratio) - NEVER vertical/portrait
- Recommended size: 900px width × 506px height (or proportional)
- Card stack: 3-5 cards visible with z-index layering
- Cards behind should be slightly offset and scaled down (scale-95)

## Component Architecture

**1. Card Stack System:**
- Top card: Full size, draggable, z-index highest
- Second card: scale-95, slight vertical offset (8px down)
- Third+ cards: scale-90, progressive offsets
- Empty state when deck is finished

**2. Card Component Structure:**
```
Card Container (rounded-2xl, shadow-2xl)
├── Screenshot Area (16:9, covers top 75% of card)
│   └── High-quality Linux desktop screenshot
└── Info Bar (bottom 25%, elegant dark overlay)
    ├── Witty Title (text-xl, font-bold)
    ├── Distro Name (text-sm, muted)
    └── Optional: Quick stats or tags
```

**3. Info Bar Design:**
- Semi-transparent dark background (bg-black/80 backdrop-blur-md)
- Padding: px-8 py-6
- Text must never overlap screenshot
- Rounded bottom corners matching card (rounded-b-2xl)

## Typography

**Fonts via Google Fonts:**
- Primary: Inter (headings, UI elements) - weights 400, 600, 700
- Secondary: Space Grotesk (witty card titles) - weights 500, 700

**Hierarchy:**
- Card titles: text-2xl font-bold (witty personality descriptions)
- Distro names: text-lg font-semibold
- UI labels: text-sm font-medium
- Metadata: text-xs text-gray-400

## Interaction Design

**Swipe Mechanics:**
- Drag threshold: 150px horizontal movement to trigger decision
- Swipe right (>150px) = LIKE
- Swipe left (<-150px) = DISLIKE
- Visual feedback: Rotate card based on drag distance (max ±15deg)
- On release: Physics-based throw animation if threshold met

**Animation Requirements (Framer Motion):**
- Front card drag: Follow cursor with spring physics
- Background card: Scale from 95 to 100 as front card moves
- Throw animation: Smooth exit with rotation matching swipe direction
- New card entrance: Fade in and scale up from 90 to 100
- Background gradient: Smooth color transition (300ms ease)

**Button Controls:**
- Bottom center: Two action buttons (Dislike/Like)
- Style: Large rounded buttons (w-16 h-16 rounded-full)
- Icons: X (dislike), Heart (like) from Lucide-React
- Hover states: Subtle scale-110 and shadow increase

## Background Treatment

**Dynamic Gradient:**
- Full viewport background
- Blur effect: backdrop-blur-3xl
- Color extraction: Sample dominant colors from current card screenshot
- Create radial gradient with extracted colors at 30% opacity
- Transition smoothly between cards (animate gradient-shift)
- Fallback: Subtle purple-to-blue gradient

## Data Structure

**Card Data Model:**
```
interface DistroCard {
  id: string
  distroName: string
  screenshot: string (URL or path)
  wittyTitle: string (e.g., "Terminal is life", "Mac envy approved")
  desktopEnvironment: string
  tags: string[]
  colorPalette?: string[] (for background gradient)
}
```

**Sample Witty Titles:**
- "Terminalden çıkmam" (Never leaves terminal)
- "Mac gibi olsun" (Make it Mac-like)
- "Sadece çalışsın yeter" (Just make it work)
- "Özelleştirme canavarı" (Customization beast)

## Images

**Screenshot Requirements:**
- High-resolution desktop screenshots (1920×1080 minimum)
- Various Linux distributions and desktop environments
- Clean, representative workspace examples
- Showcase different aesthetics (minimal, maximal, professional, gaming)
- 15-20 diverse examples covering: GNOME, KDE, i3, XFCE, Cinnamon, etc.

**Placement:**
- Each card features one full-bleed screenshot covering 75% of card height
- Aspect ratio strictly maintained at 16:9
- No hero section - app focuses entirely on card interaction

## Responsive Considerations

**Desktop-First (Primary):**
- Optimized for 1440px+ displays
- Cards remain landscape and centered
- Maximum engagement with large viewport

**Tablet (1024px):**
- Slightly smaller cards (700px width)
- Maintain landscape orientation
- Buttons remain accessible

**Mobile (768px and below):**
- Cards scale down but NEVER become vertical
- May need horizontal scrolling or reduced card size
- Swipe gestures remain primary interaction

## Special States

**Loading State:**
- Skeleton cards with shimmer effect
- Maintain card stack layout

**End of Deck:**
- "Recommendations ready!" message
- Reset or view results buttons
- Celebratory micro-animation

**Swipe Indicators:**
- Subtle overlay on card during drag showing LIKE (green) or NOPE (red)
- Opacity increases with drag distance
- Icon appears in drag direction

## Modular Architecture

**File Structure:**
- `/components/CardStack.tsx` - Main card container
- `/components/SwipeCard.tsx` - Individual draggable card
- `/components/ActionButtons.tsx` - Like/Dislike controls
- `/data/distros.ts` - Card data array
- `/utils/colorExtractor.ts` - Background gradient logic
- `/hooks/useSwipe.ts` - Swipe gesture management