component-design

Component Design Patterns Skill

Expertise: Compound components, controlled/uncontrolled, render props, component API design, accessibility requirements.

When to load

When creating, refactoring, or reviewing React components — especially when choosing between compound, controlled/uncontrolled, or headless patterns, designing typed prop APIs, or implementing accessible interactive widgets.

Component Design Workflow

1. Choose pattern — use the decision tree below to select the right component pattern
2. Define typed props — follow the Props API Design Rules (explicit variants, no boolean explosion)
3. Implement all states — loading, error, empty, success for any async data
4. Add accessibility — use the ARIA requirements table to add correct roles and keyboard support
5. Verify — confirm keyboard navigation works, screen reader announces states, and TypeScript compiles with --strict

Pattern Selection Guide

Multiple visual zones in one component?         → Slot / Children Props
Coordinated subcomponents sharing state?        → Compound Components
Works with react-hook-form / external control?  → Controlled/Uncontrolled Hybrid
Self-contained widget with internal state?      → Uncontrolled with defaults
Highly customizable rendering?                  → Render Props / Headless

Pattern 1: Compound Components

Use when: a component has multiple coordinated parts sharing implicit state.

// Context shared between sub-components
const MenuContext = createContext<{ open: boolean; toggle: () => void } | null>(null);

const Menu = ({ children }: { children: React.ReactNode }) => {
  const [open, setOpen] = useState(false);
  return (
    <MenuContext.Provider value={{ open, toggle: () => setOpen(o => !o) }}>
      <div role="menu" aria-expanded={open}>{children}</div>
    </MenuContext.Provider>
  );
};

Menu.Trigger = function MenuTrigger({ children }: { children: React.ReactNode }) {
  const ctx = useContext(MenuContext)!;
  return (
    <button onClick={ctx.toggle} aria-haspopup="true" aria-expanded={ctx.open}>
      {children}
    </button>
  );
};

Menu.Items = function MenuItems({ children }: { children: React.ReactNode }) {
  const { open } = useContext(MenuContext)!;
  if (!open) return null;
  return <ul role="listbox">{children}</ul>;
};

// Usage — caller controls structure
<Menu>
  <Menu.Trigger>Options</Menu.Trigger>
  <Menu.Items>
    <li role="option">Edit</li>
    <li role="option">Delete</li>
  </Menu.Items>
</Menu>