# HappyParcel Website - Technical Specification

## 1. Tech Stack Overview

| Category | Technology |
|----------|------------|
| Framework | React 18 + TypeScript |
| Build Tool | Vite |
| Styling | Tailwind CSS 3.4 |
| UI Components | shadcn/ui |
| Animation | Framer Motion |
| Icons | Lucide React |
| State | React useState/useRef |

## 2. Tailwind Configuration

```javascript
// tailwind.config.js extensions
{
  theme: {
    extend: {
      colors: {
        primary: {
          DEFAULT: '#5D3FD3',
          dark: '#4C32B5',
          light: '#7B5EE0',
        },
        secondary: '#1E293B',
        background: {
          DEFAULT: '#FFFFFF',
          alt: '#F8F7FC',
          purple: '#5D3FD3',
        },
        text: {
          primary: '#1E293B',
          secondary: '#64748B',
          light: '#94A3B8',
        },
        border: {
          DEFAULT: '#E2E8F0',
          light: '#F1F5F9',
        },
        star: '#22C55E',
      },
      fontFamily: {
        sans: ['Inter', 'system-ui', 'sans-serif'],
      },
      animation: {
        'fade-in': 'fadeIn 0.5s ease-out',
        'slide-up': 'slideUp 0.5s ease-out',
        'float': 'float 3s ease-in-out infinite',
      },
      keyframes: {
        fadeIn: {
          '0%': { opacity: '0' },
          '100%': { opacity: '1' },
        },
        slideUp: {
          '0%': { opacity: '0', transform: 'translateY(20px)' },
          '100%': { opacity: '1', transform: 'translateY(0)' },
        },
        float: {
          '0%, 100%': { transform: 'translateY(0)' },
          '50%': { transform: 'translateY(-10px)' },
        },
      },
    },
  },
}
```

## 3. Component Inventory

### Shadcn/UI Components (Pre-installed)

| Component | Usage | Style Overrides |
|-----------|-------|-----------------|
| Button | CTAs, form submit | Custom purple colors, 8px radius |
| Input | Form fields | 8px radius, custom focus ring |
| Select | Weight type dropdown | Purple focus state |
| Card | Feature cards, testimonials | 12px radius, custom shadow |

### Custom Components

| Component | Props | Description |
|-----------|-------|-------------|
| `TopBar` | none | Contact info bar |
| `Navbar` | none | Main navigation with scroll effect |
| `HeroSection` | none | Title + shipping form |
| `ShippingForm` | none | Rate calculator form |
| `HowItWorksSection` | none | 4-step process display |
| `StepCard` | `step: number, title: string, description: string, image: string, reverse: boolean` | Individual step |
| `PerksSection` | none | Features grid |
| `FeatureCard` | `icon: ReactNode, title: string, description: string` | Feature card |
| `TestimonialsSection` | none | Customer reviews |
| `TestimonialCard` | `quote: string, name: string, avatar: string` | Review card |
| `Footer` | none | Site footer |
| `ScrollReveal` | `children, delay?: number` | Scroll animation wrapper |

### Animation Components

| Component | Purpose |
|-----------|---------|
| `FadeIn` | Opacity fade on mount/scroll |
| `SlideUp` | Slide + fade animation |
| `StaggerContainer` | Parent for staggered children |

## 4. Animation Implementation Plan

| Interaction | Tech Choice | Implementation |
|-------------|-------------|----------------|
| Page Load - Navbar | Framer Motion | `initial={{ opacity: 0 }}` `animate={{ opacity: 1 }}` duration: 0.3s |
| Page Load - Hero Title | Framer Motion | `initial={{ opacity: 0, y: 20 }}` `animate={{ opacity: 1, y: 0 }}` duration: 0.5s, delay: 0.2s |
| Page Load - Form Fields | Framer Motion | `staggerChildren: 0.1`, each field slides up |
| Navbar Scroll Shadow | React State + CSS | `useScroll` hook toggles `scrolled` class at scrollY > 10 |
| Button Hover | Tailwind | `hover:scale-[1.02] hover:bg-primary-dark transition-all duration-200` |
| Card Hover | Tailwind | `hover:-translate-y-1 hover:shadow-lg transition-all duration-300` |
| Link Hover | Tailwind + CSS | `after:` pseudo-element width animation |
| Input Focus | Tailwind | `focus:ring-2 focus:ring-primary/20 focus:border-primary transition-colors` |
| Scroll Reveal - Sections | Framer Motion | `whileInView={{ opacity: 1, y: 0 }}` viewport: `{ once: true, margin: "-100px" }` |
| Scroll Reveal - Cards | Framer Motion | `staggerChildren: 0.15` on container, fade+slide on items |
| Step Images Float | CSS Animation | `animate-float` custom keyframe animation |
| Feature Icon Pulse | Framer Motion | `whileHover={{ scale: 1.1 }}` on icon container |

### Animation Timing Reference

```typescript
const ANIMATION_CONFIG = {
  duration: {
    fast: 0.15,
    normal: 0.3,
    slow: 0.5,
  },
  ease: {
    default: [0.4, 0, 0.2, 1],
    bounce: [0.34, 1.56, 0.64, 1],
    smooth: [0.25, 0.1, 0.25, 1],
  },
  stagger: {
    fast: 0.1,
    normal: 0.15,
    slow: 0.2,
  },
};
```

## 5. Project File Structure

```
/mnt/okcomputer/output/app/
├── public/
│   ├── images/
│   │   ├── asset_1.png
│   │   ├── asset_2.png
│   │   ├── asset_4.png
│   │   ├── asset_5.png
│   │   ├── asset_6.jpg
│   │   ├── alex.jpg
│   │   └── maria.jpg
│   └── favicon.ico
├── src/
│   ├── components/
│   │   ├── ui/              # shadcn/ui components
│   │   ├── TopBar.tsx
│   │   ├── Navbar.tsx
│   │   ├── ShippingForm.tsx
│   │   ├── StepCard.tsx
│   │   ├── FeatureCard.tsx
│   │   ├── TestimonialCard.tsx
│   │   └── ScrollReveal.tsx
│   ├── sections/
│   │   ├── HeroSection.tsx
│   │   ├── HowItWorksSection.tsx
│   │   ├── PerksSection.tsx
│   │   ├── TestimonialsSection.tsx
│   │   └── Footer.tsx
│   ├── hooks/
│   │   └── useScrollPosition.ts
│   ├── lib/
│   │   └── utils.ts
│   ├── App.tsx
│   ├── main.tsx
│   └── index.css
├── index.html
├── tailwind.config.js
├── vite.config.ts
└── package.json
```

## 6. Package Installation List

```bash
# Initialize project (already includes React, TypeScript, Vite, Tailwind, shadcn/ui)
bash /app/.kimi/skills/webapp-building/scripts/init-webapp.sh "HappyParcel"

# Animation library
npm install framer-motion

# Icons (already included with shadcn)
# lucide-react is pre-installed

# No additional packages needed
```

## 7. Responsive Breakpoints

| Breakpoint | Width | Layout Changes |
|------------|-------|----------------|
| Mobile | < 640px | Single column, stacked nav, hidden top bar |
| Tablet | 640-1024px | 2-column footer, condensed spacing |
| Desktop | > 1024px | Full layout as designed |

## 8. Accessibility Requirements

- All interactive elements keyboard accessible
- Focus visible states on all buttons/links
- Alt text on all images
- ARIA labels on icon-only buttons
- Color contrast ratio ≥ 4.5:1 for text
- Respect `prefers-reduced-motion` for animations