# React Component Organization Conventions

## Feature-Based Organization

Group related components into feature folders:

```
src/
  features/
    navigation/           # Feature group
      README.md           # Feature documentation with architecture diagrams
      page-header/        # Component
      page-wrapper/       # Component
      sidebar/            # Component
    auth/                 # Another feature group
    dashboard/            # Another feature group
```

## Component Folder Structure

For each component that requires co-located files (types, tests, etc.):

```
component-name/
  - ComponentName.tsx     # Main component implementation
  - types.ts              # Component-specific types
  - ComponentName.test.tsx # Component tests
  - README.md             # Component-specific documentation
  - index.ts              # Barrel exports
```

## Naming Conventions

- **Folders**: Use kebab-case (`page-header/`)
- **Component Files**: Use PascalCase matching export name (`PageHeader.tsx`)
- **Type Files**: Use `types.ts` for component-specific types
- **Test Files**: Use component name with `.test.tsx` suffix (`PageHeader.test.tsx`)
- **Index Files**: Always use `index.ts` for barrel exports

## Styling Conventions

- **Use Tailwind**: Always use Tailwind classes for styling instead of CSS files or inline styles
- **Use UI Components**: Leverage existing UI components from `components/ui` directory
- **No External CSS**: Never import external CSS files
- **No New Libraries**: Do not add new dependencies; use existing ones
- **Follow Patterns**: Match styling patterns used in the existing codebase

## Export Patterns

**Component File (PageHeader.tsx)**:
```typescript
export interface PageHeaderProps {
  title: string;
  subtitle?: string;
}

export const PageHeader = ({ title, subtitle }: PageHeaderProps) => {
  return (
    // Component implementation
  );
};
```

**Types File (types.ts)**:
```typescript
export interface PageHeaderTheme {
  backgroundColor: string;
  textColor: string;
}

// Additional component-specific types
```

**Barrel File (index.ts)**:
```typescript
export * from './PageHeader';
export * from './types';
```

## Import Examples

```typescript
// Import specific component
import { PageHeader } from '../components/page-header/PageHeader';

// Import via barrel
import { PageHeader, PageHeaderTheme } from '../components/page-header';
```

## Feature Documentation

Each feature folder should include a comprehensive README.md:

```markdown
# Navigation Components

## Overview
This module contains all navigation-related components for the application.

## Architecture
```mermaid
graph TD
    App --> PageWrapper
    PageWrapper --> PageHeader
    PageWrapper --> Sidebar
    PageWrapper --> MainContent
    PageHeader --> Breadcrumbs
    PageHeader --> UserMenu
```

## Components
- **PageHeader**: Application header with navigation controls
- **PageWrapper**: Layout wrapper for all pages
- **Sidebar**: Main navigation sidebar
```

## Benefits of this Approach

- Avoids "index.tsx maze" - component location is always clear
- Easier debugging (stack traces point to actual component files)
- Feature-based organization provides clear domain boundaries
- Architecture documentation with visual diagrams improves onboarding
- Maintains logical co-location while separating concerns
- Enables precise imports when needed
- Follows widely accepted React community standards
- Scales well with large component libraries

This convention balances maintainability with developer experience and remains effective as your application grows.