# AI Rules - Project Standards

> Coding standards and conventions that Claude MUST follow.
> This defines WHAT quality looks like for this project.

---

## Project Configuration

**Name:** [Your Project Name]
**Description:** [One-line description]
**Target Users:** [Who uses this?]
**Core Value:** [What problem does it solve?]

> Full specification in `instructions/BLUEPRINT.md`

---

## Tech Stack

- React 18 + TypeScript + Vite
- Tailwind CSS + shadcn/ui
- lucide-react icons
- React Router DOM

---

## File Structure

```
src/
├── components/    # Reusable UI (PascalCase.tsx)
├── pages/         # Route pages
├── hooks/         # Custom hooks (use*.ts)
├── lib/           # Utilities
├── types/         # TypeScript types (*.types.ts)
└── api/           # API functions
```

---

## Naming Conventions

| Type | Convention | Example |
|------|------------|---------|
| Components | PascalCase.tsx | `UserCard.tsx` |
| Hooks | use*.ts | `useAuth.ts` |
| Utilities | camelCase.ts | `formatDate.ts` |
| Types | *.types.ts | `user.types.ts` |
| Constants | UPPER_SNAKE | `MAX_ITEMS` |

---

## Component Rules

### Structure
- Max 150 lines per file
- Extract hooks for logic
- Use TypeScript interfaces (not types)
- Handle loading/error/empty states

### Required States
Every component with async data MUST have:
- Loading state (skeleton/spinner)
- Error state (error message)
- Empty state (no data message)

### Props Interface
```typescript
interface ComponentProps {
  // Required props first
  id: string
  data: DataType

  // Optional props after
  className?: string
  onAction?: () => void
}
```

---

## Styling Rules

- Tailwind utilities only
- Use `cn()` for conditional classes
- Mobile-first responsive design
- No inline styles
- No CSS files (use Tailwind)

```typescript
// Good
<div className={cn("p-4 bg-white", isActive && "bg-blue-500")} />

// Bad
<div style={{ padding: 16 }} />
```

---

## API Patterns

### Response Type
```typescript
interface ApiResponse<T> {
  data: T | null
  error: string | null
  loading: boolean
}
```

### Error Handling
```typescript
try {
  const data = await fetchData()
  return { data, error: null }
} catch (error) {
  toast.error('Failed to load data')
  return { data: null, error: error.message }
}
```

---

## Quality Standards

### Every New Page MUST Have:
- [ ] Loading skeleton
- [ ] Error boundary
- [ ] Empty state
- [ ] SEO meta tags
- [ ] Mobile layout

### Every New Form MUST Have:
- [ ] Client validation
- [ ] Server error display
- [ ] Submit loading state
- [ ] Success feedback
- [ ] Disabled state while submitting

### Every New Component MUST Have:
- [ ] TypeScript props interface
- [ ] Default props where sensible
- [ ] Loading prop (if async)

---

## ALWAYS / NEVER Rules

### ALWAYS:
- Handle API errors gracefully
- Show loading states for async operations
- Validate user input
- Use semantic HTML
- Add aria-labels for icons
- Complete features fully (UI + Backend)

### NEVER:
- Use `any` type
- Leave console.log statements
- Skip error handling
- Hardcode strings (use constants)
- Commit with TypeScript errors
- Build backend WITHOUT UI
- Create API WITHOUT UI that calls it
- Add database table WITHOUT UI
- Commit orphan features

---

## UI Enforcement

### Definition of Done

A feature is **NOT COMPLETE** until:

| Requirement | Must Exist |
|-------------|------------|
| Backend/API | Logic implemented |
| UI Component | User-facing component |
| Connection | UI calls the backend |
| Navigation | User can access it |

### Self-Check Before Commit
```
□ Can a user SEE this feature in the app?
□ Can a user INTERACT with this feature?
□ Is the UI CONNECTED to the backend?
□ Is there a WAY to navigate to it?

ALL must be YES to commit.
```

---

## ESLint Rules (Enforced)

| Rule | Setting | Purpose |
|------|---------|---------|
| `no-console` | error | No debug logs |
| `max-lines` | 300 | Files focused |
| `max-lines-per-function` | 75 | Functions small |
| `complexity` | 15 | Prevent complexity |
| `no-nested-ternary` | error | Readable code |
| `eqeqeq` | error | Strict equality |
| `@typescript-eslint/no-explicit-any` | error | Type safety |
| `@typescript-eslint/no-non-null-assertion` | error | Safe nulls |

---

## Coverage Thresholds

```
Lines:      80%
Functions:  80%
Branches:   70%
Statements: 80%
```

---

## Commit Message Format

```
type(scope): description

Types:
- feat: New feature
- fix: Bug fix
- docs: Documentation
- style: Formatting
- refactor: Code restructure
- perf: Performance
- test: Tests
- build: Build system
- ci: CI/CD
- chore: Maintenance
- revert: Revert commit
```

Examples:
- `feat(auth): add login page`
- `fix(api): handle null response`
- `refactor(utils): extract date helpers`

---

## Commands

```bash
npm run dev        # Start dev server
npm run typecheck  # TypeScript check
npm run lint       # ESLint check
npm run verify     # TypeScript + ESLint
npm run test       # Run tests
npm run audit:ui   # Check orphan features
npm run audit:cycles # Check circular deps
```

---

## Feature Completeness Checklist

When Claude suggests improvements, check against:

- [ ] Error state UI
- [ ] Loading state UI
- [ ] Empty state UI
- [ ] Success feedback (toast/notification)
- [ ] Form validation messages
- [ ] Keyboard navigation
- [ ] Mobile layout

---

## Notes for Claude

When building features:
1. Check `BLUEPRINT.md` for requirements
2. Follow these standards for quality
3. Match existing patterns in codebase
4. Complete features fully before commit

**Feature completeness = BLUEPRINT requirements + these standards**