component-sizing-principles

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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](../udts-component-sizing-ladders/SKILL.md).

## 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](../type-scale/SKILL.md).
- **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](../spacing-system/SKILL.md).

## 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. Where the smallest rung sits below that floor it is reserved for non-interactive use; a ladder whose smallest rung already clears 24 px has no reserved tier.
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

- **Routed here by:** [designing-a-design-system](../designing-a-design-system/SKILL.md) — the L1 dispatcher for building or extending a system.
- **REQUIRED BACKGROUND:** [spacing-system](../spacing-system/SKILL.md) — 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](../type-scale/SKILL.md) — the per-rung font is taken from the canonical scale, not free-picked.
- **For line-heights inside each rung:** [line-height-grid](../line-height-grid/SKILL.md) — interactive controls use `lh-ui`, not `lh-prose`.
- **For one system's worked rung sets:** [udts-component-sizing-ladders](../udts-component-sizing-ladders/SKILL.md) — 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)](https://www.w3.org/TR/WCAG22/#target-size-minimum).
- Material Design 3 — Component sizing guidance.
- Apple Human Interface Guidelines — touch targets (44 pt mobile; relaxed to 24 CSS px desktop per WCAG).

From thrillmade/agent-skills, MIT.

More from thrillmade/agent-skills