apple-hig-sf-symbols
Skill11 starsChanged 3 months agoMITView on GitHub
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.
In this repository39 other files it gives its agents.
- agent-starter-packSkill
- agent-state-machineSkill
- local-ai-ollamaSkill
- apple-hig-command-paletteSkill
- apple-hig-empty-statesSkill
- apple-hig-feedback-statusSkill
- apple-hig-inspectorsSkill
- apple-hig-macos-window-layoutSkill
- apple-hig-search-filteringSkill
- apple-hig-settingsSkill
- apple-hig-sidebarsSkill
- apple-hig-toolbarsSkill
- apple-hig-typographySkill
- blog-post-publishingSkill
- social-post-kitSkill
- color-principlesSkill
- kika-design-systemSkill
- emergency-switch-appSkill
- product-hunt-polish-reviewSkill
- docs-updateSkill
- project-folder-cleanupSkill
- between-runs-auditSkill
- explain-new-projectSkill
- new-project-gateSkill
- old-project-auditSkill
- project-catch-upSkill
- project-workflowSkill
- project-worth-my-timeSkill
- butterfly-effectSkill
- spreadSkill
- tilSkill
- apple-app-intentsSkill
- macos-app-distribution-dmgSkill
- macos-clipboard-pasteboardSkill
- macos-global-shortcutsSkill
- macos-launch-at-loginSkill
- macos-menubar-swiftuiSkill
- macos-notificationsSkill
- macos-permissions-privacySkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 6 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 16
Every symbol must help the user understand:
- Distinctive: line 25
If a symbol does not make the interface clearer, remove it.
- Distinctive: line 41
Use Apple-provided SF Symbols first.
- Distinctive: line 51
Only use custom icons when the concept does not exist in SF Symbols or the app has a strong brand-specific object.
- Distinctive: line 221
Do not use fill everywhere just because it looks stronger.
- Distinctive: line 282
Every symbol-only control needs an accessibility label.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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 symbolsPrinciples
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 = gearshapeBad:
Projects = folder in sidebar
Projects = square.grid.2x2 in toolbar
Projects = tray in command palette4. 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.downAvoid ambiguous choices:
Search → eye
Settings → slider.horizontal.3
Delete → xmark.circle
Export → paperplaneNavigation 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 gearshapeNavigation symbols should not look like temporary actions.
Avoid for navigation:
plus
trash
pencil
arrow.up
arrow.down
checkmark
xmarkToolbar 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 folderStatus 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 cloudStatus 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 variantExamples:
Unselected home: house
Selected home: house.fill
Offline: wifi.slash
New project: folder.badge.plus
More: ellipsis.circleDo 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 statesFor calm productivity apps:
Default: monochrome
Exception: hierarchical for large empty states
Avoid: random multicolor/gradient symbolsSwiftUI patterns
// 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.")
)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.rightReview 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 consideredPrompt 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.Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

