Design Frontend Component

2. Verified Component Design Procedure

The Atomic Design Hierarchy

ATOMS       → Smallest units (Button, Input, Label)
  ↓
MOLECULES   → Simple groups (SearchBar = Input + Button)
  ↓
ORGANISMS   → Complex sections (Header = Logo + Nav + SearchBar)
  ↓
TEMPLATES   → Page layouts (wireframes)
  ↓
PAGES       → Actual instances with real data

Phase 1: Component Planning

Before writing code, answer these questions:

1. What is the single responsibility of this component?

   • ❌ "It handles the user profile, settings, and notifications"
   • ✅ "It displays user profile information"

2. What category is it? (Atom, Molecule, Organism)

   • Atom: Basic building block (Button, Input, Icon)
   • Molecule: Combination of atoms (Form field with label and error)
   • Organism: Complex UI section (Navigation bar, Product card)

3. What data does it need?

   • Props (from parent)
   • Local state (UI-only)
   • Global state (context/store)

4. What actions can users take?

   • Events to emit/handle
   • Side effects (API calls, navigation)

Phase 2: Component Structure

File organization:

components/
├── atoms/
│   ├── Button/
│   │   ├── Button.tsx
│   │   ├── Button.test.tsx
│   │   ├── Button.stories.tsx  (Storybook)
│   │   └── index.ts
│   └── Input/
│       ├── Input.tsx
│       └── ...
├── molecules/
│   └── SearchBar/
│       ├── SearchBar.tsx
│       └── ...
└── organisms/
    └── Header/
        ├── Header.tsx
        └── ...

Component template:

// components/atoms/Button/Button.tsx
import { ReactNode } from 'react';
import styles from './Button.module.css';

export interface ButtonProps {
  /** The button's content */
  children: ReactNode;
  /** Visual variant */
  variant?: 'primary' | 'secondary' | 'danger';
  /** Size of the button */
  size?: 'small' | 'medium' | 'large';
  /** Disabled state */
  disabled?: boolean;
  /** Click handler */
  onClick?: () => void;
  /** Additional CSS classes */
  className?: string;
}

export function Button({
  children,
  variant = 'primary',
  size = 'medium',
  disabled = false,
  onClick,
  className = '',
}: ButtonProps) {
  return (
    <button
      className={`${styles.button} ${styles[variant]} ${styles[size]} ${className}`}
      disabled={disabled}
      onClick={onClick}
      type="button"
    >
      {children}
    </button>
  );
}

Phase 3: Props Design

Principles:

1. Keep props flat and simple

   // ❌ BAD: Nested props
   interface BadProps {
     user: {
       profile: {
         personal: {
           name: string;
         }
       }
     }
   }
   
   // ✅ GOOD: Flat props
   interface GoodProps {
     userName: string;
     userEmail: string;
     userAvatar: string;
   }
   

2. Use discriminated unions for variants

   // ✅ Type-safe variants
   type ButtonProps =
     | { variant: 'link'; href: string }
     | { variant: 'button'; onClick: () => void };
   

3. Provide sensible defaults

   function Card({
     variant = 'outlined',  // Default value
     elevation = 1,
     padding = 'medium'
   }: CardProps) {
     // ...
   }
   

Phase 4: State Management

Decision tree for state location:

Is it server data (API)?
├─ YES → Use React Query / SWR / TanStack Query
└─ NO → Continue

Does more than one component need it?
├─ YES → Use Context / Redux / Zustand
└─ NO → Continue

Is it just UI state (open/closed, hover)?
├─ YES → Use local useState
└─ NO → Reconsider if state is needed

Example: Proper state management

// ❌ BAD: Everything in component state
function UserProfile() {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);
  const [isEditing, setIsEditing] = useState(false);  // UI state
  const [theme, setTheme] = useState('light');         // Global state

  useEffect(() => {
    setLoading(true);
    fetch('/api/user')
      .then(res => res.json())
      .then(setUser)
      .catch(setError)
      .finally(() => setLoading(false));
  }, []);

  // ... rest of component
}

// ✅ GOOD: Separate concerns
function UserProfile() {
  // Server state (React Query)
  const { data: user, isLoading, error } = useQuery({
    queryKey: ['user'],
    queryFn: fetchUser
  });

  // Global state (Context)
  const { theme } = useTheme();

  // Local UI state
  const [isEditing, setIsEditing] = useState(false);

  // ... rest of component
}

Phase 5: Composition Over Prop Drilling

Avoid prop drilling:

// ❌ BAD: Prop drilling
function App() {
  const user = useUser();
  return <Dashboard user={user} />;
}

function Dashboard({ user }) {
  return <Sidebar user={user} />;
}

function Sidebar({ user }) {
  return <UserMenu user={user} />;
}

function UserMenu({ user }) {
  return <div>{user.name}</div>;
}

// ✅ GOOD: Use context for deeply nested data
const UserContext = createContext<User | null>(null);

function App() {
  const user = useUser();
  return (
    <UserContext.Provider value={user}>
      <Dashboard />
    </UserContext.Provider>
  );
}

function UserMenu() {
  const user = useContext(UserContext);
  return <div>{user.name}</div>;
}

Composition patterns:

// ✅ Render props pattern
function DataFetcher({ url, children }) {
  const { data, loading } = useFetch(url);
  return children({ data, loading });
}

<DataFetcher url="/api/users">
  {({ data, loading }) => loading ? <Spinner /> : <UserList users={data} />}
</DataFetcher>

// ✅ Compound components pattern
function Tabs({ children }) {
  const [activeTab, setActiveTab] = useState(0);
  return (
    <TabsContext.Provider value={{ activeTab, setActiveTab }}>
      {children}
    </TabsContext.Provider>
  );
}

Tabs.List = function TabsList({ children }) { /* ... */ };
Tabs.Tab = function Tab({ children, index }) { /* ... */ };
Tabs.Panel = function TabPanel({ children, index }) { /* ... */ };

// Usage
<Tabs>
  <Tabs.List>
    <Tabs.Tab index={0}>Profile</Tabs.Tab>
    <Tabs.Tab index={1}>Settings</Tabs.Tab>
  </Tabs.List>
  <Tabs.Panel index={0}><ProfileContent /></Tabs.Panel>
  <Tabs.Panel index={1}><SettingsContent /></Tabs.Panel>
</Tabs>

Phase 6: Performance Optimization

Only optimize when needed, but follow these patterns:

// ✅ Memoize expensive calculations
function ProductList({ products, filters }) {
  const filteredProducts = useMemo(() => {
    return products.filter(p => matchesFilters(p, filters));
  }, [products, filters]);

  return <div>{filteredProducts.map(p => <ProductCard key={p.id} {...p} />)}</div>;
}

// ✅ Memoize callbacks passed to children
function ParentComponent() {
  const handleClick = useCallback(() => {
    console.log('Clicked');
  }, []);

  return <ChildComponent onClick={handleClick} />;
}

// ✅ Memoize components that render often
const ExpensiveComponent = memo(function ExpensiveComponent({ data }) {
  // Complex rendering logic
  return <div>{/* ... */}</div>;
});

// ❌ DON'T memoize everything (premature optimization)
const SimpleComponent = memo(function SimpleComponent({ text }) {
  return <div>{text}</div>;  // Too simple to benefit from memo
});

3. Extended Patterns and Examples

For detailed code examples, see reference.md:

• Component Design Patterns: Container/Presenter, Custom Hooks, Error Boundaries
• Styling Best Practices: CSS Modules, Styled Components, Design Tokens
• Testing Patterns: Behavior-driven testing with Testing Library
• Advanced Patterns: HOCs, Slots, Reducers, Accessibility, Performance

Quick reference summary:

4. Failed Attempts (Negative Knowledge Evolution)

5. Component Design Checklist

Before committing: Single Responsibility ✓ | Size <300 lines ✓ | Props Typed ✓ | No Prop Drilling ✓ | Accessible ✓ | Tested ✓ | Documented ✓ | Styled with tokens ✓ | Unique keys in lists ✓

6. Governance

• Token Budget: ~390 lines (within 400 recommended limit)
• Extended Reference: See reference.md for detailed patterns and examples
• Dependencies: React 18+, TypeScript 5+, Testing Library
• Pattern Origin: Atomic Design (Brad Frost), React Best Practices
• Verification Date: 2026-01-01