Component Sizing Strategy

Component Categories

Leaf Components

Button, Input, Tag, Badge, Avatar, IconButton

• block-size: defined by the component via padding-block, line-height, font-size, min-block-size, and size variants (sm / md / lg).
• inline-size: default auto (hug content). Provide an explicit fill variant when full-width is needed — never default to w-full.
• Height tokens couple tightly with touch targets, text baselines, and icon size — do not let the parent stretch them arbitrarily. Flex containers default to align-items: stretch, which will override min-block-size and pull the component taller. Defend with an explicit block-size on the component root or align-self: center.

Typical height scale for controls:

Width API pattern:

type Width = 'auto' | 'fill';

• auto → inline-size: auto
• fill → inline-size: 100%

Container Components

Card, List, Section, FormGroup, Panel

• inline-size: default 100% — fills the parent. The parent (or a page shell) controls max-inline-size. This assumes normal flow; inside a flex row, use flex: 1 instead of width: 100% to fill available space.
• block-size: default auto — content determines height. Only constrain with max-block-size + overflow: auto when the container must scroll.

Overlay / Strong-Layout Components

Dialog, Drawer, Sidebar, Popover, Toast

• Own their sizing contract as part of their API — default min-inline-size, max-inline-size, and sometimes explicit block-size are expected.
• These are the exception where a component legitimately ships fixed dimensional constraints.

Sizing Contract: Who Owns What

Component owns

• padding
• gap
• line-height / font-size
• min-block-size
• Optional min-inline-size / max-inline-size (for safety bounds, e.g. Button min-width, Input min-width, Popover max-width)
• Truncation / overflow behavior
• Icon size

Parent / container owns

• Placement and available inline space
• Grid / flex distribution
• Page-level max-inline-size
• Section spacing
• Viewport adaptation

Principle: the component defines "what it looks like and the minimum space it needs"; the container defines "how much space it gets in this context".

Flex Layout Pitfalls

Many sizing failures in practice are not about missing width — they are about flex/grid item defaults.

min-width: auto on flex and grid items

By spec, flex items default to min-width: auto, which prevents them from shrinking below their content size when overflow is visible (the default). Long text or large children can blow out the layout. Grid items have the same automatic minimum size behavior.

Fix: apply min-w-0 on items that should allow content to truncate. Setting overflow: hidden on the item also bypasses the automatic minimum, but min-w-0 is the more surgical fix — it doesn't clip content on the cross axis.

Trailing elements getting squeezed

Side elements (status indicator, action button) can shrink when the main content pushes against them.

Fix: apply shrink-0 on elements that must maintain their intrinsic size.

Typical row pattern:

<div className="flex items-center gap-3 px-4 py-3">
  <Icon className="shrink-0" />
  <span className="min-w-0 truncate">{label}</span>
  <StatusDot className="shrink-0" />
</div>

Storybook Verification

Storybook is a verification tool, not the sizing strategy itself. Use it to prove the component's sizing contract holds across contexts:

export const NarrowContainer: Story = {
  decorators: [
    (Story) => (
      <div className="w-64">
        <Story />
      </div>
    ),
  ],
};

export const WideContainer: Story = {
  decorators: [
    (Story) => (
      <div className="w-[720px]">
        <Story />
      </div>
    ),
  ],
};

export const FlexRow: Story = {
  decorators: [
    (Story) => (
      <div className="flex gap-2">
        <Story />
        <Story />
      </div>
    ),
  ],
};

If a component only looks right inside one specific container width, its sizing contract is underspecified.

Quick Reference