core · git:20250728.3d3113e · 2025-07-28 · sha256 4e30c647c70af3c5
core git:20250728.3d3113eA
Immutable. This exact content never changes and is served at /api/v1/blob/4e30c647c70af3c5.
---
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