CLAUDE.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 
5## Development Commands
6 
7### Core Development
8- `npm run dev` - Start development server on port 8080
9- `npm run build` - Create production build
10- `npm run build:dev` - Create development build
11- `npm run lint` - Run ESLint linter
12- `npm run preview` - Preview production build locally
13 
14### Package Management
15- `npm install` - Install dependencies (or use `bun install` for faster installs)
16 
17## Architecture & Structure
18 
19### Framework Stack
20- **React 18.3.1** with TypeScript for UI
21- **Vite 5.4.1** as build tool with SWC for fast compilation
22- **shadcn/ui** component library built on Radix UI primitives
23- **Tailwind CSS 3.4.11** for styling with custom design system
24- **React Router DOM v6** for client-side routing
25- **TanStack Query** for server state management
26- **React Hook Form + Zod** for form handling and validation
27 
28### Key Architecture Patterns
29 
30#### Component Organization & Structure
31- `src/components/ui/` - Pre-built shadcn/ui components (40+ available, READ-ONLY)
32- `src/components/common/` - Reusable components (20-100 lines each)
33- `src/components/forms/` - Form-specific components
34- `src/components/features/` - Feature-specific components
35- `src/pages/` - Route-level page components
36- `src/hooks/` - Custom React hooks including `use-mobile.tsx` and `use-toast.ts`
37- `src/lib/utils.ts` - Utility functions with Tailwind class merging via `cn()` function
38- `src/lib/types.ts` - Shared TypeScript types and interfaces
39- `src/lib/constants.ts` - Application constants
40- `src/lib/validations/` - Zod validation schemas
41 
42#### Critical Architecture Rules
43- **Component Size Limit**: Never exceed 300 lines per component
44- **Composition Over Complexity**: Build complex UI from smaller, focused components
45- **Single Responsibility**: Each component should have one clear purpose
46- **Extract Reusable Logic**: Use custom hooks instead of duplicating code
47- **Service Layer Pattern**: No inline API calls in components - use service layer in `src/lib/`
48 
49#### Import Aliases (configured in vite.config.ts)
50- `@/` maps to `./src/`
51- `@/components` for components
52- `@/lib` for utilities
53- `@/hooks` for custom hooks
54 
55#### Routing Structure
56Routes are defined in `src/App.tsx`. Add new routes above the catch-all `*` route:
57```tsx
58<Routes>
59  <Route path="/" element={<Index />} />
60  {/* ADD NEW ROUTES HERE */}
61  <Route path="*" element={<NotFound />} />
62</Routes>
63```
64 
65### Design System Integration
66 
67This project uses a sophisticated design system based on comprehensive instructions in `.github/instructions/` and `.cursor/rules/`. Key principles:
68 
69#### shadcn/ui Components
70Over 40 pre-built components available in `src/components/ui/`:
71- **Layout**: `card`, `separator`, `sheet`, `sidebar`, `tabs`, `accordion`
72- **Forms**: `button`, `input`, `form`, `select`, `checkbox`, `radio-group`
73- **Overlays**: `dialog`, `alert-dialog`, `drawer`, `popover`, `tooltip`
74- **Data Display**: `table`, `badge`, `avatar`, `chart`, `carousel`
75 
76#### Styling Conventions & Quality Standards
77- Use Tailwind classes following the project's design system
78- Generous spacing: `py-16 lg:py-24` for sections
79- Consistent rhythm: `space-y-4 lg:space-y-6` for content
80- Mobile-first responsive design approach
81- Premium, sophisticated visual hierarchy with purposeful color psychology
82- **Accessibility**: Maintain WCAG 2.1 AA contrast ratios (4.5:1 minimum)
83- **Never ship** without running `npm run lint` - must pass without errors
84- **Industry-specific designs**: Adapt visual identity, emotional tone, and color psychology to target audience
85- **Design Philosophy**: Create unique, custom-crafted interfaces that feel premium and engaging
86- **Color Strategy**: Use colors intentionally to evoke the right emotions and enhance user experience
87 
88### Configuration Files
89 
90- `vite.config.ts` - Vite configuration with path aliases and port 8080
91- `components.json` - shadcn/ui configuration with default style and slate base color
92- `tailwind.config.ts` - Tailwind configuration with dark mode support
93- `tsconfig.json` - TypeScript configuration with strict mode
94 
95### Environment Variables
96⚠️ **Security**: This is a client-side application. Only use `VITE_` prefixed environment variables for public configuration. Never expose sensitive data like API secrets.
97 
98### Testing & Quality
99- ESLint configured with React and TypeScript rules
100- No test framework currently configured - determine testing approach from codebase if tests are needed
101 
102### Development Patterns & Best Practices
103 
104#### Code Organization
105- Use TypeScript interfaces for type safety - define shared types in `src/lib/types.ts`
106- Implement responsive design mobile-first
107- Follow React Hook Form patterns with Zod validation for forms
108- Use TanStack Query for API state management
109- Import UI components from `@/components/ui/`
110- Use the toast system via `use-toast` hook for notifications
111 
112#### Cursor Rules Integration
113This project includes comprehensive Cursor rules in `.cursor/rules/` that auto-apply based on file context:
114- **Core Rules** (`core.mdc`) - Always active architecture and quality rules
115- **Component Rules** (`components.mdc`) - Auto-loads when editing `src/components/**`
116- **Design Rules** (`design.mdc`) - Auto-loads when editing UI/styling files
117- **Form Rules** (`forms.mdc`) - Auto-loads when editing form components
118- **Hook Rules** (`hooks.mdc`) - Auto-loads when editing `src/hooks/**`
119- **Service Rules** (`services.mdc`) - Auto-loads when editing `src/lib/**`
120 
121Reference with `@rule-name` in prompts (e.g., `@quality` for quality checklist)