React Patterns

Component Architecture

File Structure (Co-location)

src/components/UserCard/
  UserCard.tsx          # Component implementation
  UserCard.test.tsx     # Tests
  UserCard.stories.tsx  # Storybook (optional)
  index.ts              # Barrel export

Component Template

import { type ReactNode } from 'react';

interface UserCardProps {
  /** User's display name */
  name: string;
  /** Optional avatar URL */
  avatarUrl?: string;
  /** Slot for action buttons */
  actions?: ReactNode;
}

export function UserCard({ name, avatarUrl, actions }: UserCardProps) {
  return (
    <article className="flex items-center gap-4 rounded-lg border p-4">
      <img
        src={avatarUrl ?? '/default-avatar.png'}
        alt={`${name}'s avatar`}
        className="h-12 w-12 rounded-full object-cover"
      />
      <div className="flex-1 min-w-0">
        <h3 className="truncate font-medium">{name}</h3>
      </div>
      {actions && <div className="flex gap-2">{actions}</div>}
    </article>
  );
}

Conventions:

• Named export, never default
• Props interface in same file with JSDoc
• Semantic HTML (<article>, <h3>, not <div>)
• Composition via slot props (actions, children, header)
• Defensive defaults for optional props

Component Size Limits

• Max 250 lines per component file
• Max 50 lines per function
• If exceeding, extract sub-components or custom hooks

State Handling Order (Golden Rule)

Every component that fetches data MUST handle states in this exact order:

function UserList() {
  const { data, isPending, error, refetch } = useUsers();

  // 1. Error FIRST
  if (error) {
    return <ErrorState error={error} onRetry={refetch} />;
  }

  // 2. Loading ONLY when no data
  if (isPending && !data) {
    return <UserListSkeleton />;
  }

  // 3. Empty state
  if (!data?.length) {
    return (
      <EmptyState
        icon="users"
        title="No users yet"
        description="Invite your first team member"
        action={{ label: 'Invite', onClick: openInviteModal }}
      />
    );
  }

  // 4. Success
  return (
    <ul role="list" className="divide-y">
      {data.map((user) => (
        <li key={user.id}>
          <UserCard user={user} />
        </li>
      ))}
    </ul>
  );
}

Why this order?

• Error before loading: prevents showing stale error under a spinner
• isPending && !data: prevents flash of loading on refetch when cached data exists
• Empty before success: explicit handling, not just a missing list

Composition Patterns

Compound Components

function Tabs({ children, defaultValue }: TabsProps) {
  const [activeTab, setActiveTab] = useState(defaultValue);
  
  return (
    <TabsContext.Provider value={{ activeTab, setActiveTab }}>
      <div role="tablist">{children}</div>
    </TabsContext.Provider>
  );
}

function TabTrigger({ value, children }: TabTriggerProps) {
  const { activeTab, setActiveTab } = useTabsContext();
  return (
    <button
      role="tab"
      aria-selected={activeTab === value}
      onClick={() => setActiveTab(value)}
    >
      {children}
    </button>
  );
}

function TabContent({ value, children }: TabContentProps) {
  const { activeTab } = useTabsContext();
  if (activeTab !== value) return null;
  return <div role="tabpanel">{children}</div>;
}

// Usage
<Tabs defaultValue="profile">
  <TabTrigger value="profile">Profile</TabTrigger>
  <TabTrigger value="settings">Settings</TabTrigger>
  <TabContent value="profile"><ProfileForm /></TabContent>
  <TabContent value="settings"><SettingsForm /></TabContent>
</Tabs>

Render Props (Headless Components)

interface ToggleRenderProps {
  isOn: boolean;
  toggle: () => void;
}

function Toggle({ children }: { children: (props: ToggleRenderProps) => ReactNode }) {
  const [isOn, setIsOn] = useState(false);
  return <>{children({ isOn, toggle: () => setIsOn((v) => !v) })}</>;
}

// Usage
<Toggle>
  {({ isOn, toggle }) => (
    <button onClick={toggle}>{isOn ? 'ON' : 'OFF'}</button>
  )}
</Toggle>

Custom Hooks for Logic Extraction

function useDebounce<T>(value: T, delayMs: number): T {
  const [debounced, setDebounced] = useState(value);

  useEffect(() => {
    const timer = setTimeout(() => setDebounced(value), delayMs);
    return () => clearTimeout(timer);
  }, [value, delayMs]);

  return debounced;
}

function useMediaQuery(query: string): boolean {
  const [matches, setMatches] = useState(
    () => window.matchMedia(query).matches
  );

  useEffect(() => {
    const mql = window.matchMedia(query);
    const handler = (e: MediaQueryListEvent) => setMatches(e.matches);
    mql.addEventListener('change', handler);
    return () => mql.removeEventListener('change', handler);
  }, [query]);

  return matches;
}

Mutation Patterns

function DeleteButton({ itemId, onDeleted }: DeleteButtonProps) {
  const { mutate: deleteItem, isPending } = useDeleteItem({
    onSuccess: () => {
      toast.success('Item deleted');
      onDeleted?.();
    },
    onError: (error) => {
      console.error('deleteItem failed:', error);
      toast.error('Failed to delete item. Please try again.');
    },
  });

  return (
    <button
      onClick={() => deleteItem(itemId)}
      disabled={isPending}
      aria-busy={isPending}
      className="btn-danger"
    >
      {isPending ? 'Deleting...' : 'Delete'}
    </button>
  );
}

Non-negotiable rules:

• disabled={isPending} — prevent double-clicks
• aria-busy={isPending} — screen reader feedback
• onError always shows toast AND logs with context
• Trigger text reflects state

Anti-Patterns

Checklist

Before completing any component:

• Named export with typed props interface
• State order: Error → Loading (no data) → Empty → Success
• Semantic HTML elements
• Keyboard accessible
• Under 250 lines
• Tests cover all 4 states
• Mutations have disabled state + error handling

Integration with Other Skills

• state-management: When to lift state vs. use stores
• testing-strategy: Factory pattern for component tests
• accessibility: ARIA patterns for interactive components
• css-architecture: Styling approach for the component