Kombinierbare Komponenten-APIs

Component API & Composition

A shared component is only as good as its public interface. Following John Ousterhout's principle of deep modules and Nathan Curtis's component API discipline, hide internal styling, state synchronization and accessibility wiring behind a small, predictable interface while giving consumers clean composition seams.

1. Preventing Boolean Prop Explosion ("Prop Apocalypse")

• Use mutually exclusive union variants instead of conflicting booleans:
  • Bad: <Button primary secondary danger outline small large /> (allows illegal combinations like primary + danger + small + large).
  • Good: variant: 'primary' | 'secondary' | 'ghost' | 'danger' and size: 'sm' | 'md' | 'lg'.
• Do not add a prop for every one-off layout tweak: if a single screen needs an extra badge and a link inside a card header, expose a header slot / children / compound subcomponent rather than adding badgeText, badgeColor, headerLinkUrl and headerLinkLabel props to Card.

2. Composition Over Monolithic Configuration

Choose the right composition pattern for the component's complexity:

• Slots / Named Regions: for structured containers (Card, PageHeader, EmptyState, FormField, Alert), accept content slots (leadingIcon, title, actions, footer, default body) so consumers can pass rich, localized content without string-only limitations.
• Compound Components: for multi-part interactive widgets (Dialog.Root, Dialog.Trigger, Dialog.Content, Dialog.Title, Dialog.Description, Dialog.Close, or Tabs.List / Tabs.Trigger / Tabs.Panel), share internal state and ARIA IDs through component context/provide-inject while letting the consumer control structure and order cleanly.
• Controlled & Uncontrolled Parity: for stateful inputs and overlays (open / onOpenChange, value / onChange), support deterministic controlled usage and sensible uncontrolled defaults where appropriate to the framework.

3. Transparent Native Attribute & Ref Forwarding

A design-system wrapper must never swallow essential HTML semantics or event handlers:

• Forward native attributes: allow standard HTML, aria-*, data-*, id, name, disabled, type and event attributes to reach the underlying interactive DOM element (<button>, <input>, <a>).
• Safe defaults: default <button> components to type="button" unless type="submit" is explicitly passed, preventing accidental form submissions inside dialogs and toolbars.
• Ref / Element access: forward DOM refs so parent flows, focus managers and positioning engines (popovers, tooltips) can measure or focus the underlying element without reaching into undocumented .querySelector() internals.
• Encapsulated internal DOM: treat internal wrapper elements and private CSS class names as implementation details, not public API — consumers should customize via documented props, slots and semantic tokens, never by writing parent CSS selectors targeting internal child tags.