website/NAUTICAL_DESIGN_SYSTEM.md

# HarborSmith Nautical Theme Design System

## Brand Identity
HarborSmith embodies premium maritime elegance with a sophisticated nautical aesthetic. The design language draws inspiration from classic yacht clubs, luxury vessels, and the deep blue waters of the San Francisco Bay.

## Color System

### Primary Palette
```css
/* Core Brand Colors */
--navy-blue: #001f3f;      /* RGB: 0, 31, 63 - Deep maritime authority */
--crimson: #dc143c;        /* RGB: 220, 20, 60 - Premium accent, CTAs */
--warm-amber: #b91c3c;     /* RGB: 185, 28, 60 - Interactive hover states */
--warm-yellow: #ef4444;    /* RGB: 239, 68, 68 - Highlights, badges */
```

### Neutral Colors
```css
/* Background & Surface Colors */
--soft-cream: #f0f4f8;     /* RGB: 240, 244, 248 - Light backgrounds */
--white: #ffffff;          /* RGB: 255, 255, 255 - Primary backgrounds */
--gray-50: #f9fafb;        /* RGB: 249, 250, 251 - Subtle backgrounds */
--gray-100: #f3f4f6;       /* RGB: 243, 244, 246 - Borders */
--gray-200: #e5e7eb;       /* RGB: 229, 231, 235 - Dividers */
```

### Text Colors
```css
/* Typography Colors */
--text-dark: #0a1628;      /* RGB: 10, 22, 40 - Primary text */
--text-light: #4a5568;     /* RGB: 74, 85, 104 - Secondary text */
--text-muted: #6b7280;     /* RGB: 107, 114, 128 - Muted text */
--text-white: #ffffff;     /* RGB: 255, 255, 255 - Inverse text */
```

### Gradient System
```css
/* Brand Gradients */
--gradient-warm: linear-gradient(135deg, #dc143c 0%, #ef4444 100%);
--gradient-sunset: linear-gradient(135deg, #b91c3c 0%, #dc143c 50%, #ef4444 100%);
--gradient-ocean: linear-gradient(135deg, #001f3f 0%, #003366 100%);
--gradient-overlay: linear-gradient(180deg, rgba(0,31,63,0.8) 0%, transparent 100%);
```

## Typography

### Font Families
```css
--font-display: 'Playfair Display', serif;  /* Elegant headers */
--font-sans: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;  /* Clean body text */
```

### Type Scale
| Level | Size | Line Height | Font Weight | Usage |
|-------|------|-------------|-------------|-------|
| Display | 72px | 1.1 | 700 | Hero headlines |
| H1 | 56px | 1.2 | 700 | Page titles |
| H2 | 48px | 1.25 | 600 | Section headers |
| H3 | 36px | 1.3 | 600 | Subsections |
| H4 | 24px | 1.35 | 500 | Card titles |
| H5 | 20px | 1.4 | 500 | Subheadings |
| Body Large | 20px | 1.6 | 400 | Lead paragraphs |
| Body | 16px | 1.5 | 400 | Default text |
| Small | 14px | 1.4 | 400 | Captions, meta |
| XSmall | 12px | 1.3 | 400 | Labels, badges |

### Font Weights
- Light: 300 (Subtle text)
- Regular: 400 (Body content)
- Medium: 500 (Emphasis)
- Semibold: 600 (Headers)
- Bold: 700 (Strong emphasis)
- Black: 900 (Display only)

## Spacing System

### Base Unit: 4px
```css
--space-0: 0px;
--space-1: 4px;
--space-2: 8px;
--space-3: 12px;
--space-4: 16px;
--space-5: 20px;
--space-6: 24px;
--space-8: 32px;
--space-10: 40px;
--space-12: 48px;
--space-16: 64px;
--space-20: 80px;
--space-24: 96px;
--space-32: 128px;
```

### Component Spacing
- **Inline elements**: 8px (space-2)
- **Related elements**: 16px (space-4)
- **Section spacing**: 48px mobile, 80px desktop
- **Page padding**: 16px mobile, 32px tablet, 48px desktop

## Layout System

### Container Widths
```css
--container-xs: 480px;   /* Mobile */
--container-sm: 640px;   /* Small tablet */
--container-md: 768px;   /* Tablet */
--container-lg: 1024px;  /* Desktop */
--container-xl: 1280px;  /* Wide desktop */
--container-2xl: 1536px; /* Ultra wide */
```

### Breakpoints
```css
/* Mobile First Approach */
@media (min-width: 640px) { /* sm */ }
@media (min-width: 768px) { /* md */ }
@media (min-width: 1024px) { /* lg */ }
@media (min-width: 1280px) { /* xl */ }
@media (min-width: 1536px) { /* 2xl */ }
```

### Grid System
- **Columns**: 12-column grid
- **Gap**: 16px mobile, 24px tablet, 32px desktop
- **Margins**: 16px mobile, 32px desktop

## Border System

### Border Radius
```css
--radius-none: 0px;
--radius-sm: 4px;     /* Inputs, small elements */
--radius-md: 8px;     /* Cards, buttons */
--radius-lg: 16px;    /* Modals, large cards */
--radius-xl: 24px;    /* Hero sections */
--radius-full: 9999px; /* Pills, avatars */
```

### Border Widths
```css
--border-0: 0px;
--border: 1px;
--border-2: 2px;
--border-4: 4px;
```

## Shadow System

### Elevation Shadows
```css
--shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
--shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
--shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1);
--shadow-xl: 0 20px 25px -5px rgba(0, 0, 0, 0.1);
--shadow-2xl: 0 25px 50px -12px rgba(0, 0, 0, 0.25);
```

### Color Shadows
```css
--shadow-warm: 0 10px 30px rgba(220, 20, 60, 0.3);
--shadow-ocean: 0 10px 30px rgba(0, 31, 63, 0.2);
--shadow-soft: 0 10px 40px rgba(0, 0, 0, 0.08);
```

## Animation System

### Timing
```css
--duration-instant: 100ms;
--duration-fast: 200ms;
--duration-normal: 300ms;
--duration-slow: 500ms;
--duration-slower: 800ms;
```

### Easing Functions
```css
--ease-linear: linear;
--ease-in: cubic-bezier(0.4, 0, 1, 1);
--ease-out: cubic-bezier(0, 0, 0.2, 1);
--ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);
--ease-bounce: cubic-bezier(0.68, -0.55, 0.265, 1.55);
```

### Standard Transitions
```css
/* Default transition for all interactive elements */
transition: all var(--duration-normal) var(--ease-in-out);

/* Hover effects */
transform: translateY(-2px);
box-shadow: var(--shadow-lg);

/* Active/pressed state */
transform: scale(0.98);
```

## Component Patterns

### Buttons

#### Primary Button
```css
background: var(--gradient-warm);
color: white;
padding: 12px 24px;
border-radius: var(--radius-md);
font-weight: 600;
transition: all var(--duration-normal);
box-shadow: var(--shadow-warm);
```

#### Secondary Button
```css
background: transparent;
color: var(--navy-blue);
border: 2px solid var(--navy-blue);
padding: 10px 22px;
border-radius: var(--radius-md);
```

#### Button States
- **Hover**: Elevated shadow, scale(1.02)
- **Active**: scale(0.98)
- **Disabled**: opacity(0.5), cursor(not-allowed)

### Cards

#### Base Card
```css
background: white;
border-radius: var(--radius-md);
padding: var(--space-6);
box-shadow: var(--shadow-md);
transition: all var(--duration-normal);
```

#### Card Hover
```css
transform: translateY(-4px);
box-shadow: var(--shadow-xl);
```

### Form Elements

#### Input Fields
```css
background: white;
border: 1px solid var(--gray-200);
border-radius: var(--radius-sm);
padding: 10px 16px;
font-size: 16px;
transition: all var(--duration-fast);
```

#### Input Focus
```css
border-color: var(--crimson);
box-shadow: 0 0 0 3px rgba(220, 20, 60, 0.1);
outline: none;
```

### Navigation

#### Desktop Nav
- Transparent on hero sections
- White background on scroll
- Backdrop blur effect
- Smooth transitions

#### Mobile Nav
- Slide-down animation
- Full-width menu
- Touch-friendly targets (min 44px)

## Icons & Imagery

### Icon System
- **Library**: Lucide Icons
- **Size Scale**: 16px, 20px, 24px, 32px
- **Stroke Width**: 1.5px default, 2px for emphasis
- **Color**: Inherit from parent

### Image Treatment
- **Border Radius**: var(--radius-md) for cards
- **Aspect Ratios**: 16:9 (hero), 4:3 (cards), 1:1 (avatars)
- **Loading**: Blur-up technique with LQIP
- **Overlays**: Gradient overlays for text legibility

## Responsive Design

### Mobile First Principles
1. Start with mobile layout
2. Enhance for larger screens
3. Touch targets minimum 44px
4. Readable font sizes (min 14px)
5. Appropriate spacing for touch

### Breakpoint Behaviors
- **Mobile (< 640px)**: Single column, stacked layout
- **Tablet (640px - 1024px)**: 2-column grids, side navigation
- **Desktop (> 1024px)**: Multi-column, full features

## Accessibility

### Color Contrast
- Normal text: 4.5:1 minimum
- Large text: 3:1 minimum
- Interactive elements: 3:1 minimum
- Focus indicators: Visible outline

### Interactive Elements
- Keyboard navigable
- Focus indicators
- ARIA labels
- Semantic HTML
- Skip navigation links

## Performance Guidelines

### Image Optimization
- WebP format with JPEG fallback
- Responsive images with srcset
- Lazy loading below fold
- Blur-up placeholders

### CSS Optimization
- Critical CSS inline
- Unused CSS removed
- CSS custom properties for theming
- Minimal specificity

### Animation Performance
- Prefer transform and opacity
- Use will-change sparingly
- 60fps target
- Reduce motion preference support

## Implementation Notes

### CSS Architecture
- Utility-first with Tailwind CSS v4
- Component classes for complex patterns
- CSS custom properties for dynamic values
- Scoped styles in Vue components

### Component Structure
```vue
<template>
  <!-- Semantic HTML -->
</template>

<script setup lang="ts">
// TypeScript logic
</script>

<style scoped>
/* Component-specific styles */
</style>
```

### Naming Conventions
- **Components**: PascalCase (HeroVideo.vue)
- **Composables**: camelCase with 'use' prefix (useTheme.ts)
- **CSS Classes**: kebab-case (nav-link)
- **CSS Variables**: kebab-case with prefix (--space-4)

## Usage Examples

### Button Component
```vue
<ThemedButton variant="primary" size="lg">
  Book Charter
  <Icon name="lucide:arrow-right" class="ml-2" />
</ThemedButton>
```

### Card Component
```vue
<VesselCard
  :image="yacht.image"
  :title="yacht.name"
  :price="yacht.price"
  :capacity="yacht.capacity"
  @click="selectVessel"
/>
```

### Typography
```vue
<h1 class="font-display text-5xl font-bold text-navy">
  Your Adventure Awaits
</h1>
<p class="text-lg text-gray-600 leading-relaxed">
  Experience luxury yacht charters in the San Francisco Bay
</p>
```

---

This design system ensures consistency, accessibility, and performance across the HarborSmith platform while maintaining the premium nautical aesthetic that defines the brand.