Layout & density

Size and density

size changes an individual component. data-density changes control heights, padding and gaps throughout a region. The default is comfortable; compact increases information density without changing text hierarchy or automatically responding to viewport width.

Both groups below use the default component size and inherit different densities.

Pixel values assume a 16px root font size. Compact layouts still need clear interaction targets; do not shrink every button simply to fit more content. When an overlay uses Portal, its destination must also inherit the density. Set global density on the root element; check the actual overlay destination when using a local density.

Spacing and alignment

Use Stack and Inline for groups, and Grid for columns. Space within a group should be smaller than space between groups. Avoid combining a parent’s gap with equivalent margins on its children.

Default gaps use density tokens. Explicit xs, sm, lg and xl values use the fixed spacing defined by each component. Let FormField arrange labels, descriptions and controls. Use Page or AppShell for page structure.

Prefer logical directions such as ms, me, ps, pe, start and end to preserve alignment in RTL. On narrow screens, adjust columns, wrapping and region order before compressing spacing.

Radii

Radii describe shape, not interaction state. Use existing component radii or pill options instead of changing corner shapes for hover, selection or errors. Check nested radii together with their spacing so inner outlines do not crowd outer corners.

Elevation

shadow-sm, shadow-md and shadow-lg map to theme-specific shadows. Separate content through spacing and borders first, then use shadows for raised surfaces. Nested containers do not each need a shadow.

Card provides a content surface. Overlays such as Popover and Dialog handle their own positioning, stacking and focus. Avoid arbitrary application-level z-index additions to repair overlay order.