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

). 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.

1. **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.

1. Emit the typed SFSymbolsKit accessors for the resolved property:
• SwiftUI: Image(systemName: String.SFSymbols.)
• UIKit: UIImage.SFSymbols.
• AppKit: NSImage.SFSymbols.
• Enum: SFSymbol. (.allCases is CaseIterable)
2. 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: .