← back to Wine Finder Next

DESIGN_SYSTEM.md

531 lines

# Wine Finder - Design System Documentation

## Overview
A mobile-first, accessible design system for the Red Thunder Wine Tracker application. Built with Tailwind CSS and React, focusing on wine discovery, price comparison, and affiliate partner integration.

---

## 1. Color Palette

### Primary Colors (Wine-Inspired)

**Wine Red Scale**
- `wine-50`: #fef2f4 - Lightest tint (backgrounds)
- `wine-100`: #fde6e9 - Light tint (hover states)
- `wine-500`: #ea4c6d - Base color (primary actions)
- `wine-600`: #d6315a - Darker (buttons, links)
- `wine-900`: #7f1c3e - Darkest (headers, text)
- `wine-950`: #460a1e - Ultra dark (shadows)

**Burgundy Scale**
- `burgundy-50` to `burgundy-950` - Secondary wine colors
- Primary use: Gradients, accents, hover states

**Gold Scale**
- `gold-50`: #fefbec - Light backgrounds
- `gold-400`: #f0c32e - Accents
- `gold-500`: #d4af37 - Primary gold (best price badges)
- `gold-700`: #9c6617 - Dark gold (text)

### Semantic Colors

**Success/In Stock**: `green-100`, `green-700`
**Warning/Limited Stock**: `yellow-100`, `yellow-700`
**Error/Out of Stock**: `red-100`, `red-700`
**Info**: `purple-100`, `purple-700`

---

## 2. Typography

### Font Families

**Sans-serif (Body & UI)**
```css
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Helvetica Neue', Arial, sans-serif
```

**Display (Headings)**
```css
font-family: Georgia, Cambria, 'Times New Roman', serif
```

### Type Scale

| Element | Size | Weight | Line Height | Usage |
|---------|------|--------|-------------|-------|
| H1 | 3xl-7xl | bold | tight | Page titles |
| H2 | 2xl-4xl | bold | tight | Section headers |
| H3 | xl-2xl | bold | snug | Card titles |
| Body | base-lg | normal | relaxed | Paragraphs |
| Small | sm | medium | normal | Labels, captions |
| Tiny | xs | normal | normal | Metadata |

### Mobile Typography
- All interactive text elements: minimum 16px to prevent iOS zoom
- Headings scale down by 1-2 sizes on mobile
- Maximum line length: 65 characters for readability

---

## 3. Spacing System

### Base Scale
- `1`: 0.25rem (4px)
- `2`: 0.5rem (8px)
- `3`: 0.75rem (12px)
- `4`: 1rem (16px)
- `6`: 1.5rem (24px)
- `8`: 2rem (32px)
- `12`: 3rem (48px)
- `16`: 4rem (64px)

### Custom Spacing
- `18`: 4.5rem (72px) - Component spacing
- `88`: 22rem (352px) - Large sections
- `128`: 32rem (512px) - Hero sections

### Container Padding
- Mobile: `px-4` (16px)
- Tablet: `px-6` (24px)
- Desktop: `px-8` (32px)

---

## 4. Components

### Wine Card

**Structure:**
```tsx
<div className="wine-card">
  {/* Image: 72 height (288px) */}
  <div className="relative h-72 bg-gradient-to-br from-purple-100 to-pink-100">
    <Image /> {/* Real wine bottle photos */}
  </div>

  {/* Content: p-5 spacing */}
  <div className="p-5 space-y-3">
    <h3>{name}</h3>
    <p>{winery}</p>
    <div>{vintage} • {type}</div>
    <div>{price} • {rating}</div>
    <button>View Details</button>
  </div>
</div>
```

**States:**
- Default: `shadow-md`
- Hover: `shadow-wine-lg scale-105`
- Active (mobile): `scale-98`
- Focus: Gold outline (2px solid)

**Badges:**
- New: Green gradient
- Deal: Red-pink gradient
- Featured: Purple-indigo gradient

---

### Search Bar

**Mobile-First Design:**
```tsx
<form className="w-full">
  <input
    style={{ fontSize: '16px' }} // Prevent iOS zoom
    className="w-full px-6 py-4 rounded-full..."
  />
  <button className="min-h-[44px]">Search</button>
</form>
```

**Touch Target:** Minimum 44x44px for all interactive elements

---

### Filter Bar

**Expandable on Mobile:**
- Collapsed by default on screens < 640px
- Toggle button with animated chevron
- Filters stack vertically

**Filter Types:**
1. **Source Checkboxes** - Multi-select pills
2. **Price Range** - Pre-defined ranges + slider
3. **Rating Slider** - 0-100 scale
4. **Wine Type** - Dropdown select
5. **Region** - Text input with search

**Accessibility:**
- All filters have labels
- Active filters visually distinct
- Clear "Reset" action

---

### Where to Buy Section

**Price Comparison Layout:**
```tsx
<div className="border-2 rounded-2xl p-6">
  {/* Best price gets gold gradient background */}
  <div className="flex justify-between items-center">
    <div>
      <h3>{retailer}</h3>
      <span>{availability}</span>
    </div>
    <div>
      <div>${price}</div>
      <button>Buy Now →</button>
    </div>
  </div>
</div>
```

**Best Price Indicator:**
- Gold gradient background
- "Best Price" badge
- Gold CTA button

**Affiliate Partner Logos:**
- Vivino: 🍇
- Total Wine: 🏪
- K&L: 🍷

---

## 5. Layouts

### Mobile Breakpoints
- `sm`: 640px (tablets)
- `md`: 768px (small laptops)
- `lg`: 1024px (laptops)
- `xl`: 1280px (desktops)

### Grid Systems

**Wine Grid:**
- Mobile: 1 column
- Tablet: 2 columns
- Desktop: 3-4 columns
- Gap: `gap-6` (24px)

**Container:**
- Max width: `container mx-auto`
- Padding: Responsive (4/6/8)

---

## 6. Animations

### Keyframe Animations

**Fade In** (0.5s ease-in-out)
```css
opacity: 0 → 1
```

**Slide Up** (0.4s ease-out)
```css
transform: translateY(20px) → translateY(0)
opacity: 0 → 1
```

**Scale In** (0.3s ease-out)
```css
transform: scale(0.9) → scale(1)
opacity: 0 → 1
```

**Bounce Subtle** (2s infinite)
```css
translateY(0) → translateY(-5px) → translateY(0)
```

**Shimmer** (2s linear infinite)
```css
background-position: -1000px → 1000px
```

### Usage
- Page load: `animate-fade-in`
- Staggered list items: `animate-slide-up` with delay
- Interactive elements: `transition-all duration-300`
- Loading states: `animate-pulse` or `animate-shimmer`

### Reduced Motion
All animations respect `prefers-reduced-motion: reduce`

---

## 7. Accessibility

### WCAG AA Compliance

**Color Contrast:**
- Body text: 4.5:1 minimum
- Large text: 3:1 minimum
- Interactive elements: Clear focus states

**Touch Targets:**
- Minimum 44x44px for all buttons/links
- Adequate spacing between clickable elements

**Screen Readers:**
- All images have alt text
- Form inputs have labels
- ARIA labels for icon buttons
- Semantic HTML structure

**Keyboard Navigation:**
- All interactive elements focusable
- Logical tab order
- Visible focus indicators (gold outline)

**Mobile Accessibility:**
- 16px minimum font size (prevents zoom)
- `-webkit-appearance: none` for iOS
- Safe area padding for notched devices

---

## 8. Responsive Design

### Mobile-First Approach

**320px - 640px (Mobile)**
- Single column layouts
- Stacked navigation
- Expandable filters
- Full-width CTAs
- Touch-optimized spacing

**640px - 1024px (Tablet)**
- 2-column grids
- Side-by-side filters
- Larger touch targets maintained

**1024px+ (Desktop)**
- 3-4 column grids
- Sticky navigation
- Hover interactions
- Larger imagery

---

## 9. States & Interactions

### Interactive States

**Buttons:**
- Default: Gradient background
- Hover: Darker gradient + shadow
- Active: Scale down (0.98)
- Focus: Gold outline
- Disabled: 50% opacity + no pointer

**Cards:**
- Default: Shadow-md
- Hover: Shadow-wine-lg + scale(1.05)
- Focus: Gold outline
- Loading: Pulse animation

**Form Inputs:**
- Default: Border-gray-200
- Focus: Border-wine-600 + ring
- Error: Border-red-500
- Success: Border-green-500

---

## 10. Icons & Imagery

### Icon System
Using emoji icons for simplicity:
- Wine: 🍷
- Grape: 🍇
- Location: 📍
- Building: 🏛️
- Star: ⭐
- Fire: 🔥
- Trophy: 🏆
- Cart: 🛒

### Image Guidelines

**Wine Bottle Photos:**
- Source: Real affiliate partner images
- Aspect ratio: Portrait (2:3 or taller)
- Format: WebP with JPG fallback
- Loading: Next.js Image optimization
- Placeholder: Gradient background + 🍷 emoji

**Responsive Images:**
```tsx
<Image
  src={wine.image}
  alt={wine.name}
  fill
  className="object-contain"
  sizes="(max-width: 768px) 100vw, 50vw"
  priority={isFeatured}
/>
```

---

## 11. Performance

### Optimization Strategies

**Code Splitting:**
- Route-based splitting (Next.js automatic)
- Component lazy loading for heavy charts

**Image Optimization:**
- Next.js Image component
- Lazy loading below the fold
- WebP format with fallbacks

**CSS:**
- Tailwind purge in production
- Critical CSS inlined
- Minimal custom CSS

**Animations:**
- GPU-accelerated (transform, opacity)
- Reduced motion support
- Disabled during scroll

---

## 12. Design Patterns

### Empty States
```tsx
<EmptyState
  icon="🔍"
  title="No wines found"
  message="Try adjusting your filters"
  action={{ label: "Reset", onClick: resetFilters }}
/>
```

### Loading States
- Skeleton loaders (not spinners) for lists
- Spinner for page transitions
- Shimmer effect for image placeholders

### Error States
- User-friendly messages
- Retry actions
- Fallback content

### Success States
- Toast notifications (future)
- Inline success messages
- Visual confirmations

---

## 13. Branding

### Voice & Tone
- Friendly, approachable
- Wine-knowledgeable but not pretentious
- Value-focused (deals, savings)
- Trustworthy (real data, real photos)

### Copy Guidelines
- Clear, concise headlines
- Action-oriented CTAs
- Feature benefits over features
- Price transparency

---

## 14. Implementation Checklist

### New Component Checklist
- [ ] Mobile-first responsive design
- [ ] Minimum 44px touch targets
- [ ] 16px input font size (iOS)
- [ ] Keyboard accessible
- [ ] Screen reader tested
- [ ] Color contrast validated
- [ ] Loading state designed
- [ ] Error state designed
- [ ] Empty state designed
- [ ] Animation respects reduced motion
- [ ] Works without JavaScript

### Page Checklist
- [ ] Meta tags (title, description)
- [ ] Open Graph images
- [ ] Semantic HTML
- [ ] Logical heading hierarchy
- [ ] Skip to main content link
- [ ] Mobile tested on real device
- [ ] Lighthouse score > 90
- [ ] No console errors

---

## 15. File Structure

```
/root/Projects/wine-finder-next/
├── app/
│   ├── page.tsx                 # Homepage
│   ├── search/page.tsx          # Search results
│   ├── wine/[id]/page.tsx       # Wine detail
│   ├── layout.tsx               # Root layout
│   └── globals.css              # Global styles
├── components/
│   ├── WineCard.tsx             # Wine card component
│   ├── SearchBar.tsx            # Search input
│   ├── FilterBar.tsx            # Filters
│   ├── SortDropdown.tsx         # Sort options
│   ├── PriceChart.tsx           # Price history chart
│   ├── WhereToBuy.tsx           # Affiliate partners
│   ├── RelatedWines.tsx         # Related wines
│   ├── FeaturedSection.tsx      # Featured wines
│   ├── SkeletonLoader.tsx       # Loading skeleton
│   └── EmptyState.tsx           # Empty state
├── lib/services/                # API services
├── tailwind.config.ts           # Tailwind config
└── DESIGN_SYSTEM.md            # This file
```

---

## 16. Resources

### Design Tools
- Tailwind CSS: https://tailwindcss.com
- Next.js Image: https://nextjs.org/docs/api-reference/next/image
- Recharts: https://recharts.org (for price charts)

### Accessibility
- WCAG Guidelines: https://www.w3.org/WAI/WCAG21/quickref/
- WebAIM Contrast Checker: https://webaim.org/resources/contrastchecker/
- Lighthouse: Built into Chrome DevTools

### Testing
- Mobile: Chrome DevTools responsive mode + real devices
- Screen Readers: NVDA (Windows), VoiceOver (Mac/iOS)
- Keyboard: Tab through entire interface

---

## Contact

Design System maintained by Steve Abrams
steve@designerwallcoverings.com

Last Updated: 2025-11-15
Version: 1.0.0