media contract
Icon
SF-Symbol-paired icon primitive. Names map 1-to-1 with the project tokens.sfSymbols entries (e.g. "settings" → SF "gearshape" / lucide-react "Settings"). Pick the semantic name; the renderer picks the right glyph for the platform.
Variants
- monochrome
- Single tint via currentColor
- hierarchical
- Two-tone — base + 30% opacity highlight (iOS 26 default for filled states)
- palette
- Multi-color via tokenised tint pair
- multicolor
- Apple-defined fixed colors — flag, status
Sizes
- xs
- 12pt — inline meta
- sm
- 16pt — buttons, list rows
- md
- 20pt — default UI iconography
- lg
- 24pt — header, navigation
- xl
- 32pt — empty states
- 2xl
- 48pt — onboarding hero
Slots
- symbol
- Semantic icon key from tokens.sfSymbols
Example
Default monochrome inside a button
<Button leading={<Icon name="add" />}>New</Button>Usage rule
Each Icon must use a name from tokens.sfSymbols — never hard-code a glyph string.
The full Icon contract has 7 more rules and 2 more examples, plus the do-not patterns. Get the full recipe.