I Let GitHub Copilot Define My React Standards for Six Months. Here's the Damage It Did.

src/components/
├── Button.tsx                    ← Developer A, month 1
├── ButtonComponent.tsx           ← Developer B, month 2 (same thing, different name)
├── PrimaryButton/
│   └── PrimaryButton.tsx         ← Developer C, month 3 (folder style)
├── ui/
│   └── button.tsx                ← Developer D, month 4 (shadcn influence)
└── IconButton.tsx                ← Developer A again, month 5 (forgot the folder pattern)

src/
├── app/                    # App shell — routing, global layout, providers
│   ├── layout.tsx          # Root layout
│   ├── router.tsx          # Route definitions
│   └── providers.tsx       # Context providers stacked here, not scattered
│
├── components/             # Shared UI primitives — NO business logic here
│   ├── Button/
│   │   ├── Button.tsx      # The component
│   │   ├── Button.test.tsx # Tests live next to what they test
│   │   └── index.ts        # Re-export for clean imports
│   ├── Input/
│   ├── Modal/
│   └── index.ts            # Barrel export for all shared components
│
├── features/               # Domain features — business logic lives here
│   ├── Auth/
│   │   ├── components/     # Components only used inside Auth
│   │   ├── hooks/          # Hooks only used inside Auth
│   │   ├── services/       # API calls only used inside Auth
│   │   ├── types.ts        # Types only used inside Auth
│   │   └── AuthPage.tsx    # The page component
│   ├── UserProfile/
│   └── Dashboard/
│
├── hooks/                  # Reusable hooks — NO feature-specific logic
├── services/               # API layer — all fetch calls go through here
├── types/                  # Global TypeScript types
├── utils/                  # Pure helper functions
└── main.tsx

// ✅ Our conventions — written down once, never debated again

// Components: PascalCase, noun-based
// ✅ UserProfileCard.tsx
// ✅ AuthenticationForm.tsx
// ❌ userProfileCard.tsx
// ❌ UserProfileCardComponent.tsx  ← "Component" suffix is redundant
// ❌ UPCard.tsx  ← Abbreviations are hidden knowledge

// Props interfaces: ComponentNameProps
// ✅ interface ButtonProps {}
// ✅ interface UserProfileCardProps {}
// ❌ interface IButtonProps {}  ← I-prefix is hungarian notation, we don't use it
// ❌ interface Props {}  ← Too generic, hard to search

// Custom hooks: always useNoun or useNounVerb
// ✅ useAuth
// ✅ useUserProfile
// ✅ useProductFilter
// ❌ useFetchUser  ← The "fetch" is an implementation detail, not the hook's identity

// Event handlers: always handleEventName
// ✅ handleSubmit, handleClick, handleFilterChange
// ❌ onSubmit (that's for the prop name, not the handler variable)
// ❌ submitForm, clickButton (verbs without "handle" prefix)

// components/UserAvatar/UserAvatar.tsx
// This component has one reason to change: the avatar's visual design.
// It doesn't know where the user came from or how their data is structured globally.

interface UserAvatarProps {
  name: string;
  imageUrl?: string;
  size?: 'sm' | 'md' | 'lg';
}

// We use function declaration over React.FC — team decision.
// Reason: React.FC has implicit children prop in older React versions,
// and the function declaration makes the return type clearer.
export function UserAvatar({ name, imageUrl, size = 'md' }: UserAvatarProps) {
  const initials = name
    .split(' ')
    .map(part => part[0])
    .join('')
    .toUpperCase()
    .slice(0, 2);

  const sizeClasses = {
    sm: 'w-8 h-8 text-xs',
    md: 'w-10 h-10 text-sm',
    lg: 'w-14 h-14 text-base',
  };

  if (imageUrl) {
    return (
      <img
        src={imageUrl}
        alt={`${name}'s avatar`}
        className={`rounded-full object-cover ${sizeClasses[size]}`}
      />
    );
  }

  return (
    <div
      className={`rounded-full bg-blue-500 text-white flex items-center justify-center font-medium ${sizeClasses[size]}`}
      aria-label={`${name}'s avatar`}
    >
      {initials}
    </div>
  );
}

// features/UserProfile/hooks/useUserProfile.ts
// The hook owns the data logic. The component owns the rendering.
// If the API changes, you touch the hook. If the design changes, you touch the component.
// They have separate reasons to change — separate files.

import { useState, useEffect } from 'react';

interface User {
  id: string;
  name: string;
  email: string;
  avatarUrl?: string;
  bio: string;
}

interface UseUserProfileReturn {
  user: User | null;
  isLoading: boolean;
  error: string | null;
  refetch: () => void;
}

export function useUserProfile(userId: string): UseUserProfileReturn {
  const [user, setUser] = useState<User | null>(null);
  const [isLoading, setIsLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);

  const fetchUser = async () => {
    setIsLoading(true);
    setError(null);
    try {
      const response = await fetch(`/api/users/${userId}`);
      if (!response.ok) throw new Error('Failed to fetch user');
      const data: User = await response.json();
      setUser(data);
    } catch (err) {
      setError(err instanceof Error ? err.message : 'Unknown error');
    } finally {
      setIsLoading(false);
    }
  };

  useEffect(() => {
    fetchUser();
  }, [userId]);

  return { user, isLoading, error, refetch: fetchUser };
}

// features/UserProfile/components/UserProfileCard.tsx
// This component is dumb on purpose. It renders what it receives.
// The complexity lives in the hook — this stays readable.

import { useUserProfile } from '../hooks/useUserProfile';
import { UserAvatar } from '../../../components/UserAvatar';

interface UserProfileCardProps {
  userId: string;
}

export function UserProfileCard({ userId }: UserProfileCardProps) {
  const { user, isLoading, error } = useUserProfile(userId);

  if (isLoading) return <UserProfileCardSkeleton />;
  if (error) return <ErrorMessage message={error} />;
  if (!user) return null;

  return (
    <div className="rounded-lg border border-gray-200 p-6">
      <div className="flex items-center gap-4">
        <UserAvatar name={user.name} imageUrl={user.avatarUrl} size="lg" />
        <div>
          <h2 className="text-lg font-semibold">{user.name}</h2>
          <p className="text-gray-500 text-sm">{user.email}</p>
        </div>
      </div>
      {user.bio && <p className="mt-4 text-gray-700">{user.bio}</p>}
    </div>
  );
}

// components/Tabs/Tabs.tsx
// The compound pattern gives consumers flexibility without prop explosion.
// Compare:

// ❌ Prop explosion — rigid, hard to extend, impossible to compose
<Tabs
  activeTab={currentTab}
  onTabChange={handleChange}
  tabTitles={['Overview', 'Details', 'Settings']}
  tabContents={[<Overview />, <Details />, <Settings />]}
  tabIcons={[overviewIcon, detailsIcon, settingsIcon]}
  tabDisabled={[false, false, true]}
/>

// ✅ Compound — flexible, composable, clear ownership
<Tabs value={currentTab} onChange={handleChange}>
  <Tabs.List>
    <Tabs.Trigger value="overview">Overview</Tabs.Trigger>
    <Tabs.Trigger value="details">Details</Tabs.Trigger>
    <Tabs.Trigger value="settings" disabled>Settings</Tabs.Trigger>
  </Tabs.List>
  <Tabs.Content value="overview"><Overview /></Tabs.Content>
  <Tabs.Content value="details"><Details /></Tabs.Content>
  <Tabs.Content value="settings"><Settings /></Tabs.Content>
</Tabs>

// The implementation — compound components use Context to share state
// without prop drilling between the sub-components

import { createContext, useContext, useState, ReactNode } from 'react';

interface TabsContextValue {
  activeTab: string;
  onChange: (value: string) => void;
}

const TabsContext = createContext<TabsContextValue | null>(null);

function useTabsContext() {
  const context = useContext(TabsContext);
  if (!context) {
    throw new Error('Tabs compound components must be used within <Tabs>');
  }
  return context;
}

interface TabsProps {
  value: string;
  onChange: (value: string) => void;
  children: ReactNode;
}

// The root component — owns the context
export function Tabs({ value, onChange, children }: TabsProps) {
  return (
    <TabsContext.Provider value={{ activeTab: value, onChange }}>
      <div className="tabs-root">{children}</div>
    </TabsContext.Provider>
  );
}

// Sub-components — consume the context
Tabs.List = function TabsList({ children }: { children: ReactNode }) {
  return <div role="tablist" className="flex border-b">{children}</div>;
};

Tabs.Trigger = function TabsTrigger({
  value,
  disabled = false,
  children,
}: {
  value: string;
  disabled?: boolean;
  children: ReactNode;
}) {
  const { activeTab, onChange } = useTabsContext();
  const isActive = activeTab === value;

  return (
    <button
      role="tab"
      aria-selected={isActive}
      disabled={disabled}
      onClick={() => !disabled && onChange(value)}
      className={`px-4 py-2 text-sm font-medium border-b-2 transition-colors
        ${isActive ? 'border-blue-500 text-blue-600' : 'border-transparent text-gray-500'}
        ${disabled ? 'opacity-40 cursor-not-allowed' : 'hover:text-gray-700'}`}
    >
      {children}
    </button>
  );
};

Tabs.Content = function TabsContent({
  value,
  children,
}: {
  value: string;
  children: ReactNode;
}) {
  const { activeTab } = useTabsContext();
  if (activeTab !== value) return null;
  return <div role="tabpanel" className="py-4">{children}</div>;
};

When you need state, ask in this order:

1. Can this be derived from existing state or props?
   YES → Don't add state. Compute it inline.
   NO  → Continue.

2. Is this state used by only ONE component?
   YES → useState (or useReducer if the logic is complex)
   NO  → Continue.

3. Is this state used by a small, bounded component tree?
   YES → useContext within that feature
   NO  → Continue.

4. Is this state genuinely global (user session, theme, cart)?
   YES → Zustand store
   NO  → Go back to step 2. You probably answered wrong.

// ✅ The decision tree in practice:

// Step 1 — derived state: don't store it
function UserGreeting({ user }: { user: User }) {
  // Don't useState for displayName — it's derived from user.name
  const displayName = user.name.split(' ')[0]; // Compute inline
  return <h1>Hello, {displayName}</h1>;
}

// Step 2 — single component: useState
function SearchInput() {
  const [query, setQuery] = useState('');
  return <input value={query} onChange={e => setQuery(e.target.value)} />;
}

// Step 2 — complex single-component logic: useReducer
type FilterAction =
  | { type: 'SET_CATEGORY'; payload: string }
  | { type: 'SET_PRICE_RANGE'; payload: [number, number] }
  | { type: 'RESET' };

interface FilterState {
  category: string;
  priceRange: [number, number];
}

function filterReducer(state: FilterState, action: FilterAction): FilterState {
  switch (action.type) {
    case 'SET_CATEGORY':
      return { ...state, category: action.payload };
    case 'SET_PRICE_RANGE':
      return { ...state, priceRange: action.payload };
    case 'RESET':
      return { category: '', priceRange: [0, 1000] };
  }
}

// Step 3 — feature-scoped shared state: useContext
// See the compound Tabs example above — TabsContext is step 3.

// Step 4 — global state: Zustand
// (Lives in src/store/ — not shown here to keep focus)

# Copilot Instructions — YourProject React Standard

## Component Structure
- Use function declarations, not React.FC
- Props interface named ComponentNameProps
- Export named, not default
- Each component in its own folder with index.ts re-export

## File Location Rules
- Shared UI with no business logic → src/components/
- Feature-specific components → src/features/FeatureName/components/
- Never create components directly in src/components/ that import from src/features/

## State Management
- Derived state: compute inline, never useState
- Single-component state: useState or useReducer
- Feature-scoped shared state: useContext within the feature
- Global state: Zustand in src/store/

## Naming
- Components: PascalCase noun (UserProfileCard not UserProfileCardComponent)
- Event handlers: handleEventName (handleSubmit not onSubmit or submitForm)
- Custom hooks: useNoun or useNounVerb (useAuth not useFetchAuth)
- Props interfaces: ComponentNameProps (no I prefix)

## TypeScript
- Always type props explicitly — no implicit any
- Prefer interface for props, type for unions and utility types
- Avoid type assertions (as X) unless absolutely necessary

// src/_examples/ExampleFeatureComponent.tsx
// THIS IS A REFERENCE EXAMPLE — not production code.
// Copilot uses this as a pattern reference for new components.

// STANDARD: function declaration, not React.FC
// STANDARD: props interface named ComponentNameProps
// STANDARD: named export, not default

interface ExampleFeatureComponentProps {
  // STANDARD: required props first, optional props last
  userId: string;
  // STANDARD: optional props have explicit defaults in the signature
  variant?: 'compact' | 'full';
}

// STANDARD: component name matches filename
export function ExampleFeatureComponent({
  userId,
  variant = 'full', // STANDARD: default here, not in the interface
}: ExampleFeatureComponentProps) {
  // STANDARD: hook for data fetching — never fetch in the component body
  const { user, isLoading, error } = useUserProfile(userId);

  // STANDARD: early returns for loading and error states
  // before the main render — keeps the happy path clean
  if (isLoading) return <Skeleton />;
  if (error) return <ErrorMessage message={error} />;
  if (!user) return null;

  return (
    <div>
      {/* STANDARD: conditional rendering with ternary for two states,
          short-circuit && for one state */}
      {variant === 'full' ? (
        <FullUserCard user={user} />
      ) : (
        <CompactUserCard user={user} />
      )}
    </div>
  );
}

// .eslintrc.js
module.exports = {
  rules: {
    // Enforce named exports — no default exports from component files
    'import/no-default-export': 'error',

    // Enforce consistent function component style
    'react/function-component-definition': [
      'error',
      { namedComponents: 'function-declaration' }
    ],

    // Prevent prop-types (we use TypeScript)
    'react/prop-types': 'off',

    // Enforce hook naming convention
    'react-hooks/rules-of-hooks': 'error',

    // Custom rule: warn when useState is used for values derivable from props
    // (This requires a custom ESLint plugin — the team built one)
    'custom/no-derived-state': 'warn',
  }
};