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 supplies styled panels and a separator but no resizing interaction.
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; choose as="a" explicitly.
Do not use Box as a replacement for inputs, buttons, links, table parts, or dialogs.
Do not assume an open prop creates an onOpenChange callback. Use the callbacks documented by the specific component and native disclosure events where needed.

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.