Never use anonymous arrow functions directly in JSX event handlers.
Always extract handlers into named functions declared before the return statement.

// ❌ Bad: anonymous functions everywhere
function ProductCard({ product, onAdd }) {
  return (
    <div>
      <h3>{product.name}</h3>
      <p>${product.price}</p>
      <button onClick={() => {
        if (product.stock > 0) {
          onAdd(product.id);
          toast.success(`Added ${product.name}`);
        } else {
          toast.error('Out of stock');
        }
      }}>
        Add to Cart
      </button>
      <button onClick={() => navigator.clipboard.writeText(product.url)}>
        Share
      </button>
    </div>
  );
}

// ✅ Good: named handlers, testable and readable
function ProductCard({ product, onAdd }) {
  function handleAddToCart() {
    if (product.stock > 0) {
      onAdd(product.id);
      toast.success(`Added ${product.name}`);
    } else {
      toast.error('Out of stock');
    }
  }

  function handleShare() {
    navigator.clipboard.writeText(product.url);
  }

  return (
    <div>
      <h3>{product.name}</h3>
      <p>${product.price}</p>
      <button onClick={handleAddToCart}>Add to Cart</button>
      <button onClick={handleShare}>Share</button>
    </div>
  );
}

Never use inline style objects in JSX. Use CSS Modules (*.module.css)
or Tailwind CSS class names. If the project uses Tailwind, prefer
utility classes. If it uses CSS Modules, import and use styles.

// ❌ Bad: inline styles that drift from your design system
function Alert({ message, type }) {
  return (
    <div style={{
      padding: '16px',
      borderRadius: '8px',
      backgroundColor: type === 'error' ? '#fee2e2' : '#dcfce7',
      color: type === 'error' ? '#991b1b' : '#166534',
      border: `1px solid ${type === 'error' ? '#fca5a5' : '#86efac'}`,
      fontSize: '14px',
      marginBottom: '12px',
    }}>
      <p style={{ margin: 0, fontWeight: 600 }}>{message}</p>
    </div>
  );
}

// ✅ Good: Tailwind classes, consistent with design system
function Alert({ message, type }) {
  const styles = {
    error: 'bg-red-100 text-red-800 border-red-300',
    success: 'bg-green-100 text-green-800 border-green-300',
  };

  return (
    <div className={`p-4 rounded-lg border mb-3 ${styles[type]}`}>
      <p className="m-0 font-semibold text-sm">{message}</p>
    </div>
  );
}

One React component per file. The file name must match the component name.
If a component exceeds 150 lines, split it into smaller components.
Helper components used only by the parent go in a subfolder.

// ❌ Bad: UserDashboard.tsx — 380 lines, 4 components
function UserAvatar({ user }) {
  // ...30 lines
}

function UserStats({ stats }) {
  // ...45 lines
}

function RecentActivity({ activities }) {
  // ...60 lines
}

export default function UserDashboard() {
  // ...200+ lines using all the above
}

// ✅ Good: one component per file
components/
  UserDashboard/
    UserDashboard.tsx      // main component, <150 lines
    UserAvatar.tsx          // extracted, independently testable
    UserStats.tsx           // extracted, reusable elsewhere
    RecentActivity.tsx      // extracted, own loading states
    index.ts               // re-exports UserDashboard

// UserDashboard.tsx
import { UserAvatar } from './UserAvatar';
import { UserStats } from './UserStats';
import { RecentActivity } from './RecentActivity';

export default function UserDashboard() {
  // clean, focused, <150 lines
}

Always define a TypeScript interface for component props.
Always destructure props in the function signature.
Never use `props.x` access pattern. Never type props as `any`.

// ❌ Bad: no types, props bag passed around
function InvoiceRow(props: any) {
  return (
    <tr>
      <td>{props.invoice.number}</td>
      <td>{props.invoice.client.name}</td>
      <td>${props.invoice.total.toFixed(2)}</td>
      <td>
        <button onClick={() => props.onPay(props.invoice.id)}>
          Pay
        </button>
      </td>
    </tr>
  );
}

// ✅ Good: typed interface, destructured props
interface InvoiceRowProps {
  invoice: {
    id: string;
    number: string;
    client: { name: string };
    total: number;
  };
  onPay: (invoiceId: string) => void;
}

function InvoiceRow({ invoice, onPay }: InvoiceRowProps) {
  return (
    <tr>
      <td>{invoice.number}</td>
      <td>{invoice.client.name}</td>
      <td>${invoice.total.toFixed(2)}</td>
      <td>
        <button onClick={() => onPay(invoice.id)}>Pay</button>
      </td>
    </tr>
  );
}

Every useEffect must have an explicit dependencies array.
Never leave the array empty unless the effect genuinely should
only run on mount — and if so, add a comment explaining why.
Never omit the array entirely.

// ❌ Bad: missing and incorrect dependency arrays
function UserProfile({ userId }) {
  const [user, setUser] = useState(null);
  const [posts, setPosts] = useState([]);

  // Missing dependency: won't refetch when userId changes
  useEffect(() => {
    fetchUser(userId).then(setUser);
  }, []);

  // No array at all: runs on EVERY render
  useEffect(() => {
    fetchPosts(userId).then(setPosts);
  });

  // ...
}

// ✅ Good: explicit, correct dependencies
function UserProfile({ userId }) {
  const [user, setUser] = useState(null);
  const [posts, setPosts] = useState([]);

  useEffect(() => {
    fetchUser(userId).then(setUser);
  }, [userId]); // refetches when userId changes

  useEffect(() => {
    fetchPosts(userId).then(setPosts);
  }, [userId]); // refetches when userId changes

  // Mount-only effect with explanation
  useEffect(() => {
    analytics.trackPageView('user-profile');
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, []); // intentionally mount-only: track page view once per navigation

  // ...
}

Never render a bare .map() without checking for loading, error,
and empty states first. Every data-driven component must handle:
1. Loading state (skeleton or spinner)
2. Error state (user-friendly message with retry option)
3. Empty state (helpful message, not blank screen)
4. Data state (the actual render)

// ❌ Bad: bare .map(), no state handling
function OrderList({ customerId }) {
  const [orders, setOrders] = useState([]);

  useEffect(() => {
    fetch(`/api/orders?customer=${customerId}`)
      .then(res => res.json())
      .then(setOrders);
  }, [customerId]);

  return (
    <ul>
      {orders.map(order => (
        <li key={order.id}>
          Order #{order.number} — ${order.total}
        </li>
      ))}
    </ul>
  );
}

// ✅ Good: all states handled
function OrderList({ customerId }) {
  const [orders, setOrders] = useState<Order[] | null>(null);
  const [error, setError] = useState<string | null>(null);
  const [isLoading, setIsLoading] = useState(true);

  useEffect(() => {
    setIsLoading(true);
    setError(null);
    fetch(`/api/orders?customer=${customerId}`)
      .then(res => {
        if (!res.ok) throw new Error('Failed to load orders');
        return res.json();
      })
      .then(setOrders)
      .catch(err => setError(err.message))
      .finally(() => setIsLoading(false));
  }, [customerId]);

  if (isLoading) return <OrderListSkeleton />;
  if (error) return <ErrorMessage message={error} onRetry={() => window.location.reload()} />;
  if (!orders || orders.length === 0) return <EmptyState message="No orders yet" />;

  return (
    <ul>
      {orders.map(order => (
        <li key={order.id}>
          Order #{order.number} — ${order.total}
        </li>
      ))}
    </ul>
  );
}

# React Component Rules

## Event Handlers
- Never use anonymous arrow functions in JSX event handlers
- Extract all handlers into named functions before the return statement

## Styling
- Never use inline style objects
- Use CSS Modules or Tailwind utility classes

## File Structure
- One React component per file
- File name must match component name
- Max 150 lines per component — split into subfolder if larger

## Props
- Define TypeScript interfaces for all component props
- Always destructure props in function signature
- Never use `any` for props

## Effects
- Every useEffect must have an explicit dependencies array
- Empty arrays require a comment explaining why mount-only is correct
- Never omit the dependencies array

## State Handling
- Never render a bare .map() without null/undefined checks
- Every data-driven component must handle: loading, error, empty, and data states
- Show skeletons or spinners during loading
- Show user-friendly error messages with retry options