Apple Hig Empty States

---
name: apple-hig-empty-states
description: 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.
---

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

```swift
ContentUnavailableView(
    "No Projects",
    systemImage: "folder",
    description: Text("Create a project to organize your work.")
)
```

With actions:

```swift
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.
```