/sf-symbols-workflow

name: sf-symbols-workflow
description: Guide SF Symbols selection, inspection, customization, rendering modes, variable color, symbol effects, animated symbols, custom symbols, accessibility semantics, availability checks, and Apple app integration. Use when a task mentions SF Symbols, the SF Symbols app, systemImage names, symbolRenderingMode, foregroundStyle palette or hierarchical color, multicolor symbols, variableValue, symbolEffect, custom symbol templates, symbol export, asset-catalog symbol resources, or choosing symbols for SwiftUI, AppKit, UIKit, or watchOS UI.

SF Symbols Workflow

Purpose

Use this skill to choose, inspect, customize, validate, and integrate SF Symbols in Apple app UI. The skill owns symbol selection, SF Symbols app inspection, rendering-mode decisions, custom-symbol workflow, symbol animation routing, and accessibility semantics.

It is not the app-icon workflow, not the generic SwiftUI animation workflow, and not the Xcode project execution workflow.

When To Use

• Use this skill when the user asks about Apple's SF Symbols library or SF Symbols app.
• Use this skill when the task mentions built-in symbols, `Image(systemName:)`, `Label`, `UIImage(systemName:)`, `NSImage(systemSymbolName:)`, `symbolRenderingMode`, `symbolVariant`, `foregroundStyle`, `variableValue`, `symbolEffect`, `SymbolEffectTransition`, custom symbols, or symbol templates.
• Use this skill when a UI design needs a semantically correct icon, state variant, platform-available symbol, palette/multicolor rendering, variable color, or animated symbol effect.
• Use this skill when the user wants Codex to inspect the local SF Symbols app through Computer Use.
• Recommend `swiftui-animation-workflow` when the primary question is broader SwiftUI motion, transition design, state-driven animation, phase animation, keyframe animation, or reduce-motion behavior.
• Recommend `icon-composer-app-icon-workflow` when the work is an app icon rather than an in-app symbol.
• Recommend `apple-ui-accessibility-workflow` when the main issue is accessibility review beyond symbol labels and semantic meaning.
• Recommend `xcode-build-run-workflow` when the next honest step is asset-catalog integration, build, preview, simulator, or project-file validation.

Single-Path Workflow

1. Classify the symbol job:

• choose a built-in symbol
• repair an incorrect or unavailable symbol name
• choose a variant, such as fill, slash, circle, square, or badge
• choose monochrome, hierarchical, palette, or multicolor rendering
• apply variable color or variable draw behavior
• apply a symbol effect or symbol transition
• create, annotate, validate, or export a custom symbol
• integrate an asset-catalog symbol into an app

2. Apply the Apple docs gate:

• read the relevant Apple documentation first
• state the documented behavior being relied on before recommending implementation
• if Apple docs and the local SF Symbols app disagree, stop and surface the conflict
• if no relevant Apple docs can be found, say that explicitly before proceeding

3. Inspect the local tool when current symbol-library behavior matters:

• verify the SF Symbols app exists before promising GUI guidance
• inspect the local app through Computer Use when the task needs category, rendering, animation, export, or custom-symbol evidence
• use the app's sidebar and inspectors to verify symbol availability, variants, rendering support, variable behavior, and animation support

4. Choose the symbol path:

• built-in SF Symbol when the semantic match and platform availability are good
• built-in symbol plus variant when the state is a standard variant
• rendering-mode or palette change when the shape is right and only color semantics need work
• symbol effect when the motion is symbol-local and Apple documents the effect for the target platforms
• custom symbol when the app needs a brand-specific or unavailable symbol while preserving SF Symbols metrics and template rules
• ordinary SVG/vector artwork when the shape is not a symbol and does not benefit from SF Symbols behavior

5. Check implementation boundaries:

• SwiftUI uses `Image`, `Label`, symbol modifiers, `foregroundStyle`, `symbolEffect`, and asset names when appropriate
• UIKit and AppKit use image and symbol configuration APIs when appropriate
• Xcode project and asset-catalog changes hand off to `xcode-build-run-workflow`
• app-icon work hands off to `icon-composer-app-icon-workflow`

6. Return one recommendation path with:

• the symbol source
• rendering and animation choices
• accessibility semantics
• documentation behavior relied on
• validation or handoff steps

Local Tool Check

Use this check before live SF Symbols work:

1. Locate the app. Gale's current local path observed on 2026-06-28 is `/Applications/SF Symbols.app`. 2. Read the app version from `Contents/Info.plist` when current library behavior matters. 3. Open or inspect the app when the user asks for GUI guidance, custom symbol validation, export behavior, or visual comparison. 4. Treat SF Symbols app state as evidence, not as a source file to mutate. Ask before saving, overwriting, exporting into a repo, or changing user-owned collections.

Current local evidence from 2026-06-28: SF Symbols 7.2 build 119 exposes an accessibility-visible sidebar with categories such as What's New, Draw, Variable, Multicolor, Custom Symbols, and inspectors for Info, Format, and Animation.

Inputs

• `request`: optional free-text task description used to classify the symbol job.
• `target_framework`: optional framework emphasis such as `swiftui`, `uikit`, `appkit`, or `mixed`.
• `target_platforms`: optional platform list such as `ios`, `macos`, `watchos`, `visionos`, or `mixed-apple`.
• `symbol_name`: optional existing symbol name or custom symbol asset name.
• `visual_goal`: optional desired semantic meaning, state, brand shape, or interaction feed