blackcanyontickets/reactrebuild0825/README.md

# Black Canyon Tickets - React Rebuild

A production-ready React rebuild of the Black Canyon Tickets platform featuring a complete design token system, comprehensive component library, and WCAG AA compliant accessibility.

## Phase 2 Complete ✅

**Delivered Features:**
- ✅ Complete design token system with light/dark themes
- ✅ Production-ready UI primitive library  
- ✅ Responsive layout system with navigation
- ✅ Mock authentication with role-based permissions
- ✅ Error boundaries and loading states
- ✅ Business domain components (EventCard, TicketTypeRow, OrderSummary)
- ✅ WCAG AA accessibility compliance (4.5:1+ contrast ratios)
- ✅ Strict TypeScript and ESLint configuration
- ✅ Comprehensive Playwright test suite with visual regression

## Quick Start

```bash
# Install dependencies
npm install

# Start development server
npm run dev

# Open http://localhost:5173
```

### Demo Accounts

**Regular User:**
- Username: `demo@blackcanyontickets.com`
- Password: `demo123`
- Access: Events and ticket purchasing

**Admin User:**
- Username: `admin@blackcanyontickets.com`  
- Password: `admin123`
- Access: Full platform administration

**Super Admin:**
- Username: `superadmin@blackcanyontickets.com`
- Password: `super123`
- Access: All administrative features

## Tech Stack

### Core Technologies
- **React 18** with TypeScript for type safety
- **Vite** for lightning-fast development and builds
- **Tailwind CSS** with custom design token system
- **React Router v6** for client-side routing

### Development Tools
- **ESLint** with strict React/TypeScript rules
- **Playwright** for end-to-end testing with screenshots
- **TypeScript** with strict configuration
- **Prettier** for consistent code formatting

### Architecture Patterns
- **Design Token System** - CSS custom properties for consistent theming
- **Component Composition** - Reusable primitives with flexible APIs
- **Error Boundaries** - Graceful error handling at component level
- **Mock Authentication** - Role-based access control simulation
- **Accessibility First** - WCAG AA compliance built into components

## Design System

### Theme System
The application supports automatic light/dark theme switching with:

- **Light Theme**: Clean, modern aesthetic with high contrast
- **Dark Theme**: Sophisticated, muted palette for professional environments
- **Color Tokens**: Semantic color system (primary, secondary, success, warning, error)
- **Typography Scale**: Consistent text sizes from xs to 4xl
- **Spacing System**: 8px grid-based spacing tokens

### Design Tokens Usage
```css
/* Colors */
color: var(--color-text-primary);
background: var(--color-surface-primary);
border-color: var(--color-border-primary);

/* Typography */
font-size: var(--font-size-lg);
line-height: var(--line-height-relaxed);

/* Spacing */
padding: var(--spacing-4);
margin: var(--spacing-2);
```

## Component Library

### UI Primitives

**Button Component**
```tsx
import { Button } from '@/components/ui/Button';

<Button variant="primary" size="lg" onClick={handleClick}>
  Primary Action
</Button>
```

**Input Component**
```tsx
import { Input } from '@/components/ui/Input';

<Input
  type="email"
  label="Email Address"
  error={errors.email}
  required
/>
```

**Card Component**
```tsx
import { Card } from '@/components/ui/Card';

<Card variant="elevated" className="p-6">
  <Card.Header>
    <h3>Card Title</h3>
  </Card.Header>
  <Card.Content>
    Card content goes here
  </Card.Content>
</Card>
```

### Business Components

**EventCard**
```tsx
import { EventCard } from '@/components/events/EventCard';

<EventCard
  event={event}
  showActions={true}
  onTicketPurchase={handlePurchase}
/>
```

**TicketTypeRow**
```tsx
import { TicketTypeRow } from '@/components/tickets/TicketTypeRow';

<TicketTypeRow
  ticketType={ticketType}
  quantity={quantity}
  onQuantityChange={setQuantity}
/>
```

## Development Commands

```bash
# 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

# Testing
npm run test         # Run Playwright end-to-end tests
npm run test:headed  # Run tests with visible browser
npm run test:ui      # Run tests with Playwright UI
```

## Project Structure

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

## Authentication System

Mock authentication supports three user roles:

- **User**: Basic event browsing and ticket purchasing
- **Admin**: Event management and analytics
- **Super Admin**: Platform administration and user management

```tsx
import { useAuth } from '@/hooks/useAuth';

function ProtectedComponent() {
  const { user, hasPermission } = useAuth();
  
  if (!hasPermission('admin')) {
    return <AccessDenied />;
  }
  
  return <AdminInterface />;
}
```

## Error Handling

Comprehensive error boundaries catch and handle errors gracefully:

```tsx
import { AppErrorBoundary } from '@/components/errors/AppErrorBoundary';

<AppErrorBoundary fallback={<ErrorFallback />}>
  <YourComponent />
</AppErrorBoundary>
```

## Accessibility Features

- **WCAG AA Compliance**: All color combinations meet 4.5:1 contrast ratios
- **Keyboard Navigation**: Full keyboard support for all interactive elements
- **Screen Reader Support**: Proper ARIA labels and semantic HTML
- **Focus Management**: Visible focus indicators and logical tab order
- **Responsive Design**: Mobile-first approach with touch-friendly targets

## Testing

### Playwright Test Suite

Comprehensive end-to-end tests covering:

- **Authentication flows** with all user roles
- **Navigation** and routing functionality  
- **Component interactions** and form submissions
- **Responsive design** across viewport sizes
- **Theme switching** between light and dark modes
- **Visual regression** with automated screenshots

```bash
# Run all tests
npm run test

# Run specific test file
npx playwright test auth.spec.ts

# Run tests with browser visible
npm run test:headed

# Generate test report
npx playwright show-report
```

## Performance Considerations

- **Tree Shaking**: Components import only what they need
- **Code Splitting**: Route-based code splitting with React.lazy
- **Optimized Builds**: Vite's production optimizations enabled
- **CSS Optimization**: Design tokens reduce CSS bundle size

## CrispyGoat Quality Standards

This project exemplifies CrispyGoat's commitment to:

- **Premium Polish**: Every component feels finished and professional
- **Developer Experience**: Clear APIs, excellent TypeScript support
- **Accessibility**: Universal design principles throughout
- **Performance**: Optimized for production deployments
- **Maintainability**: Clean architecture and comprehensive documentation

## Browser Support

- **Chrome/Edge**: Full support for latest 2 versions
- **Firefox**: Full support for latest 2 versions  
- **Safari**: Full support for latest 2 versions
- **Mobile**: iOS Safari 14+, Chrome Android 90+

## Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feat/new-feature`
3. Make changes following our code standards
4. Run tests: `npm run test`
5. Run linting: `npm run lint:fix`
6. Submit a pull request

## License

This project is for learning and demonstration purposes.

---

**Built with CrispyGoat quality standards - premium polish, developer-first experience.**