core ยท git:20250728.7290823 ยท 2025-07-28 ยท sha256 e3163576ceecafd8

core git:20250728.7290823A

Immutable. This exact content never changes and is served at /api/v1/blob/e3163576ceecafd8.

---
description: Core architecture and quality rules for React + Vite + shadcn/ui template
globs: ["src/**/*.{tsx,ts}", "package.json", "vite.config.ts", "tailwind.config.ts"]
alwaysApply: true
---

# React + Vite + shadcn/ui Template - Core Rules

## ๐Ÿšจ CRITICAL ARCHITECTURE RULES

### Component Size & Organization
- **NEVER** create components over 300 lines
- **ALWAYS** break down complex components into smaller, focused pieces (20-100 lines)
- **EXTRACT** reusable logic to custom hooks, not copy-paste
- **USE** composition patterns - build complex UI from smaller components

### File Structure Requirements
```
src/
โ”œโ”€โ”€ components/
โ”‚   โ”œโ”€โ”€ ui/              # shadcn/ui components (READ-ONLY)
โ”‚   โ”œโ”€โ”€ common/          # Reusable components
โ”‚   โ”œโ”€โ”€ forms/           # Form components
โ”‚   โ””โ”€โ”€ features/        # Feature-specific components
โ”œโ”€โ”€ hooks/               # Custom React hooks
โ”œโ”€โ”€ lib/
โ”‚   โ”œโ”€โ”€ utils.ts         # Utilities (includes cn function)
โ”‚   โ”œโ”€โ”€ types.ts         # Shared TypeScript types
โ”‚   โ”œโ”€โ”€ constants.ts     # App constants
โ”‚   โ””โ”€โ”€ validations/     # Zod schemas
โ”œโ”€โ”€ pages/               # Route components (composition only)
โ”œโ”€โ”€ services/            # API calls
โ””โ”€โ”€ context/             # React context providers
```

### Import Organization
```tsx
// 1. React imports
import React, { useState, useEffect } from 'react'

// 2. Third-party libraries
import { useQuery } from '@tanstack/react-query'
import { zodResolver } from '@hookform/resolvers/zod'

// 3. UI components
import { Button } from '@/components/ui/button'
import { Card } from '@/components/ui/card'

// 4. Local components
import { UserCard } from '@/components/common/UserCard'

// 5. Hooks and utilities
import { useDisclosure } from '@/hooks/useDisclosure'
import { cn } from '@/lib/utils'

// 6. Types and constants
import type { User } from '@/lib/types'
import { API_ENDPOINTS } from '@/lib/constants'
```

### Essential Commands
```bash
npm run dev          # Start development server (port 8080)
npm run build        # Production build  
npm run lint         # Run ESLint - MUST pass before shipping
```

### Quality Gates
- **BEFORE SHIPPING**: Run `npm run lint` and fix all issues
- **ACCESSIBILITY**: Maintain WCAG 2.1 AA contrast (4.5:1 minimum)
- **NO CONSOLE ERRORS**: Zero warnings in browser console
- **RESPONSIVE**: Test on mobile and desktop
- **DESIGN QUALITY**: Industry-appropriate visual identity with purposeful color psychology
- **CUSTOM DESIGN**: Interfaces should feel premium and custom-crafted, not template-like