---
name: sf-symbols
description: 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.
allowed-tools: [Read, Write, Edit, Glob, Grep]
last_verified: 2026-07-16
review_by: 2027-06-22
---

# 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:

1. **Start from the closest system symbol** (prefer an unfilled base) — SF Symbols app →
   Export Template. Never draw from a blank canvas.
2. **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).
3. **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.
4. **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).
5. **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.
6. **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

- https://developer.apple.com/sf-symbols/ (the SF Symbols app)
- https://developer.apple.com/videos/play/wwdc2025/337/ (What's new in SF Symbols 7)
- https://developer.apple.com/videos/play/wwdc2021/10250/ (Create custom symbols)
- https://developer.apple.com/videos/play/wwdc2023/10258/ (Animate symbols)
- https://developer.apple.com/videos/play/wwdc2022/10158/ (Variable Color)
- https://developer.apple.com/design/human-interface-guidelines/sf-symbols
- Related skills: `design/animation-patterns` (symbol-effects implementation), `design/typography` (SF font pairing), `generators/app-icon-generator` (app icons are NOT symbols)