Composition

Compose structure and behavior

Card groups related content; its header and title establish hierarchy. Dialog supplies modal behavior, while its trigger, content, title and footer declare the composition. These parts remain ordinary React elements with explicit responsibilities.

Use real Button and Link components for interaction. A Card surface is not automatically a button. Avoid nested buttons, links inside links and clickable generic div elements.

Let the application own the workflow

Use controlled state when other parts of your application need to read or change a value. Use a default value when a component can own its local interaction. Verify the exact callback in the API: not every family calls it onChange.

For example, the styled Select uses onValueChange. Form integration needs the real name and value contract, rather than assuming that a styled control behaves exactly like a native select element.

Choose the smallest useful abstraction

Table provides semantic markup; DataTable adds common local data behavior; DataGrid handles richer ownership and column features. Start with the simplest family that meets the workflow.

DashboardLayout composes a workspace with sidebar and navbar. AppShell is a general layout structure. Keep responsive behavior and landmark names explicit when combining layouts, and avoid nested main regions.

Keep trigger props intact

DialogTrigger, Tooltip and other wrappers depend on their child forwarding props and a ref. Pimolu Button supports this composition. If you create a custom trigger, retain its accessible name, event handlers and focus target.