Component Sizing Principles

Component sizing principles

Component heights and icon sizes are curated, not formula-derived. A good ladder picks each height so it pairs cleanly with a font from the type scale, an icon from the icon set, and target-size requirements — and so each rung distinguishes visually from its neighbors. This skill names the universal principles; it is deliberately system-neutral. For one concrete instantiation — the per-density rung sets with their exact heights, fonts, and icon pairings — see udts-component-sizing-ladders.

When to use

• Picking a height for a button, input, chip, badge, dropdown, or any other rectangular interactive control.
• Proposing a control-height or icon-size ladder for a new density mode.
• Auditing one-off heights (h-7, h-9, h-11) drifting across a codebase.
• Code review: flag heights outside the curated ladder; propose the nearest curated rung with rationale.

When NOT to use

• One-off marketing CTAs designed for a specific page (e.g. hero buttons at 72 px). A ladder governs recurring controls, not single-surface designs.
• Non-rectangular controls (circular avatars, range thumbs) where the size is governed by the icon or asset, not a height token.

Ladders are curated, not formula-derived

A formula height → font-size → icon-size produces mathematically clean values that render poorly. Curate the rungs by hand instead, for three reasons:

• Formula heights create visually indistinct rungs. Heights at every fixed step (24, 28, 32, 36, ...) are hard to tell apart in a stack — adjacent rungs blur, so the ladder loses its job of signalling hierarchy.
• Off-scale font sizes clash with the typography system. A formula lands on sizes like 13, 15, 17 that sit outside the modular scale and read as noise next to type set from type-scale.
• Off-curve icon sizes glitch at common zoom levels. Icon sizes outside the curated set render with hairline artifacts at ordinary zoom.

A curated ladder trades flexibility for visual distinguishability, predictable pairing, and target-size safety. Design systems benefit from less flexibility at this layer.

The rung-pairing principle

Each rung pairs its height with a font size from the type scale and a curated icon size. The pairings are fixed per rung, not chosen ad hoc per instance. One invariant holds across every rung: the icon is never smaller than the paired font size — an undersized icon next to its label reads as a rendering bug.

Ladders are conventionally labelled with T-shirt sizes (xs / sm / md / lg / xl) so the rung, its font, and its icon travel together under one name.

Curated icon sizes

Curate the icon ladder the same way you curate heights. 12, 16, 24, 32, 40, 48 is a widely-used curated set — these are the sizes at which the common icon families (Material Icons, Lucide, Heroicons, Phosphor) render cleanly without hairline glitches, and they subdivide into 4 px steps at the small end (where inline alignment matters) and 8 px steps at the large end (where it doesn't).

Don't formula-derive icon sizes. A height-to-icon ratio like icon = height / 2 produces off-curve values (14, 18, 22, ...) — every one of which renders worse than its curated neighbour.

The WCAG 2.5.8 target-size floor

Interactive control heights clear 24 CSS px per WCAG 2.5.8 AA Target Size (added in WCAG 2.2). In practice:

• Reserve the smallest rung — which may sit at or below the 24 px floor — for non-interactive elements (badges, read-only chips, density tags).
• Start interactive rungs at the first rung that clears the floor.
• In a roomier, lower-density mode whose smallest rung already exceeds 24 px, the entire ladder is interactive-safe.

Failing this floor is one of the most common WCAG 2.2 audit misses. The floor itself is defined alongside the spacing primitives in spacing-system.

Sibling consistency

Sibling controls in the same UI surface share a rung. Mixing (say) an sm and an md button next to each other reads as a typo, not a hierarchy — hierarchy comes from prominence and placement, not from a one-step height difference between neighbours.

Picking a rung

Default heuristic:

• Paired buttons and inputs: the system's default mid rung. Use the same rung for a button and its associated input so they align horizontally in a form.
• Dense table cell / compact toggle: one rung smaller than default.
• Primary CTA / hero button: one or two rungs larger than default, by prominence.
• Badge, breadcrumb separator, density tag (non-interactive): the smallest, non-interactive rung.

Verification

After picking a rung:

1. Ladder match: the rung comes from the declared density ladder, not a one-off height. Mixing rungs from different density ladders in one surface is a bug.
2. Interactive floor: the height clears 24 CSS px for interactive controls; the smallest rung is reserved for non-interactive use.
3. Font pairing: the inner font-size matches the rung's paired size from the type scale, not a free-picked value.
4. Icon pairing: the leading or trailing icon size matches the rung's paired icon, and is not smaller than the font.
5. Sibling consistency: sibling controls in the same surface share a rung.

Cross-references

• REQUIRED BACKGROUND: spacing-system — the unit primitives drive which density ladder applies, and the 24 CSS px WCAG 2.5.8 floor is defined there.
• For the font sizes paired with each rung: type-scale — the per-rung font is taken from the canonical scale, not free-picked.
• For line-heights inside each rung: line-height-grid — interactive controls use lh-ui, not lh-prose.
• For one system's worked rung sets: udts-component-sizing-ladders — concrete per-density heights with their font and icon pairings (incubating L2 stub).

Sources

• WCAG 2.5.8 — Target Size (AA, added in 2.2).
• Material Design 3 — Component sizing guidance.
• Apple Human Interface Guidelines — touch targets (44 pt mobile; relaxed to 24 CSS px desktop per WCAG).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: thrillmade
• Source: thrillmade/agent-skills
• License: MIT
• Homepage: https://logmind.dev

Install and usage instructions live in the source repository linked above.