| 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. |
Apple HIG SF Symbols
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.
Core rule
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.
Relationship to other skills
Sidebar = navigation symbols
Toolbar = action symbols
Inspector = property/detail symbols
Command palette = command/category symbols
Status areas = state symbols
Principles
1. Prefer system symbols before custom icons
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.
2. Pair symbols with text when meaning is not obvious
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.
3. Use symbols consistently
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
4. Choose by meaning, not aesthetics
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
Navigation symbol vocabulary
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
Toolbar action symbol vocabulary
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
Status symbol vocabulary
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.
Variant rules
.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.
Rendering modes
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
SwiftUI patterns
Label("Projects", systemImage: "folder")
Button {
createProject()
} label: {
Label("New Project", systemImage: "folder.badge.plus")
}
Button {
openCommandPalette()
} label: {
Image(systemName: "command")
}
.accessibilityLabel("Open Command Palette")
Image(systemName: "sparkles")
.accessibilityHidden(true)
Label(
"Home",
systemImage: isSelected ? "house.fill" : "house"
)
ContentUnavailableView(
"No Projects",
systemImage: "folder",
description: Text("Create a project to get started.")
)
Accessibility rules
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)
RTL and localization notes
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
Review checklist
[ ] 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
Prompt template
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.
Quality bar
Symbols make the app faster to scan.
They clarify meaning without adding visual noise.
They feel native, consistent, and accessible.
