agentleFS
aka-kikaaka-kika/akakika-skills/skills/apple-hig/apple-hig-empty-states/SKILL.md

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.

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
  1. Distinctive:

    Use this skill when designing or implementing empty, first-run, no-result, offline, error, or waiting states in Apple-platform apps.

    line 12
  2. Distinctive:

    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 …

    line 58
  3. Distinctive:

    Do not use this skill to hide real errors.

    line 62
  4. Very specific:

    Use ContentUnavailableView when possible.

    line 127
  5. Distinctive:

    Keep the message short.

    line 185
  6. Distinctive:

    Use one calm SF Symbol.

    line 186
  7. Distinctive:

    Use one primary action.

    line 187
  8. Distinctive:

    Add one secondary action only if useful.

    line 188
  9. Distinctive:

    Avoid cute/clever copy.

    line 189
  10. Distinctive:

    Avoid blaming the user.

    line 190
  11. Distinctive:

    Do not show a huge empty illustration in small popovers.

    line 191
  12. Distinctive:

    Use secondary text for explanation.

    line 192
  13. Distinctive:

    Use clear recovery actions for errors.

    line 193

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 action

Example:

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

Review 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 clear

Common 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 reset

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

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.