playchoo-manager-nextjs/CLAUDE.md

# Claude Code Assistant Guidelines for Playchoo NextJS Project

## Component Development Principles

### 1. Always Create Reusable Components

**Before writing any component code, ask yourself:**
- Is this UI pattern used elsewhere or likely to be used elsewhere?
- Can this be broken down into smaller, reusable pieces?
- Does a similar component already exist that can be extended?

**Component Creation Checklist:**
1. Check if a similar component exists: `grep -r "ComponentName" src/components/`
2. If creating new UI patterns, extract them into separate components
3. Place reusable components in appropriate directories:
   - `/src/components/` - General reusable components
   - `/src/components/skeletons/` - Skeleton components
   - `/src/components/modals/` - Modal components

### 2. Skeleton Component Guidelines

**Skeletons ARE components - apply the same reusability principles:**
- Every skeleton pattern should be extracted into a reusable component
- Even simple loading elements should be components if used more than once
- Never write inline skeleton JSX - always extract it

**Skeleton Best Practices:**
1. ALWAYS extract skeleton patterns into separate components:
   ```tsx
   // Good - Reusable components for EVERYTHING
   PlayerCardSkeleton.tsx
   CourtVisualizationSkeleton.tsx
   HeaderSkeleton.tsx
   TextLineSkeleton.tsx
   AvatarSkeleton.tsx
   ButtonSkeleton.tsx
   
   // Bad - ANY inline skeleton
   <div className="h-4 bg-slate-200 animate-pulse"></div>
   
   // Good - Even simple elements become components
   <TextLineSkeleton width="w-24" />
   <AvatarSkeleton size="md" />
   ```

2. Match the exact structure of the real component:
   - Same padding and margins
   - Same grid/flex layouts
   - Same responsive breakpoints
   - Same container structure

3. Show static text that doesn't require data:
   - Page titles
   - Section headers
   - Button labels
   - Navigation elements

4. Reuse skeleton components within other skeletons:
   ```tsx
   // BookingDetailSkeleton using other skeleton components
   <TimelineTimeSlotHeader ... />
   <CourtWithPlayersSkeleton />
   <PlayerListSkeleton />
   ```

### 3. Component Extraction Rules

**Extract a new component when you see:**
1. ANY repeated JSX pattern (even 1 line repeated 2+ times)
2. Complex nested structures that could be named
3. ANY loading/skeleton state (no exceptions)
4. UI patterns that represent a "thing" (player, court, booking, etc.)
5. Any JSX that could be given a meaningful name

**Example of proper extraction:**
```tsx
// Instead of repeating this pattern:
<div className="flex items-center space-x-3 p-3 bg-slate-50 rounded-xl">
  <div className="w-10 h-10 bg-slate-200 rounded-full animate-pulse"></div>
  <div className="flex-1">
    <div className="h-4 bg-slate-200 rounded-lg w-24 mb-1 animate-pulse"></div>
    <div className="h-3 bg-slate-200 rounded-lg w-16 animate-pulse"></div>
  </div>
</div>

// Create PlayerItemSkeleton:
export function PlayerItemSkeleton() {
  return (
    <div className="flex items-center space-x-3 p-3 bg-slate-50 rounded-xl">
      <div className="w-10 h-10 bg-slate-200 rounded-full animate-pulse"></div>
      <div className="flex-1">
        <div className="h-4 bg-slate-200 rounded-lg w-24 mb-1 animate-pulse"></div>
        <div className="h-3 bg-slate-200 rounded-lg w-16 animate-pulse"></div>
      </div>
    </div>
  );
}

// Then use it:
{[1, 2, 3, 4].map(i => <PlayerItemSkeleton key={i} />)}
```

### 4. Component Naming Conventions

- **Skeletons**: `[ComponentName]Skeleton.tsx` (e.g., `PlayerCardSkeleton.tsx`)
- **Modals**: `[Purpose]Modal.tsx` (e.g., `LoginPromptModal.tsx`)
- **Cards**: `[Content]Card.tsx` (e.g., `BookingCourtCard.tsx`)
- **Lists**: `[Item]List.tsx` (e.g., `PlayersList.tsx`)
- **Headers**: `[Context]Header.tsx` (e.g., `TimelineTimeSlotHeader.tsx`)

### 5. Before Creating Any Component

**Run these checks:**
```bash
# Check for similar components
grep -r "similar-pattern" src/components/

# Check for existing skeletons
ls src/components/skeletons/

# Check where the pattern is used
grep -r "className.*similar-styles" src/
```

### 6. Component Composition Patterns

**Prefer composition over duplication:**
```tsx
// Good - Composed from smaller parts
<Card>
  <CardHeader>
    <TimelineTimeSlotHeader {...props} />
  </CardHeader>
  <CardBody>
    <CourtWithPlayersSkeleton />
    <PlayersList players={players} />
  </CardBody>
</Card>

// Bad - Everything inline
<div className="...">
  <div className="...">
    {/* 50 lines of header JSX */}
  </div>
  <div className="...">
    {/* 100 lines of body JSX */}
  </div>
</div>
```

## Project-Specific Guidelines

### IMPORTANT: Theme System and Color Usage

**⚠️ CRITICAL: Always use themable colors - NEVER hardcode purple/indigo/pink values**

The Playchoo app has a comprehensive theme system that supports multiple color schemes. When adding or modifying any UI elements:

1. **USE THEMABLE COLOR CLASSES:**
   - ✅ GOOD: `bg-purple-600`, `from-indigo-600`, `text-pink-600` (these are automatically themed)
   - ❌ BAD: `#9333ea`, `rgb(147, 51, 234)`, or any hardcoded hex/rgb values
   
2. **FOR GRADIENTS:**
   - ✅ GOOD: `from-indigo-600 via-purple-600 to-pink-600`
   - ❌ BAD: Custom gradient definitions with hardcoded colors

3. **AVAILABLE THEMED COLORS:**
   - **Purple shades**: purple-50 through purple-900 (primary theme color)
   - **Indigo shades**: indigo-50 through indigo-900 (secondary theme color)
   - **Pink shades**: pink-50 through pink-900 (accent theme color)
   - These automatically change based on the active theme (Blue Ocean, Green Nature, Sunset, Midnight)

4. **CHECK BEFORE ADDING COLORS:**
   ```bash
   # Check if similar themed elements exist
   grep -r "from-purple\|to-purple\|bg-purple" src/
   grep -r "from-indigo\|to-indigo\|bg-indigo" src/
   grep -r "from-pink\|to-pink\|bg-pink" src/
   ```

5. **THEME FILES:**
   - CSS variables: `src/styles/theme.css`
   - TypeScript config: `src/config/theme.ts`
   - Calendario colors: `src/utils/calendarioConfig.ts`

The theme system ensures consistency across all color schemes and allows users to switch themes seamlessly. Every purple, indigo, or pink color in the app should be themable.

### UI Consistency
- Always use the existing color scheme and gradients (themable colors only)
- Match the border radius patterns (rounded-xl, rounded-2xl)
- Use consistent spacing (p-3, p-4, p-6, p-8)
- Follow the existing animation patterns (animate-pulse, animate-fadeIn, animate-slideIn)

### Skeleton Components Must:
1. Show real text for static labels (using `useTranslation` hook)
2. Match the exact layout of the real component
3. Use the same responsive breakpoints
4. Include proper padding and margin structure
5. Reuse other skeleton components where applicable

### Performance Considerations
- Keep skeleton components lightweight
- Avoid complex calculations in skeleton components
- Use CSS animations rather than JS animations
- Lazy load heavy components when possible

## Commands to Run After Creating Components

```bash
# After creating/modifying components, always run:
npm run lint

# Check for TypeScript errors:
npx tsc --noEmit

# Ensure all imports are correct:
grep -r "ComponentName" src/
```

## Remember
**Every time you write JSX, ask: "Should this be a component?"** (This includes ALL skeleton/loading JSX)
**Every piece of skeleton JSX MUST be a component - no exceptions**
**Every time you copy-paste code, stop and extract it into a component instead**

## The Golden Rule
**If you can name it, it should be a component.**
- "Loading text line" → `TextLineSkeleton`
- "Pulsing avatar" → `AvatarSkeleton`  
- "Player card skeleton" → `PlayerCardSkeleton`
- "Loading button" → `ButtonSkeleton`

**No inline skeletons. Ever. Even for "simple" things.**

## Git Commit Messages

**NEVER add these lines to commit messages:**
- ❌ `🤖 Generated with [Claude Code](https://claude.com/claude-code)`
- ❌ `Co-Authored-By: Claude <noreply@anthropic.com>`

**Commit messages should be:**
- Clear and concise
- Describe what was changed and why
- Free of AI attribution or branding