how easy the component is to use
how hard it is to misuse
how stable it is across product changes
how safely it can evolve
how much state leaks into callers
how many bugs become impossible by design

A component API should expose intent, not implementation accidents.

prop names
prop value semantics
callback timing
callback payload
children/slot structure
controlled/uncontrolled behavior
DOM/ref exposure
accessibility guarantees
styling hooks
state reset semantics
async/pending/error behavior
versioning and migration rules

<CaseStatusBadge status="under_review" />

status under_review has a stable visual meaning
invalid status is rejected or handled explicitly
component renders semantically appropriate markup
caller does not need to know internal class names
future status additions won't break existing callers silently

<DataTable
  rows={rows}
  sort={sort}
  onSortChange={setSort}
  isLoading={isLoading}
/>

caller owns rows
caller owns sorting state
DataTable may request sorting transition
caller owns loading state
DataTable owns rendering and interaction semantics

<DataTable
  data={rows}
  config={{ sortable: true, filterable: true }}
  onChange={handleChange}
/>

Who owns sort state?
Who owns filter state?
What does onChange mean?
Does data table mutate data?
Does config affect state reset?

What is the smallest useful thing a caller wants to express?
What is the most advanced thing a caller may need later?
Which details must remain private?
Which extension points are intentional?
Which states must be impossible?

<Modal open={open} onOpenChange={setOpen}>
  <Modal.Content>
    <Modal.Title>Reject case?</Modal.Title>
    <Modal.Description>This action requires a reason.</Modal.Description>
    <RejectCaseForm />
  </Modal.Content>
</Modal>

there is a modal
open state is controlled
content has title and description
form lives inside modal

portal implementation
focus trap implementation
escape listener implementation
aria wiring implementation
scroll lock implementation

<Button variant="primary" size="md" disabled={isSubmitting}>
  Submit
</Button>

variant
size
disabled
children
className

const combobox = useCombobox({ items, value, onValueChange })

state
keyboard behavior
ARIA attributes
prop getters
item registry

<Tabs value={tab} onValueChange={setTab}>
  <Tabs.List>
    <Tabs.Trigger value="overview">Overview</Tabs.Trigger>
    <Tabs.Trigger value="audit">Audit</Tabs.Trigger>
  </Tabs.List>
  <Tabs.Content value="overview">...</Tabs.Content>
  <Tabs.Content value="audit">...</Tabs.Content>
</Tabs>

parent-child coordination
context boundary
required parts
ordering
keyboard behavior
controlled/uncontrolled behavior

<EnforcementCaseCard
  case={enforcementCase}
  currentUserCapabilities={capabilities}
  onOpenCase={openCase}
  onAssignCase={assignCase}
/>

domain vocabulary
permission semantics
business lifecycle
empty/error/pending state

<CaseActionButton
  flag
  mode="x"
  handler={fn}
  data={caseObj}
/>

<CaseActionButton
  action="escalate"
  caseRecord={caseRecord}
  disabledReason={disabledReason}
  onRequestAction={handleRequestAction}
/>

flag                    → meaningless
mode                    → vague
handler                 → mechanism
onRequestAction         → intent event
caseRecord              → domain object
disabledReason          → explicit UX and business state

<Button primary secondary danger ghost loading disabled />

primary + secondary
danger + ghost + primary
loading + disabled but clickable

<Button variant="primary" tone="danger" isLoading={isSubmitting} />

type ButtonProps =
  | {
      variant: 'solid'
      tone?: 'neutral' | 'danger' | 'success'
    }
  | {
      variant: 'ghost'
      tone?: 'neutral' | 'danger'
    }
  | {
      variant: 'link'
      tone?: 'neutral'
    }

<Tabs defaultValue="overview" />

<Tabs value={tab} onValueChange={setTab} />

value          → controlled state
onValueChange  → request to change controlled state
defaultValue   → initial uncontrolled state

function useControllableState<T>({
  value,
  defaultValue,
  onChange,
}: {
  value?: T
  defaultValue: T
  onChange?: (nextValue: T) => void
}) {
  const [internalValue, setInternalValue] = React.useState(defaultValue)
  const isControlled = value !== undefined
  const currentValue = isControlled ? value : internalValue

  const setValue = React.useCallback(
    (nextValue: T) => {
      if (!isControlled) {
        setInternalValue(nextValue)
      }
      onChange?.(nextValue)
    },
    [isControlled, onChange]
  )

  return [currentValue, setValue] as const
}

warn if component switches from uncontrolled to controlled
warn if component switches from controlled to uncontrolled
warn if value is provided without onValueChange for mutable component

notification callback
intent callback
lifecycle callback

<Tabs onValueChange={setTab} />

selected tab changed or wants to change

<CaseActions onRequestEscalation={requestEscalation} />

user expressed intent to escalate

<Modal onOpenAutoFocus={handleAutoFocus} onCloseComplete={handleCloseComplete} />

onChange={(event) => ...}

<CaseTable
  onSelectionChange={(selection) => {
    console.log(selection.selectedCaseIds)
  }}
/>

type CaseSelectionChange = {
  selectedCaseIds: string[]
  source: 'row-click' | 'checkbox' | 'keyboard' | 'bulk-action'
}

type SortChange = {
  field: 'createdAt' | 'priority' | 'status'
  direction: 'asc' | 'desc'
}

onSort={(event, column, desc) => ...}

<PageHeader
  title="Cases"
  buttons={[
    { label: 'Export', icon: 'download', onClick: exportCases },
    { label: 'Create', icon: 'plus', onClick: createCase },
  ]}
/>

custom tooltip
permission wrapper
loading button
split button
confirmation dialog
keyboard shortcut badge
tracking metadata

<PageHeader
  title="Cases"
  actions={
    <>
      <ExportCasesButton />
      <CreateCaseButton />
    </>
  }
/>

If variation is data-like, use config.
If variation is UI structure or behavior, use composition.

<StatusBadge status="approved" />

<Card
  title="Investigation"
  actions={<CaseActionMenu caseId={caseId} />}
/>

<Card>
  <CaseSummary />
</Card>

<Card
  header={<CaseHeader />}
  footer={<CaseFooter />}
>
  <CaseSummary />
</Card>

<Card>
  <Card.Header>
    <CaseHeader />
  </Card.Header>
  <Card.Body>
    <CaseSummary />
  </Card.Body>
  <Card.Footer>
    <CaseFooter />
  </Card.Footer>
</Card>

type EmptyStateProps = {
  loading?: boolean
  error?: Error
  empty?: boolean
  data?: CaseRecord[]
}

loading + error + empty + data

type CaseListState =
  | { status: 'loading' }
  | { status: 'error'; error: Error; onRetry: () => void }
  | { status: 'empty'; message: string }
  | { status: 'ready'; cases: CaseRecord[] }

<CaseListView state={state} />

function CaseListView({ state }: { state: CaseListState }) {
  switch (state.status) {
    case 'loading':
      return <CaseListSkeleton />
    case 'error':
      return <ErrorState error={state.error} onRetry={state.onRetry} />
    case 'empty':
      return <EmptyState message={state.message} />
    case 'ready':
      return <CaseList cases={state.cases} />
  }
}

<SubmitButton onClick={submit} />

Does button disable while submitting?
Who catches error?
Can user click twice?
Does loading indicator show?
Can caller cancel?
What happens after success?

<SubmitButton
  isSubmitting={isSubmitting}
  disabledReason={disabledReason}
  onSubmit={submit}
/>

type SubmitCommand = {
  execute: () => Promise<void>
  isPending: boolean
  error?: Error
  canExecute: boolean
  disabledReason?: string
}

<SubmitButton command={submitCommand} />

Can user trigger it twice before first result returns?

<ApproveCaseButton onApprove={approveCase} />

<ApproveCaseButton
  isPending={approveMutation.isPending}
  disabledReason={reason}
  onApprove={approveCase}
/>

function ApproveCaseButton({ isPending, disabledReason, onApprove }: Props) {
  const disabled = isPending || Boolean(disabledReason)

  return (
    <button disabled={disabled} onClick={onApprove}>
      {isPending ? 'Approving...' : 'Approve'}
    </button>
  )
}

caller owns command execution
caller exposes pending state
button prevents duplicate local interaction
server still must enforce idempotency

<CaseTransferDialog caseId={caseId} />

<CaseTransferDialog
  open={open}
  onOpenChange={setOpen}
  assignees={assignees}
  isLoadingAssignees={isLoadingAssignees}
  submitState={submitState}
  onSubmitTransfer={submitTransfer}
/>

caller owns data fetching
caller owns submit mutation
component renders known states
component does not invent cache policy

Dialog traps focus while open
Dialog restores focus on close
Tabs expose selected tab to assistive tech
Menu supports keyboard navigation
Form field connects label, input, description, and error
Disabled controls communicate disabled semantics

<FormField name="reason">
  <FormField.Label>Reason</FormField.Label>
  <FormField.Control asChild>
    <textarea />
  </FormField.Control>
  <FormField.Error />
</FormField>

className
data-state attributes
CSS variables
style prop
theme tokens
variant props
slot classNames
unstyled/headless mode

<button
  className={cn(buttonVariants({ variant, size }), className)}
  data-state={isPressed ? 'pressed' : 'idle'}
  data-disabled={disabled ? '' : undefined}
>
  {children}
</button>

className applies to root element
data-state values are stable
variant names are stable
internal DOM structure is not guaranteed unless documented

ref.current.internalState = ...
ref.current.domNode.querySelector(...)

type ModalHandle = {
  focusFirstField: () => void
}

const modalRef = React.useRef<ModalHandle>(null)

<CaseModal ref={modalRef} />

function CaseModal({ ref }: { ref: React.Ref<ModalHandle> }) {
  const firstFieldRef = React.useRef<HTMLInputElement>(null)

  React.useImperativeHandle(ref, () => ({
    focusFirstField() {
      firstFieldRef.current?.focus()
    },
  }))

  return <input ref={firstFieldRef} />
}

Expose capability, not internal structure.

<DataGrid
  rows={rows}
  renderCell={(row, col) => <Cell row={row} col={col} />}
  getRowClassName={(row) => expensive(row)}
/>

callbacks may be called many times
callbacks must be pure
callbacks should be stable for large data
cell renderers should not perform side effects

<DataGrid
  rows={rows}
  columns={columns}
  getRowId={(row) => row.id}
  virtualized
/>

rows.map(row => columns.map(col => computeExpensive(row, col)))

getRowId
column id
item key
selector
render memo boundary

add optional prop
add new variant value
add new compound part
add new callback with clearer semantics
support both old and new names temporarily

same prop name, different meaning
same callback, different timing
same variant, different accessibility behavior
same ref, different target

type OldProps = {
  onClose?: () => void
}

type NewProps = {
  open: boolean
  onOpenChange: (open: boolean) => void
}

function Dialog(props: OldProps & Partial<NewProps>) {
  if (process.env.NODE_ENV !== 'production') {
    if (props.onClose) {
      console.warn('Dialog onClose is deprecated. Use onOpenChange(false).')
    }
  }

  // compatibility layer here
}

<CasePanel
  data={caseRecord}
  showHeader
  showAudit
  canEdit
  canClose
  closeText="Close"
  onClick1={edit}
  onClick2={close}
  loading={loading}
  error={error}
/>

prop names are generic
callbacks don't reveal intent
visibility flags encode layout details
permission and action state are mixed
loading/error ownership is unclear
component is hard to extend

<CasePanel caseRecord={caseRecord} state={panelState}>
  <CasePanel.Header
    actions={
      <CaseActions
        capabilities={capabilities}
        onRequestEdit={editCase}
        onRequestClosure={closeCase}
      />
    }
  />
  <CasePanel.Body />
  <CasePanel.AuditTrail auditEvents={auditEvents} />
</CasePanel>

CasePanel owns layout semantics
CaseActions owns action rendering
caller owns capabilities and commands
AuditTrail receives explicit audit model
panelState represents loading/error/ready explicitly

<CasePanel.AuditTrail
  state={auditState}
  onRetry={refetchAudit}
/>

What is the component's responsibility?
What is explicitly outside its responsibility?
Who owns each state value?
Which props are data inputs?
Which props are commands?
Which props are render slots?
Which props are styling hooks?
Which combinations are illegal?
Can illegal combinations be represented by the type?
What does each callback mean?
When does each callback fire?
Does callback payload expose intent or implementation?
Is accessibility default or optional?
Does ref expose capability or internals?
How does the component handle pending/error/disabled?
What is stable across releases?
What can change without breaking callers?
How would we test this contract?

many booleans controlling layout
prop named config with many nested flags
callback named handleSomething
callback payload is raw implementation detail
component both fetches data and renders reusable UI
component mutates external store directly
component exposes internal DOM through ref
component requires caller to know internal class structure
component has multiple sources of truth
component accepts any children but expects specific children
component has undocumented order dependency

<Table data={data} />

<Table
  rows={rows}
  getRowId={(row) => row.id}
  sort={sort}
  onSortChange={setSort}
  selection={selection}
  onSelectionChange={setSelection}
  state={tableState}
/>

clarity over terseness
invariants over convenience
composition over prediction
migration over one-off hacks

shows case summary
supports approve, reject, request changes
some actions may be disabled by permission
reject requires reason
submit is async
panel can be embedded in modal or full page
caller owns mutation and audit logging
component must be testable without backend

state ownership table
event contract table
illegal states list
accessibility requirements
extension points

<ReviewDecisionPanel
  caseSummary={caseSummary}
  availableDecisions={availableDecisions}
  selectedDecision={selectedDecision}
  onSelectedDecisionChange={setSelectedDecision}
  reason={reason}
  onReasonChange={setReason}
  submitState={submitState}
  onSubmitDecision={submitDecision}
/>

<ReviewDecisionPanel state={panelState} onSubmitDecision={submitDecision}>
  <ReviewDecisionPanel.Summary caseSummary={caseSummary} />
  <ReviewDecisionPanel.DecisionOptions />
  <ReviewDecisionPanel.ReasonField />
  <ReviewDecisionPanel.Actions />
</ReviewDecisionPanel>

Expose intent, not internal mechanism.
Name props using domain meaning where appropriate.
Make state ownership explicit.
Separate notification, intent, and lifecycle callbacks.
Prefer JSX composition for structural variation.
Use config for data-like variation.
Prevent illegal states with types and runtime guardrails.
Expose accessibility as part of the contract.
Expose styling hooks intentionally.
Expose ref capabilities narrowly.
Design for migration before the API becomes popular.