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:

   // 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:

   // 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:

// 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:

# 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:

// 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:

   # 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

# 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