Component limitations and pitfalls

Know which components provide complete interaction, which are structural primitives, and what applications still own.

Know which components are structural

Portal currently returns children in place. It does not mount into document.body or another DOM container.
Resizable includes pointer and keyboard resizing, but does not save sizes or resize an unrelated sibling. The application owns persistence and the surrounding layout.
Overlay supplies scrim and centering only; it does not add modal semantics, focus trapping, Escape handling, or scroll locking.
FocusTrap manages Tab cycling only; it does not create a complete dialog or restore focus after unmount.

Do not depend on generated class names or undocumented DOM nesting.
Do not pass a caption prop to Table.Root; render Table.Caption as a child.
Do not put multiple independently labelled controls in one Field and expect all of them to receive wiring.
Do not render Button with href and assume it becomes a link; compose it with Link explicitly.
Do not use Box as a replacement for inputs, buttons, links, table parts, or dialogs.
Use the documented state API: Dialog and Sheet request dismissal through onClose, while Popover, DropdownMenu, and Collapsible support open with onOpenChange.

Test keyboard behavior, focus order, and visible focus for every interactive composition.
Verify labels, descriptions, errors, current-page state, and dynamic announcements with assistive technology.
Test controlled components when values are missing, stale, empty, or outside the available item set.
Check long labels, localized content, reduced motion, high zoom, narrow viewports, and both color modes.
Use public props and compound members only. Treat internal classes and element nesting as implementation details.