---
description: Component composition patterns and architecture principles
alwaysApply: false
globs: **/*.{ts,tsx,js,jsx,vue,svelte}
---

# Component Architecture & Composition Patterns

## Core Philosophy

**Composition Over Configuration**

Build complex UIs from simple, focused components that compose well together.

### Key Tenets

- **Single Responsibility**: Each component does one thing well
- **Composition Slots**: Use children/slots instead of complex prop APIs
- **Default Props**: Provide sensible defaults for easy use
- **Prop Interfaces**: Clear contracts with TypeScript/PropTypes
- **Minimal State**: Keep component state local and minimal

## Anti-patterns to Avoid

- ❌ God components that do everything
- ❌ Prop drilling through many layers
- ❌ Hard-coded values instead of props
- ❌ Component logic mixed with layout
- ❌ Tight coupling between components

## Template Pattern

Create base templates that handle common layouts and let content be injected.

```jsx
const PageTemplate = ({ title, children }) => (
  <div className="page-container">
    <Header />
    <main className="page-content">
      {title && <h1>{title}</h1>}
      {children}
    </main>
    <Footer />
  </div>
);
```

## Container/Presenter Pattern

Split components into smart (containers) and dumb (presenters) components.

- **Container**: Handles data and logic
- **Presenter**: Pure presentation, receives data via props

## Prop Interface Design

```typescript
interface BaseComponentProps {
  className?: string;
  children?: React.ReactNode;
  testId?: string;
}

interface ButtonProps extends BaseComponentProps {
  variant?: 'primary' | 'secondary' | 'ghost';
  size?: 'sm' | 'md' | 'lg';
  disabled?: boolean;
  loading?: boolean;
  onClick?: (event: React.MouseEvent) => void;
}
```

### Prop Naming Conventions

- Boolean props: `isOpen`, `hasError`, `disabled`
- Handler props: `onClick`, `onClose`, `onChange`
- Render props: `renderHeader`, `renderItem`
- Data props: `items`, `data`, `value`
- Config props: `variant`, `size`, `theme`