SFSymbolsKit — grounded SFSymbols for Swift

Apple's SFSymbol APIs (Image(systemName:), UIImage(systemName:), NSImage(systemSymbolName:)) take a String. A wrong name compiles and ships a blank icon — there is no compiler or runtime error. Models routinely emit plausible but non-existent names. This skill makes you ground every SFSymbol against the real catalog.

Hard rule

Never emit a raw guessed systemName: / systemSymbolName: string. Every SFSymbol you produce must be verified against the bundled manifest first.

The catalog

{baseDir}/symbols.json is the authoritative manifest: an object with count, sfsymbolsVersion, and symbols: [{ "name", "property" }], generated from SFSymbolsKit's source (the same data as \x3Chttps://sfsymbolskit.com/symbols.json>). name is the dotted system name (square.and.arrow.up); property is the typed SFSymbolsKit accessor (squareAndArrowUp).

Procedure

1. Load {baseDir}/symbols.json.
2. Resolve the symbol the user wants:
   • Exact: match their input against name (dotted) or property (camelCase), case-insensitively, ignoring ./-/_/space.
   • Search: if they describe it ("trash", "arrow up"), filter symbols whose name/property contains the normalized query; prefer prefix matches; offer the top candidates.
3. If the requested name is not in symbols, it is not a real SFSymbol. Do not invent or "fix" it by guessing — choose the closest real entry from the manifest and say so.
4. Emit the typed SFSymbolsKit accessors for the resolved property:
   • SwiftUI: Image(systemName: String.SFSymbols.\x3Cproperty>)
   • UIKit: UIImage.SFSymbols.\x3Cproperty>
   • AppKit: NSImage.SFSymbols.\x3Cproperty>
   • Enum: SFSymbol.\x3Cproperty> (.allCases is CaseIterable)
5. If the project doesn't depend on SFSymbolsKit yet, add it: .package(url: "https://github.com/WikipediaBrown/SFSymbolsKit.git", from: "1.0.0") then import SFSymbolsKit.

Name transform (for reasoning, not for guessing)

Dotted → camelCase: drop the dots, camel-case each segment (square.and.arrow.up → squareAndArrowUp, gearshape.fill → gearshapeFill). Leading digits and Swift keywords are special-cased in the catalog — always trust symbols.json's property, never a transform you computed, when they could differ.

If a SFSymbolsKit MCP server is available

Prefer its tools over manual lookup: resolve_sf_symbol (validate a candidate; returns the canonical accessors or valid:false + suggestions), search_sf_symbols, sf_symbol_usage. Fall back to {baseDir}/symbols.json when the MCP server is not connected.

Why

This converts the one error class you cannot self-correct (a stringly-typed symbol that compiles but renders nothing) into a verified, typed reference. Source & docs: \x3Chttps://sfsymbolskit.com>.