blackcanyontickets/reactrebuild0825/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Black Canyon Tickets React Rebuild is a frontend-only React application focused on learning modern UI/UX patterns. This is a complete rebuild using React 18, TypeScript, and Tailwind CSS with a sophisticated glassmorphism design system. The project serves as a production-ready demo of premium ticketing platform interfaces without live database or payment integrations.

🚨 IMPORTANT: Check REBUILD_PLAN.md for current status and Phase 3 roadmap before making any changes.

Development Commands

# Development
npm run dev          # Start development server at localhost:5173
npm run build        # Type check and build for production  
npm run preview      # Preview production build locally

# Code Quality
npm run lint         # Run ESLint on codebase
npm run lint:fix     # Run ESLint with auto-fix
npm run typecheck    # Run TypeScript type checking
npm run quality      # Run all quality checks (typecheck + lint + format:check)
npm run quality:fix  # Run all quality fixes (typecheck + lint:fix + format)

# Testing
npm run test         # Run Playwright end-to-end tests
npm run test:ui      # Run tests with Playwright UI
npm run test:headed  # Run tests with visible browser
npm run test:qa      # Run QA test suite with screenshots
npm run test:smoke   # Run smoke tests for critical paths
npm run test:auth    # Run authentication flow tests
npm run test:theme   # Run theme switching tests
npm run test:responsive # Run responsive design tests
npm run test:components # Run component interaction tests

# Formatting
npm run format       # Format code with Prettier
npm run format:check # Check code formatting

Tech Stack

Core Technologies

• React 18 with TypeScript for strict typing and modern patterns
• Vite for lightning-fast development builds and HMR
• Tailwind CSS with comprehensive design token system
• React Router v6 for client-side routing with protected routes
• Zustand for lightweight, scalable state management

UI/Animation Libraries

• Framer Motion for smooth animations and micro-interactions
• Lucide React for consistent, scalable SVG icons
• React Hook Form with Zod validation for type-safe forms
• Date-fns for date manipulation and formatting

Development Tools

• TypeScript with strict configuration and path aliases
• ESLint with comprehensive React/TypeScript/accessibility rules
• Prettier with Tailwind plugin for code formatting
• Playwright for end-to-end testing with visual regression

Architecture

Design Token System

Comprehensive CSS custom property system supporting:

• Dual Theme Support: Automatic light/dark mode with system preference detection
• Semantic Colors: Background, text, border, and accent colors with proper contrast ratios
• Typography Scale: Consistent font sizes, weights, and line heights
• Spacing System: 8px grid-based spacing tokens
• Glass Effects: Backdrop blur and transparency utilities
• Animation Tokens: Consistent timing functions and keyframes

Component Architecture

• Atomic Design: Reusable primitives (Button, Input) composed into complex organisms
• Token-Based Styling: All components use design tokens for consistent theming
• TypeScript Interfaces: Strict typing for props, state, and component APIs
• Error Boundaries: Graceful error handling at component and route levels
• Accessibility First: WCAG AA compliance built into all components

Route Structure

/ or /dashboard     - Protected dashboard with event overview
/events            - Event management interface (events:read permission)
/tickets           - Ticket management (tickets:read permission)
/customers         - Customer management (customers:read permission) 
/analytics         - Analytics dashboard (analytics:read permission)
/settings          - User account settings
/admin/*           - Admin panel (admin role required)
/login             - Authentication portal
/home              - Public homepage
/showcase          - Design system showcase
/docs              - Theme documentation

Mock Authentication System

Role-based access control with three tiers:

• User: Basic event access and ticket purchasing
• Admin: Event management and organization features
• Super Admin: Full platform administration

File Structure

src/
├── components/
│   ├── ui/                 # Reusable UI primitives
│   │   ├── Button.tsx      # Primary action component with variants
│   │   ├── Input.tsx       # Form input with validation states
│   │   ├── Card.tsx        # Container component with glass effects
│   │   ├── Alert.tsx       # Status message component
│   │   ├── Badge.tsx       # Small status indicators
│   │   └── Select.tsx      # Dropdown selection component
│   ├── layout/             # Layout and navigation
│   │   ├── AppLayout.tsx   # Main application layout wrapper
│   │   ├── Header.tsx      # Top navigation with user menu
│   │   ├── Sidebar.tsx     # Collapsible navigation sidebar
│   │   └── MainContainer.tsx # Content area with proper spacing
│   ├── auth/               # Authentication components
│   │   └── ProtectedRoute.tsx # Route guards with permission checks
│   ├── loading/            # Loading states and skeletons
│   ├── errors/             # Error boundaries and fallback UI
│   ├── events/             # Event-related components
│   ├── tickets/            # Ticketing and purchase components
│   ├── checkout/           # Purchase flow components
│   ├── billing/            # Payment and fee breakdown
│   └── scanning/           # QR scanning components
├── pages/                  # Route components
├── contexts/               # React Context providers
├── hooks/                  # Custom React hooks
├── types/                  # TypeScript type definitions
├── design-tokens/          # Design system token definitions
└── styles/                 # CSS files and utilities

Design System

Theme Configuration

The application supports automatic theme switching with:

• CSS Custom Properties: Token-based design system in /src/design-tokens/
• Tailwind Integration: All tokens available as Tailwind utilities
• WCAG AA Compliance: 4.5:1+ contrast ratios across all color combinations
• Glass Effects: Sophisticated backdrop blur and transparency patterns

Component Usage Patterns

// Design token-based styling
<Button variant="primary" size="lg" className="bg-primary-500 text-primary-text">
  Action Button
</Button>

// Glass effect utilities
<Card className="bg-glass-bg backdrop-blur-lg border-glass-border">
  <Card.Header>Glass Card</Card.Header>
</Card>

// Responsive spacing with tokens
<div className="p-lg md:p-xl space-y-md">
  Content with consistent spacing
</div>

Testing Strategy

Playwright Test Suite

Comprehensive coverage including:

• Authentication Flows: Login/logout with all user roles
• Navigation Testing: Route guards and permission checks
• Component Interactions: Form submissions and modal behaviors
• Responsive Design: Mobile and desktop viewport testing
• Theme Switching: Light/dark mode persistence
• Visual Regression: Automated screenshot comparisons

Test Organization

• smoke.spec.ts - Critical path smoke tests
• auth.spec.ts - Authentication flow validation
• navigation.spec.ts - Route and navigation testing
• theme.spec.ts - Theme switching and persistence
• responsive.spec.ts - Cross-device responsive testing
• components.spec.ts - Component interaction testing

Mock Data System

All data is simulated using TypeScript interfaces and static mock data:

• No Database Connections: Pure frontend learning environment
• Realistic Data Structures: Mirrors production BCT schemas
• Type Safety: Full TypeScript coverage for mock APIs
• State Management: Zustand stores for different data domains

Code Quality Standards

ESLint Configuration

• Strict TypeScript Rules: No any types, explicit return types
• React Best Practices: Hooks rules, prop validation, accessibility
• Import Organization: Sorted imports with path groups
• Performance Rules: Prevent common React anti-patterns

TypeScript Configuration

• Strict Mode: All strict checks enabled
• Path Aliases: @/* imports for clean module resolution
• Unused Code Detection: Warnings for unused variables/imports
• Exact Optional Properties: Strict object type checking

Development Workflow

Before Committing

1. Run npm run quality:fix to fix linting and formatting
2. Run npm run test:smoke for critical path validation
3. Verify design tokens usage instead of hardcoded values
4. Check responsive design across viewport sizes

Component Development

1. Start with design tokens for colors, spacing, and typography
2. Implement TypeScript interfaces before implementation
3. Add proper accessibility attributes and ARIA labels
4. Test component with both light and dark themes
5. Write Playwright tests for interactive components

Performance Considerations

• Code Splitting: Route-based lazy loading with React.lazy
• Tree Shaking: Optimized imports and bundle analysis
• Design Token Efficiency: CSS custom properties reduce bundle size
• Image Optimization: Proper sizing and lazy loading

Important Notes

This is a Learning Project

• Frontend Only: No live APIs, databases, or payment processing
• Mock Authentication: Simulated user sessions and permissions
• Static Data: All content served from TypeScript mock files
• Safe Environment: No risk of affecting production systems

CrispyGoat Quality Standards

• Premium Polish: Every component must feel finished and professional
• Accessibility First: WCAG AA compliance throughout
• Developer Experience: Clear APIs, excellent TypeScript support
• Performance: Production-ready optimization patterns
• Maintainability: Clean architecture and comprehensive documentation