thrillwiki_django_no_react/.agent/rules/design-system.md

# ThrillWiki Design System Rules

Visual identity, colors, typography, and styling guidelines for ThrillWiki UI.

## Brand Identity

- **Name**: ThrillWiki (optional "(Beta)" suffix during preview)
- **Tagline**: The Ultimate Theme Park Database
- **Personality**: Enthusiastic, trustworthy, community-driven
- **Visual Style**: Modern, clean, subtle gradients, smooth animations, card-based layouts

## Color System

### Semantic Color Tokens (use these, not raw hex values)

| Token | Purpose | Usage |
|-------|---------|-------|
| `--background` | Page background | Main content area |
| `--foreground` | Primary text | Body text, headings |
| `--primary` | Interactive elements | Buttons, links |
| `--secondary` | Secondary UI | Secondary buttons |
| `--muted` | Subdued content | Hints, disabled states |
| `--accent` | Highlights | Focus rings, special callouts |
| `--destructive` | Danger actions | Delete buttons, errors |
| `--success` | Positive feedback | Success messages, confirmations |
| `--warning` | Caution | Alerts, warnings |

### Status Colors (Entity Badges)
- **Operating**: Green (`--success`)
- **Closed**: Red (`--destructive`)
- **Under Construction**: Amber (`--warning`)

### Dark Mode
- Automatically supported via CSS variables
- Reduce contrast (use off-white, not pure white)
- Replace shadows with subtle glows
- Slightly dim images

## Typography

### Font
- **Primary Font**: Inter (Sans-Serif)
- **Weights**: 400 (Regular), 500 (Medium), 600 (Semibold), 700 (Bold)
- **Fallback**: system-ui, sans-serif

### Type Scale

| Size | Name | Usage |
|------|------|-------|
| 48px | Display | Hero headlines |
| 36px | H1 | Page titles |
| 30px | H2 | Section headers |
| 24px | H3 | Card titles |
| 20px | H4 | Subheadings |
| 16px | Body | Default text |
| 14px | Small | Secondary text |
| 12px | Caption | Labels, hints |

### Text Classes (Tailwind)
```
Page Title:    text-4xl font-bold
Section Header: text-2xl font-semibold
Card Title:    text-lg font-medium
Body:          text-base
Caption:       text-sm text-muted-foreground
```

## Spacing System

### Base Unit
- 4px base unit
- All spacing is multiples of 4

### Spacing Scale

| Token | Size | Usage |
|-------|------|-------|
| `space-1` (p-1) | 4px | Tight gaps |
| `space-2` (p-2) | 8px | Icon gaps |
| `space-3` (p-3) | 12px | Small padding |
| `space-4` (p-4) | 16px | Default padding |
| `space-6` (p-6) | 24px | Section gaps |
| `space-8` (p-8) | 32px | Large gaps |
| `space-12` (p-12) | 48px | Section margins |

## Border Radius

| Token | Size | Usage |
|-------|------|-------|
| `rounded-sm` | 4px | Small elements |
| `rounded` | 8px | Buttons, inputs |
| `rounded-lg` | 12px | Cards |
| `rounded-xl` | 16px | Large cards, modals |
| `rounded-full` | 9999px | Pills, avatars |

## Layout

### Max Content Width
- Main content: `max-w-7xl` (1280px)
- Centered with `mx-auto`
- Responsive padding: `px-4 md:px-6 lg:px-8`

### Grid System
- Desktop (1024px+): 4 columns
- Tablet (768px+): 2 columns
- Mobile (<768px): 1 column

```html
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-6">
```

## Component Patterns

### Cards
- Background: `bg-card`
- Border: `border border-border`
- Radius: `rounded-lg`
- Padding: `p-4` or `p-6`
- Interactive cards: Add `hover:shadow-md transition-shadow cursor-pointer`

### Buttons
| Variant | Classes |
|---------|---------|
| Primary | `bg-primary text-primary-foreground hover:bg-primary/90` |
| Secondary | `bg-secondary text-secondary-foreground hover:bg-secondary/80` |
| Outline | `border border-input bg-background hover:bg-accent` |
| Ghost | `hover:bg-accent hover:text-accent-foreground` |
| Destructive | `bg-destructive text-destructive-foreground hover:bg-destructive/90` |

### Inputs
- Border: `border border-input`
- Focus: `focus:ring-2 focus:ring-primary focus:border-transparent`
- Error: `border-destructive focus:ring-destructive`

### Badges
```html
<span class="inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium bg-green-100 text-green-800">
  Operating
</span>
```

## Icons

- **Library**: Lucide icons (via `lucide-vue-next`)
- **Default Size**: 24px (w-6 h-6)
- **Stroke Width**: 1.5px
- **Color**: Inherit from text color

Common icons:
- Search, Menu, User, Heart, Star, MapPin, Calendar, Camera, Edit, Trash, Check, X, ChevronRight, ExternalLink

## Responsive Breakpoints

| Breakpoint | Width | Target |
|------------|-------|--------|
| `sm` | 640px | Large phones |
| `md` | 768px | Tablets |
| `lg` | 1024px | Small laptops |
| `xl` | 1280px | Desktops |
| `2xl` | 1536px | Large screens |

## Accessibility Requirements

- Color contrast: 4.5:1 minimum for normal text
- Focus states: Visible focus ring on all interactive elements
- Motion: Respect `prefers-reduced-motion`
- Screen readers: Proper ARIA labels on interactive elements
- Keyboard: All functionality accessible via keyboard

## ThrillWiki-Specific Patterns

### Unit Display
Always provide unit conversion toggle (metric/imperial):
```vue
<UnitDisplay :value="121" type="speed" />
<!-- Renders: "121 km/h" or "75 mph" based on user preference -->
```

### Rating Display
```vue
<RatingDisplay :rating="4.2" :count="156" />
<!-- Renders: ★★★★☆ 4.2 (156 reviews) -->
```

### Entity Cards
All entity cards (Park, Ride, Company) should show:
- Image (with loading skeleton)
- Name (primary text)
- Key details (secondary text)
- Status badge
- Quick stats (rating, count, etc.)