docs: add comprehensive Phase 2 documentation
- Create detailed README.md with quick start and demo accounts - Add complete UI primitives documentation with examples - Document architecture patterns and design decisions - Update REBUILD_PLAN.md marking Phase 2 as complete - Include component usage guides and testing documentation - Document accessibility compliance and performance considerations Documentation provides complete developer onboarding experience with practical examples and architectural guidance. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
318
reactrebuild0825/README.md
Normal file
318
reactrebuild0825/README.md
Normal file
@@ -0,0 +1,318 @@
|
||||
# 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.**
|
||||
Reference in New Issue
Block a user