Component API review

Run this checklist in order. A "no" on the first five questions usually means redesign, not patching.

1. Can I describe the component in one sentence without "and"?

If the pitch is "a table and a filter panel and export", it's three components wearing one badge. Split.

2. Props: nouns not adjectives-soup

• Data props (what to render) vs behavior props (what to do) vs style props (rare).

• 5 booleans → the component has modes; extract variants or split components.

• Booleans named isXxxDisabledWhenYyy are logic leaking into API — compute in the caller.

3. Controlled, uncontrolled, or both — declared explicitly

// the React idiom for "both"
const [value, setValue] = useControlled({
  value: props.value,
  defaultValue: props.defaultValue,
  onChange: props.onChange,
})

A component that is sometimes controlled and sometimes mutates internal state without saying so is a bug factory.

4. Composition over configuration

Prefer children/slots over prop-driven DOM:

// ❌ 12 layout props
<Card titleAlign="left" footerBorder={false} actionsPosition="top" ... />

// ✅ slots
<Card>
  <Card.Header>Title</Card.Header>
  <Card.Body>...</Card.Body>
  <Card.Footer>...</Card.Footer>
</Card>

Render props / children-as-function for cross-component coupling (render prop <Select>{(items) => ...}</Select>), never for trivial layout.

5. Escape hatches exist

Every abstraction is wrong for someone. Provide, in order of preference:

1. className/styling hook — cosmetic overrides
2. slot/render props — structural overrides
3. a real escape: asChild/Component polymorphism — behavioral overrides

If users need !important and DOM hacking, the API failed.

6. Events name outcomes, not gestures

onCollapse, onSelectionChange (intent) beat onClick, onMouseMove (raw gesture) — the latter belongs on the underlying element anyway.

7. Accessibility is part of the API

• The contract includes roles/keyboard behavior; document which ARIA pattern it implements.
• Slotting arbitrary children must not break semantics (a <div> inside <ul> is a violation the component must prevent or sanitize).

8. Refs & SSR

• Forward refs; the DOM node is part of the contract.
• No window/document at module top or during render — guard for SSR.

Definition of done (agent checklist)

• One-sentence pitch, no "and"
• Controlled/uncontrolled story explicit
• Slots for structure, props for data, minimal booleans
• Escape hatch documented
• Keyboard + ARIA behavior documented and tested
• Ref forwarding + SSR safe