Component composition

Keep layout and behavior with the component; let its caller supply finished pieces of UI. Design the interface around the component's own responsibilities. Let callers compose content and actions instead of configuring nested UI through data, flags, and callbacks.

Components must have no more than five props, excluding children and UI slots. If an interface exceeds this limit, use composition to move UI regions and their configuration to the caller. Only genuine UI slots are exempt; renaming a configuration prop does not make it a slot.

Sort every prop first

Keep native DOM props, accessibility attributes, refs, and controlled-state contracts intact. A boolean that changes a class is not automatically a second component. Domain data also belongs on a feature component that actually owns its behavior; do not turn every domain value into JSX.

Choose the simplest pattern

1. Children for the main content. Start here.
2. Slots for a small, fixed set of regions. Type <role>Slot as ReactNode; place the value without inspecting it. Prefer actionsSlot={<ConnectButton connection={connection} />} to a label, visibility flag, disabled flag, and callback. Follow an existing local slot name when present.
3. Render props only when content needs state owned by the component. Expose a minimal typed argument, not the component's full store or internal implementation.
4. Compound parts when callers vary the presence, order, or configuration of regions. Reuse existing parts before introducing new wrappers.
5. Separate components when a mode selects another layout or interaction contract. Share parts underneath; keep small visual variants on the root.
6. Wrap and specialize an existing primitive when only defaults or feature wiring differ. Preserve its native and accessibility behavior instead of re-describing its API.

Choose a more structured pattern only when it reduces what real callers have to know. Bundling props in options, renaming configuration to xSlot, or splitting internals while keeping the same prop-heavy interface does not transfer ownership.

Compound parts

• Name parts after their root and role: ConnectionSummaryContent, ConnectionSummaryActions. Use roles such as Header, Title, Description, Content, Footer, Actions, Media, Icon, Group, Item, Separator, Trigger, and Label only where they have a job.
• A simple layout part renders one semantic element, accepts that element's props, merges className, and forwards the remaining props and refs according to the local primitive's API. Zero to two custom props is a useful heuristic, not a limit for headless primitives or controls.
• Keep layout parts optional and let CSS adapt to their presence. Do not add hasAction or inspect, clone, or identify children to discover the layout. Semantic requirements still apply: a dialog needs an accessible name, and interactive parts need their provider and relationships.
• Keep whole-component appearance on the root. Use existing classes or data-* attributes and scoped CSS selectors for parts; do not add context merely to distribute size or spacing.
• Reuse the headless primitive's context/store for shared interactions. Add a local typed context only for behavior state that parts genuinely share; follow neighboring context and hook naming.
• A default sub-part can sit behind a convenience boolean if it is also exposed for callers needing control. Do not accumulate booleans to configure that default part.

Read EXAMPLES.md for worked examples using slots and compound parts.