Menu
Use when choosing, reviewing, or implementing SF Symbols in an Apple-platform app — picking meaningful symbols, keeping the same concept on the same symbol everywhere, and handling variants, rendering modes, and accessibility.
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional SOC
Use when shipping a macOS app outside the App Store — Developer ID signing with hardened runtime, notarization with notarytool, stapling, building a clean drag-to-Applications DMG, and verifying the result launches on a stranger's Mac.
Use when reading, writing, or watching the macOS clipboard — NSPasteboard types and multiple representations, the changeCount polling pattern, the transient/concealed pasteboard conventions clipboard tools must respect, and the Sequoia paste-privacy alerts.
Use when adding or reviewing keyboard shortcuts in a macOS app — in-app vs global, RegisterEventHotKey vs the KeyboardShortcuts package vs NSEvent monitors, user-configurable recording, conflict handling, and which defaults won't collide with the system.
Use when adding, reviewing, or debugging Launch at Login in a macOS app — SMAppService registration, the requiresApproval state, a Settings toggle that reflects reality, and migration off deprecated login-item APIs.
Use when adding or reviewing macOS user notifications — UNUserNotificationCenter permission flow, categories and action buttons, click routing through the delegate, foreground presentation, and rules that keep notifications from becoming spam.
Use when a macOS app needs a TCC permission or touches private data — the map of which API, Info.plist key, and entitlement each permission needs, pre-prompt explanation patterns, denied-state recovery with System Settings deep links, and honest privacy copy.
| name | apple-hig-sf-symbols |
| description | Use when choosing, reviewing, or implementing SF Symbols in an Apple-platform app — picking meaningful symbols, keeping the same concept on the same symbol everywhere, and handling variants, rendering modes, and accessibility. |
Pick and review SF Symbols so every icon carries meaning, the same concept always uses the same symbol, and icon-only controls stay accessible. Reach for this when working on sidebar icons, toolbar icons, tab bars, buttons, menus, empty states, status indicators, inspectors, settings screens, command palettes, custom symbol review, and accessibility cleanup.
SF Symbols are meaning tools, not decoration.
Every symbol must help the user understand:
What is this?
What does it do?
What state is it in?
Where will this take me?
If a symbol does not make the interface clearer, remove it.
Sidebar = navigation symbols
Toolbar = action symbols
Inspector = property/detail symbols
Command palette = command/category symbols
Status areas = state symbols
Use Apple-provided SF Symbols first.
Image(systemName: "folder")
Image(systemName: "sparkles")
Image(systemName: "gearshape")
Image(systemName: "sidebar.left")
Image(systemName: "magnifyingglass")
Only use custom icons when the concept does not exist in SF Symbols or the app has a strong brand-specific object.
Preferred:
Label("Projects", systemImage: "folder")
Label("New Skill", systemImage: "sparkles")
Label("Settings", systemImage: "gearshape")
Risky:
Image(systemName: "sparkles")
Icon-only buttons are acceptable only when the action is familiar, the context is clear, and the button has an accessibility label.
The same concept should use the same symbol everywhere.
Good:
Projects = folder
Skills = sparkles
Prompts = text.badge.star
Memory = brain
Reports = chart.bar.doc.horizontal
Settings = gearshape
Bad:
Projects = folder in sidebar
Projects = square.grid.2x2 in toolbar
Projects = tray in command palette
Clear beats cool.
Good:
New Project → folder.badge.plus
Search → magnifyingglass
Settings → gearshape
Delete → trash
Archive → archivebox
Export → square.and.arrow.up
Import → square.and.arrow.down
Avoid ambiguous choices:
Search → eye
Settings → slider.horizontal.3
Delete → xmark.circle
Export → paperplane
Home house
Active Runs bolt.circle
Queue list.bullet.rectangle
Projects folder
Tasks checkmark.circle
Skills sparkles
Prompts text.badge.star
Files doc
Memory brain
Notes note.text
Decisions checkmark.seal
Reports chart.bar.doc.horizontal
Settings gearshape
Navigation symbols should not look like temporary actions.
Avoid for navigation:
plus
trash
pencil
arrow.up
arrow.down
checkmark
xmark
New plus
New Project folder.badge.plus
New Note note.text.badge.plus
Search magnifyingglass
Filter line.3.horizontal.decrease.circle
Sort arrow.up.arrow.down
Share square.and.arrow.up
Import square.and.arrow.down
Export square.and.arrow.up
Refresh arrow.clockwise
Retry arrow.counterclockwise
Stop stop.circle
Pause pause.circle
Resume play.circle
Inspector sidebar.right
More ellipsis.circle
Command Palette command
Delete trash
Archive archivebox
Copy doc.on.doc
Edit pencil
Duplicate plus.square.on.square
Reveal in Finder folder
Idle moon
Running bolt.circle
Thinking brain
Waiting clock
Completed checkmark.circle
Failed exclamationmark.triangle
Warning exclamationmark.triangle
Blocked xmark.octagon
Online circle.fill
Offline wifi.slash
Synced checkmark.icloud
Syncing arrow.triangle.2.circlepath
Private lock.shield
Local internaldrive
Cloud cloud
Status symbols should be paired with text. Never rely on color alone.
.fill = selected or active state
.slash = unavailable/off state
.badge = compound action or meaning
.circle = contained toolbar/status control
.square = contained grid/control variant
Examples:
Unselected home: house
Selected home: house.fill
Offline: wifi.slash
New project: folder.badge.plus
More: ellipsis.circle
Do not use fill everywhere just because it looks stronger.
Monochrome = default for sidebar, toolbar, menus, lists
Hierarchical = empty states, larger calm illustrations, inspector headers
Palette = status/warning symbols only when parts need separate colors
Multicolor = only when built-in colors add meaning
Gradients = avoid in productivity UI except maybe hero/empty states
For calm productivity apps:
Default: monochrome
Exception: hierarchical for large empty states
Avoid: random multicolor/gradient symbols
// Preferred navigation row
Label("Projects", systemImage: "folder")
// Preferred toolbar action
Button {
createProject()
} label: {
Label("New Project", systemImage: "folder.badge.plus")
}
// Icon-only button with accessibility
Button {
openCommandPalette()
} label: {
Image(systemName: "command")
}
.accessibilityLabel("Open Command Palette")
// Decorative symbol
Image(systemName: "sparkles")
.accessibilityHidden(true)
// Selected/unselected variant
Label(
"Home",
systemImage: isSelected ? "house.fill" : "house"
)
// Empty state
ContentUnavailableView(
"No Projects",
systemImage: "folder",
description: Text("Create a project to get started.")
)
Every symbol-only control needs an accessibility label.
Good:
Button {
createProject()
} label: {
Image(systemName: "plus")
}
.accessibilityLabel("New Project")
Better:
Button {
createProject()
} label: {
Label("New Project", systemImage: "folder.badge.plus")
}
Decorative symbols should be hidden from accessibility:
Image(systemName: "sparkles")
.accessibilityHidden(true)
Rules:
- Avoid English-letter symbols unless necessary.
- Be careful with arrows in right-to-left layouts.
- Test Hebrew/Arabic UI if the app supports RTL.
- Prefer semantic symbols over text-like symbols.
RTL-sensitive symbols:
chevron.left
chevron.right
arrow.left
arrow.right
sidebar.left
sidebar.right
[ ] Every symbol communicates clear meaning
[ ] Same concept uses same symbol everywhere
[ ] Navigation symbols are different from action symbols
[ ] Symbols are paired with text where needed
[ ] Icon-only controls have accessibility labels
[ ] Decorative icons are accessibility hidden
[ ] Status symbols are paired with text
[ ] Color is not the only state indicator
[ ] Rendering mode is consistent
[ ] Fill/slash/badge variants clarify meaning
[ ] Symbols are readable at actual size
[ ] Symbols do not overpower text
[ ] RTL/localization issues are considered
Drop this into any coding agent (Claude Code, Codex, Cursor, …) to apply the skill:
Use the apple-hig-sf-symbols skill to clean up all iconography.
Rules:
- Prefer SF Symbols over custom icons.
- Symbols must communicate meaning.
- Use the same symbol for the same concept everywhere.
- Use Label(title, systemImage:) when possible.
- Add accessibility labels to icon-only controls.
- Hide decorative symbols from accessibility.
- Navigation symbols belong in sidebars/tabs.
- Action symbols belong in toolbars/menus/buttons.
- Status symbols must be paired with text.
- Use monochrome by default.
- Avoid multicolor/gradients unless they add meaning.
- Check compact sizes and RTL/localization concerns.
Before coding:
1. Search for all Image(systemName:) usage.
2. Search for all Label(... systemImage:) usage.
3. Create a current symbol map.
4. Identify confusing or inconsistent symbols.
5. Propose a clean symbol vocabulary.
After coding:
1. List files changed.
2. List symbols replaced.
3. Explain why each replacement was made.
4. Show final symbol vocabulary.
5. Include manual test steps.
Symbols make the app faster to scan.
They clarify meaning without adding visual noise.
They feel native, consistent, and accessible.