SF Symbols
Over 7,000 system symbols with free platform consistency, Dynamic Type alignment, and
accessibility — the default answer to "we need an icon." This skill covers using them well,
authoring custom ones that behave like system ones, and the animation vocabulary.
(Animation implementation patterns live in design/animation-patterns → symbol-effects.md;
this skill owns selection, authoring, and rendering.)
When This Skill Activates
- Choosing icons for tabs, toolbars, buttons, widgets ("should this be an SF Symbol?" — usually yes)
- A needed glyph doesn't exist → authoring a custom symbol
- Rendering a changing value (signal, progress, volume) as a symbol
- Symbol state changes that should animate (mute/unmute, play/pause)
Using system symbols
- Prefer symbols over custom art for tab/toolbar icons — recognizability across the platform
for free, and they scale with text styles (
imageScale, weights match adjacent text).
- Keep platform-conventional symbols conventional: share, trash, search mean one thing each.
- Rendering modes: Monochrome · Hierarchical (one color, opacity-derived depth) ·
Palette (2–3 explicit colors) · Multicolor (intrinsic colors). Pick per context — hierarchical
shines in toolbars; multicolor in content.
- Gradients (SF Symbols 7-era): a smooth linear gradient generated from one source color,
available in all rendering modes — use where depth helps, keep flat in dense UI.
- Variable value: pass
variableValue (0–1) to render magnitude — signal bars, progress.
Thresholds distribute evenly; 0% is the only "empty" state (a symbol reads "full" before 100%).
Variable Draw (SF Symbols 7) renders the path at a percentage instead of activating
layers — an alternative for progress/temperature; a symbol can carry both but renders one.
Animation vocabulary
Presets: Bounce · Pulse · Variable Color · Scale · Appear · Disappear · Replace · Draw On/Off
(SF Symbols 7). Behavior classes: discrete (one-off), indefinite (until removed — always pair
with removal logic), transition, content transition.
- Swap symbol states with
.contentTransition(.symbolEffect(.replace)) — and prefer Magic
Replace (preserves matching enclosures, uses Draw Off/On where supported) for state pairs
like mute/unmute.
- Draw On/Off playback: By Layer (default) · Whole Symbol · Individually. Symbols define their
own drawing direction (wind draws left→right; symmetric symbols from center).
- Effects propagate down the view hierarchy —
.symbolEffectsRemoved() blocks them on subviews.
- Full API patterns (SwiftUI
symbolEffect, UIKit addSymbolEffect) in
design/animation-patterns/symbol-effects.md.
Authoring custom symbols
The workflow that makes a custom glyph behave like a system one:
- Start from the closest system symbol (prefer an unfilled base) — SF Symbols app →
Export Template. Never draw from a blank canvas.
- Draw three sources: Ultralight-Small, Regular-Small, Black-Small — the system
interpolates all 27 variants (9 weights × 3 scales) from them. Get Regular-Small right
first, then copy its paths and only move points — all sources must keep the same number
and order of paths and points (move, never add/remove).
- Outline everything: convert live strokes to outlined paths once the design settles; no
open paths (can't fill), no gradients or drop shadows baked in (they break multicolor/
hierarchical rendering) — flat fills only.
- Annotate with unified annotation: layers in explicit z-order; system colors for
multicolor (they adapt to dark mode/contrast); primary→tertiary groups drive hierarchical
and palette modes;
Erase punches shapes out of layers behind; Hidden excludes a layer
from a mode. For variable color, z-order = activation order (first-to-fill at bottom).
- Draw guide points (SF Symbols 7 templates) for Draw On/Off: every path needs a start
(open circle) and end (closed circle); corners marked with diamonds; annotate the Regular
weight first (the only weight where guide points can be added/removed) and keep guide-point
order identical across weights.
- Export the current template version for Xcode. Legacy note: 2.0 templates are
monochrome-only (needed only for very old deployment targets); 3.0+ carries all rendering
modes; 4.0+ carries variable color.
❌ Common failures: baking effects into art (breaks rendering modes) · mismatched path counts
across sources (kills interpolation) · re-ordering paths after annotation (forces re-annotation)
· shipping a filled base variant as the only variant.
Output Format
For icon reviews: Location | Current | Symbol exists? (name) | Mode/config | Action.
For custom-symbol requests: the 6-step authoring checklist above with per-step status.
References
1---
2name: sf-symbols
3description: SF Symbols end-to-end — choosing and configuring the 7,000+ system symbols (rendering modes, variable color/draw, gradients), authoring custom symbols that interpolate across weights, and the animation preset vocabulary. Use when picking iconography, building custom symbols, animating symbol state changes, or rendering values as symbols.
4allowed-tools: [Read, Write, Edit, Glob, Grep]
5last_verified: 2026-07-16
6review_by: 2027-06-22
7---
8
9# SF Symbols
10
11Over 7,000 system symbols with free platform consistency, Dynamic Type alignment, and
12accessibility — the default answer to "we need an icon." This skill covers using them well,
13authoring custom ones that behave like system ones, and the animation vocabulary.
14(Animation *implementation patterns* live in `design/animation-patterns` → symbol-effects.md;
15this skill owns selection, authoring, and rendering.)
16
17## When This Skill Activates
18
19- Choosing icons for tabs, toolbars, buttons, widgets ("should this be an SF Symbol?" — usually yes)
20- A needed glyph doesn't exist → authoring a custom symbol
21- Rendering a changing value (signal, progress, volume) as a symbol
22- Symbol state changes that should animate (mute/unmute, play/pause)
23
24## Using system symbols
25
26- Prefer symbols over custom art for tab/toolbar icons — recognizability across the platform
27 for free, and they scale with text styles (`imageScale`, weights match adjacent text).
28- Keep platform-conventional symbols conventional: share, trash, search mean one thing each.
29- **Rendering modes**: Monochrome · Hierarchical (one color, opacity-derived depth) ·
30 Palette (2–3 explicit colors) · Multicolor (intrinsic colors). Pick per context — hierarchical
31 shines in toolbars; multicolor in content.
32- **Gradients** (SF Symbols 7-era): a smooth linear gradient generated from one source color,
33 available in all rendering modes — use where depth helps, keep flat in dense UI.
34- **Variable value**: pass `variableValue` (0–1) to render magnitude — signal bars, progress.
35 Thresholds distribute evenly; 0% is the only "empty" state (a symbol reads "full" before 100%).
36 **Variable Draw** (SF Symbols 7) renders the path at a percentage instead of activating
37 layers — an alternative for progress/temperature; a symbol can carry both but renders one.
38
39## Animation vocabulary
40
41Presets: **Bounce · Pulse · Variable Color · Scale · Appear · Disappear · Replace · Draw On/Off**
42(SF Symbols 7). Behavior classes: discrete (one-off), indefinite (until removed — always pair
43with removal logic), transition, content transition.
44
45- Swap symbol states with `.contentTransition(.symbolEffect(.replace))` — and prefer **Magic
46 Replace** (preserves matching enclosures, uses Draw Off/On where supported) for state pairs
47 like mute/unmute.
48- Draw On/Off playback: By Layer (default) · Whole Symbol · Individually. Symbols define their
49 own drawing direction (wind draws left→right; symmetric symbols from center).
50- Effects propagate down the view hierarchy — `.symbolEffectsRemoved()` blocks them on subviews.
51- Full API patterns (SwiftUI `symbolEffect`, UIKit `addSymbolEffect`) in
52 `design/animation-patterns/symbol-effects.md`.
53
54## Authoring custom symbols
55
56The workflow that makes a custom glyph behave like a system one:
57
581. **Start from the closest system symbol** (prefer an unfilled base) — SF Symbols app →
59 Export Template. Never draw from a blank canvas.
602. **Draw three sources**: Ultralight-Small, Regular-Small, Black-Small — the system
61 interpolates all **27 variants** (9 weights × 3 scales) from them. Get Regular-Small right
62 first, then copy its paths and only *move* points — all sources must keep the **same number
63 and order of paths and points** (move, never add/remove).
643. **Outline everything**: convert live strokes to outlined paths once the design settles; no
65 open paths (can't fill), no gradients or drop shadows baked in (they break multicolor/
66 hierarchical rendering) — flat fills only.
674. **Annotate with unified annotation**: layers in explicit z-order; system colors for
68 multicolor (they adapt to dark mode/contrast); primary→tertiary groups drive hierarchical
69 and palette modes; `Erase` punches shapes out of layers behind; `Hidden` excludes a layer
70 from a mode. For **variable color**, z-order = activation order (first-to-fill at bottom).
715. **Draw guide points** (SF Symbols 7 templates) for Draw On/Off: every path needs a start
72 (open circle) and end (closed circle); corners marked with diamonds; annotate the Regular
73 weight first (the only weight where guide points can be added/removed) and keep guide-point
74 order identical across weights.
756. **Export the current template version** for Xcode. Legacy note: 2.0 templates are
76 monochrome-only (needed only for very old deployment targets); 3.0+ carries all rendering
77 modes; 4.0+ carries variable color.
78
79❌ Common failures: baking effects into art (breaks rendering modes) · mismatched path counts
80across sources (kills interpolation) · re-ordering paths after annotation (forces re-annotation)
81· shipping a filled base variant as the only variant.
82
83## Output Format
84
85For icon reviews: `Location | Current | Symbol exists? (name) | Mode/config | Action`.
86For custom-symbol requests: the 6-step authoring checklist above with per-step status.
87
88## References
89
90- https://developer.apple.com/sf-symbols/ (the SF Symbols app)
91- https://developer.apple.com/videos/play/wwdc2025/337/ (What's new in SF Symbols 7)
92- https://developer.apple.com/videos/play/wwdc2021/10250/ (Create custom symbols)
93- https://developer.apple.com/videos/play/wwdc2023/10258/ (Animate symbols)
94- https://developer.apple.com/videos/play/wwdc2022/10158/ (Variable Color)
95- https://developer.apple.com/design/human-interface-guidelines/sf-symbols
96- Related skills: `design/animation-patterns` (symbol-effects implementation), `design/typography` (SF font pairing), `generators/app-icon-generator` (app icons are NOT symbols)
rshankras