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

<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

<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):

<UnitDisplay :value="121" type="speed" />
<!-- Renders: "121 km/h" or "75 mph" based on user preference -->

Rating Display

<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.)