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)