rshankras/sf-symbols

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)