apple-hig-empty-states
Skill11 starsChanged 3 months agoMITView on GitHub
Use when designing or implementing empty, first-run, no-result, offline, error, or waiting states in Apple-platform apps — every empty state explains what is missing, why it matters, and what to do next.
In this repository39 other files it gives its agents.
- agent-starter-packSkill
- agent-state-machineSkill
- local-ai-ollamaSkill
- apple-hig-command-paletteSkill
- apple-hig-feedback-statusSkill
- apple-hig-inspectorsSkill
- apple-hig-macos-window-layoutSkill
- apple-hig-search-filteringSkill
- apple-hig-settingsSkill
- apple-hig-sf-symbolsSkill
- 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
Show its rules and text
We split this skill into the rules it gives an agent
13 rules. About 0 are common, 12 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈12
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 12
Use this skill when designing or implementing empty, first-run, no-result, offline, error, or waiting states in Apple-platform apps.
- Distinctive: line 58
Use this skill when a view has no data, no selection, no permissions, no connection, no results, or the user is seeing the app for the …
- Distinctive: line 62
Do not use this skill to hide real errors.
- Very specific: line 127
Use ContentUnavailableView when possible.
- Distinctive: line 185
Keep the message short.
- Distinctive: line 186
Use one calm SF Symbol.
- Distinctive: line 187
Use one primary action.
- Distinctive: line 188
Add one secondary action only if useful.
- Distinctive: line 189
Avoid cute/clever copy.
- Distinctive: line 190
Avoid blaming the user.
- Distinctive: line 191
Do not show a huge empty illustration in small popovers.
- Distinctive: line 192
Use secondary text for explanation.
- Distinctive: line 193
Use clear recovery actions for errors.
≈ “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 Empty States
Turn blank screens into useful empty, first-run, no-result, offline, and error states that explain what is missing and what to do next. Reach for it whenever a view has no data, no selection, no results, no connection, or a failed load.
Purpose
Use this skill when designing or implementing empty, first-run, no-result, offline, error, or waiting states in Apple-platform apps.
Use for:
- No projects
- No tasks
- No active runs
- No skills
- No notes
- No reports
- No selected item
- No search results
- First launch
- Offline/local model not running
- Permission missing
- Failed load
Core rule
An empty state must explain what is missing, why it matters, and what to do next.A blank screen is not an empty state.
Empty state formula
Icon
Title
Short explanation
Primary action
Optional secondary actionExample:
No Active Runs
The agent is not working on anything right now.
Start a task or open the queue.
[New Task] [Open Queue]When to use this skill
Use this skill when a view has no data, no selection, no permissions, no connection, no results, or the user is seeing the app for the first time.
When not to use this skill
Do not use this skill to hide real errors. If something failed, show an error state with recovery.
Types of empty states
1. First-run empty state
For new users.
Welcome to your app
Create your first project, connect an agent, or add a skill to begin.
[Create Project] [Add Skill]2. No-content state
For normal empty data.
No Projects
Create a project to organize tasks, prompts, and skills.
[New Project]3. No-selection state
For inspector/detail areas.
No Item Selected
Select a task, project, run, or skill to inspect its details.4. No-search-results state
For failed search.
No Results
Try a project, skill, prompt, file, or command name.
[Clear Search]5. Offline / unavailable state
For local models or services.
Ollama Not Running
Start Ollama to use local models in this app.
[Retry] [Open Settings]6. Error state
For real failure.
Could Not Load Reports
The reports folder could not be read.
[Retry] [Choose Folder]SwiftUI default
Use ContentUnavailableView when possible.
ContentUnavailableView(
"No Projects",
systemImage: "folder",
description: Text("Create a project to organize your work.")
)With actions:
ContentUnavailableView {
Label("No Active Runs", systemImage: "bolt.circle")
} description: {
Text("The agent is not working on anything right now.")
} actions: {
Button("New Task") {
createTask()
}
Button("Open Queue") {
openQueue()
}
}Example empty states
No Active Runs
The agent is not working on anything right now.
Start a task, open the queue, or run a saved skill.
[New Task] [Open Queue]
No Skills
Skills are reusable instructions the agent can apply while coding.
Create your first skill or import a skill folder.
[New Skill] [Import]
No Reports
Daily reports will appear here after your first generated summary.
Generate one from today’s activity.
[Generate Report]
No Search Results
Nothing matched your search.
Try a project, skill, prompt, file, or command name.
[Clear Search]
Ollama Not Running
Local models are unavailable until Ollama starts.
Start Ollama, then retry.
[Retry] [Open Settings]Design rules
- Keep the message short.
- Use one calm SF Symbol.
- Use one primary action.
- Add one secondary action only if useful.
- Avoid cute/clever copy.
- Avoid blaming the user.
- Do not show a huge empty illustration in small popovers.
- Use secondary text for explanation.
- Use clear recovery actions for errors.
Good SF Symbols
No projects: folder
No tasks: checkmark.circle
No active runs: bolt.circle
No skills: sparkles
No prompts: text.badge.star
No files: doc
No notes: note.text
No reports: chart.bar.doc.horizontal
No selection: sidebar.right
No search results: magnifyingglass
Offline: wifi.slash
Error: exclamationmark.triangleReview checklist
[ ] Empty state explains what is missing
[ ] Empty state explains what to do next
[ ] Primary action is clear
[ ] Copy is short and calm
[ ] Symbol matches the state
[ ] No-result state supports clearing search
[ ] Error state has retry or recovery
[ ] Offline state explains service dependency
[ ] Empty state is not too large for popover
[ ] VoiceOver labels are clearCommon mistakes
Blank screen
“Nothing here” with no next action
Too many buttons
Cute but unclear copy
Error hidden as empty state
Huge illustration in a tiny menu bar panel
No retry for failed load
No clear search resetPrompt template
Use the apple-hig-empty-states skill to add polished empty states.
Rules:
- Every no-data, no-selection, no-search-result, offline, and error state needs clear UI.
- Use ContentUnavailableView where possible.
- Include a short title, explanation, and primary action.
- Use one meaningful SF Symbol.
- Keep copy calm and direct.
- Add retry or recovery for error states.
- Add Clear Search for no-result states.
- Do not hide real errors as generic emptiness.
After coding:
1. List empty states added.
2. List actions added.
3. Explain error/offline recovery.
4. Give manual test steps.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.

