Epic 1: Project Setup & Design System

[Vitalisn4]

Issue #1: Initialize React + Vite + TypeScript Project

Labels: epic-1, setup, frontend, priority-high
Milestone: Epic 1 - Project Setup
Dependencies: None

Description:
Set up the foundation for the VividShift frontend application using modern React tooling.

Acceptance Criteria:

• Create new frontend/ directory in project root
• Initialize Vite project with React 18 + TypeScript template
• Configure TypeScript with strict mode enabled
• Set up ESLint and Prettier with recommended configs
• Configure path aliases (@/ for src directory)
• Verify dev server runs successfully on localhost:5173
• Add .env.example with required environment variables
• Update root .gitignore to exclude frontend build artifacts

Technical Notes:

• Use npm create vite@latest frontend -- --template react-ts
• Ensure Node.js 18+ is required
• Add scripts to root package.json for convenience

---

Issue #2: Configure Tailwind CSS with Custom Design Tokens

Labels: epic-1, styling, design-system, priority-high
Milestone: Epic 1 - Project Setup
Dependencies: #1

Description:
Set up Tailwind CSS with custom design tokens matching the VividShift design system.

Acceptance Criteria:

• Install and configure Tailwind CSS v3+
• Create tailwind.config.ts with custom theme
• Define color palette using CSS variables:
  • Primary (Teal/Cyan: 180 70% 45%)
  • Secondary (Warm coral: 15 80% 60%)
  • Accent (Cool blue: 210 80% 55%)
  • Background (Off-white: 210 20% 98%)
  • Surface (Pure white)
  • Muted (Soft gray: 210 15% 90%)
  • Success (Green: 150 60% 45%)
  • Warning (Amber: 40 90% 50%)
• Configure spacing scale (base unit: 4px)
• Configure border radius (12px cards, 8px buttons, 6px inputs)
• Set up typography scale
• Verify Tailwind classes work in a test component

Technical Notes:

• Use @tailwindcss/forms plugin for form styling
• Configure content paths to scan all React files

---

Issue #3: Set Up shadcn/ui with Custom Theme

Labels: epic-1, components, ui-library, priority-high
Milestone: Epic 1 - Project Setup
Dependencies: #2

Description:
Install and configure shadcn/ui component library with VividShift branding.

Acceptance Criteria:

• Initialize shadcn/ui in the project
• Configure components.json with custom theme colors
• Install base dependencies (class-variance-authority, clsx, tailwind-merge)
• Create lib/utils.ts with cn() utility function
• Verify components can be added via CLI (npx shadcn-ui@latest add button)
• Customize default theme to match VividShift color palette
• Document component installation process in README

Technical Notes:

• Follow shadcn/ui installation guide
• Ensure components are installed in src/components/ui/
• Use CSS variables for theming

---

Issue #4: Create Color Palette CSS Variables

Labels: epic-1, styling, design-system, priority-medium
Milestone: Epic 1 - Project Setup
Dependencies: #2

Description:
Define CSS custom properties for the design system color palette.

Acceptance Criteria:

• Create src/styles/colors.css or add to main CSS file
• Define all color tokens as CSS variables:

  --primary: hsl(180, 70%, 45%);
  --secondary: hsl(15, 80%, 60%);
  --accent: hsl(210, 80%, 55%);
  --background: hsl(210, 20%, 98%);
  --surface: hsl(0, 0%, 100%);
  --muted: hsl(210, 15%, 90%);
  --success: hsl(150, 60%, 45%);
  --warning: hsl(40, 90%, 50%);

• Create dark mode variants (optional, for future)
• Import color variables in main CSS entry point
• Verify variables are accessible in components
• Document color usage in design system docs

---

Issue #5: Configure Typography and Spacing Scales

Labels: epic-1, styling, design-system, priority-medium
Milestone: Epic 1 - Project Setup
Dependencies: #2

Description:
Set up typography system with Inter/Plus Jakarta Sans and consistent spacing.

Acceptance Criteria:

• Install and configure Inter font (Google Fonts or local)
• Install Plus Jakarta Sans for headings (optional)
• Install JetBrains Mono for monospace (dates, IDs)
• Configure font families in Tailwind config
• Define typography scale (text-xs through text-4xl)
• Set up spacing scale (4px base unit: 1, 2, 3, 4, 6, 8, 12, 16, 20, 24, 32, 40, 48, 64)
• Create typography utility classes
• Add example typography showcase page/component

Technical Notes:

• Use @fontsource packages or Google Fonts
• Ensure fonts load efficiently (preload, font-display)

---

Issue #6: Set Up Framer Motion for Animations

Labels: epic-1, animations, dependencies, priority-medium
Milestone: Epic 1 - Project Setup
Dependencies: #1

Description:
Install and configure Framer Motion for smooth animations throughout the app.

Acceptance Criteria:

• Install framer-motion package
• Create animation variants file (src/lib/animations.ts)
• Define common animation presets:
  • Page transitions (fade + slide)
  • Card hover (lift + shadow)
  • Modal open/close (scale + fade)
  • Success feedback (checkmark)
• Create reusable animation components/wrappers
• Document animation usage patterns
• Add example animated component

Technical Notes:

• Keep animations performant (use will-change where needed)
• Respect prefers-reduced-motion media query

---

Issue #7: Create Base Layout Components

Labels: epic-1, components, layout, priority-high
Milestone: Epic 1 - Project Setup
Dependencies: #3, #6

Description:
Build foundational layout components (DashboardLayout, PageHeader, Modal).

Acceptance Criteria:

• Create DashboardLayout component with:
  • Sidebar navigation
  • Main content area
  • Responsive behavior (collapsible sidebar on mobile)
• Create PageHeader component with:
  • Title and description props
  • Optional action buttons
  • Breadcrumb support (optional)
• Create Modal/Dialog component using shadcn/ui:
  • Header, body, footer sections
  • Close button
  • Backdrop overlay
  • Keyboard navigation (ESC to close)
• Add responsive breakpoint handling
• Ensure accessibility (ARIA labels, focus management)
• Add loading states support

Technical Notes:

• Use shadcn/ui Dialog component as base
• Implement proper focus trapping in modals

---