Repository navigation
ADR 0003
Status: superseded · Built: planned · Date: 2026-11-18 · Superseded by: 0010
Decision only; size and type tokens land in the foundation PR.
shadcn's controls are sized for a mouse: the default button is 36px tall, sm is 32px and
icon buttons are 36px square. On a phone that's below every guideline:
| Source | Minimum target |
|---|---|
| Apple Human Interface Guidelines | 44 × 44 pt (iOS default control; 28 pt minimum) |
| Material Design | 48 × 48 dp |
| WCAG 2.2, 2.5.8 (AA) | 24 × 24 CSS px |
| WCAG 2.2, 2.5.5 (AAA) | 44 × 44 CSS px |
Web apps built on shadcn then feel different from the same product's React Native app.
vinskiano already works around it by hand (h-11). Some screens are dense and desktop-only
(spotcraft's dashboard tables, tagtape's desktop app).
1 CSS px, 1 iOS point and 1 Android dp are the same size, so one number serves all.
-
Default control size is 44px (
--size-control): buttons, inputs, selects, tabs, menu items and list rows are 44px tall; icon buttons are 44 × 44. At every screen size. -
Compact is 36px (
--size-control-compact), opt-in per control, never a global switch. Its hit area is still 44 × 44. -
Small visuals keep a 44 × 44 hit area: checkboxes, radios, switches, close buttons and chips. On the web through padding or a
::beforeoverlay, on native throughhitSlop. -
12px between targets (
--gap-control), compact layouts included. -
Text inputs are at least 16px, so iOS Safari doesn't zoom on focus.
-
Links inside running text follow the text size.
-
The type scale is Apple's iOS text styles, in rem so it follows browser zoom and text size:
Token Size / line height (px) Token Size / line height (px) large-title34 / 41 body17 / 22 title-128 / 34 callout16 / 21 title-222 / 28 subhead15 / 20 title-320 / 25 footnote13 / 18 headline17 / 22, semibold caption-112 / 16 caption-211 / 13 -
Nothing smaller than 11px. No thin, extra-light or light weights for text. Brands change the fonts, not the steps.
-
Components use these tokens; they never hardcode heights like
h-9.
- Web and native controls measure the same, and both meet WCAG 2.5.5 (AAA) by default.
- Dense desktop screens get taller than shadcn's defaults, unless they opt in to compact.
- Body text is 17px, not the web's usual 16px.
- shadcn components keep their names but take spotstrap's heights.
- A test renders every control at a 375px viewport and checks its hit area.
Published from docs/. Edit the files there; changes here are overwritten.