apple-hig-feedback-status
Skill11 starsChanged 3 months agoMITView on GitHub
Use when designing or implementing feedback, status, progress, alerts, errors, success states, and live activity indicators in Apple-platform apps — inline status, banners, alerts, notifications, and loading states.
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-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
15 rules. About 0 are common, 15 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈15
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 8
Use this skill when designing or implementing feedback, status, progress, alerts, errors, success states, and live activity indicators in …
- Distinctive: line 55
Use for local state near content.
- Distinctive: line 65
Use for screen-level issues.
- Distinctive: line 74
Use for destructive actions, permission issues, or blocking errors.
- Distinctive: line 78
Use when work completes while user is elsewhere.
- Distinctive: line 82
Use when time or steps matter.
- Distinctive: line 104
Use loading indicators only when something is actually happening.
- Distinctive: line 125
Use determinate progress only when you know the total.
- Distinctive: line 131
Use indeterminate progress when the duration is unknown.
- Distinctive: line 160
Do not blink aggressively.
- Distinctive: line 161
Do not animate everything.
- Distinctive: line 183
Avoid dramatic success messages.
- Distinctive: line 257
Use alerts for blocking or dangerous operations.
- Distinctive: line 272
Use notifications for background completion:
- Distinctive: line 280
Do not notify for every minor state change.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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 Feedback Status
Use this skill when designing or implementing feedback, status, progress, alerts, errors, success states, and live activity indicators in Apple-platform apps. It covers running states, task progress, model status, local server status, notifications, toasts, banners, inline errors, loading states, and completion feedback.
Core rule
Always tell the user what is happening, what changed, and whether they need to act.Status vocabulary
Use consistent states:
Idle
Thinking
Running
Waiting
Blocked
Needs Review
Completed
Failed
Offline
Paused
CancelledWhen to use this skill
Use for:
- Agent is working
- Task finished
- Task failed
- Ollama not running
- API key missing
- Permission denied
- File operation succeeded
- File operation failed
- Syncing
- Saving
- Loading
- Waiting for user input
Feedback levels
1. Inline status
Use for local state near content.
Running
Saved
Waiting for model2. Banner
Use for screen-level issues.
Ollama is offline. Local models are unavailable.
[Retry] [Settings]3. Alert/dialog
Use for destructive actions, permission issues, or blocking errors.
4. Notification
Use when work completes while user is elsewhere.
5. Progress indicator
Use when time or steps matter.
Agent status map
Idle moon No current work
Thinking brain Planning or reasoning
Running bolt.circle Executing a task
Waiting clock Waiting for input/service
Blocked xmark.octagon Cannot continue without action
Needs Review checkmark.seal User should inspect result
Completed checkmark.circle Finished successfully
Failed exclamationmark.triangle Failed with error
Offline wifi.slash Required service unavailable
Paused pause.circle Temporarily stopped
Cancelled xmark.circle Stopped by userPair symbols with text. Do not rely on color alone.
Loading state rules
Use loading indicators only when something is actually happening.
Good:
Checking Ollama connection…
Generating report…
Indexing project files…
Waiting for agent response…Bad:
Loading…
Please wait…
Working magic…Progress rules
Use determinate progress only when you know the total.
ProgressView(value: completed, total: total)Use indeterminate progress when the duration is unknown.
ProgressView("Generating report…")Avoid fake percentages.
Do not show 73% if the app does not actually know progress.For agent work, prefer step labels over fake percent:
Planning task
Editing files
Running checks
Waiting for result
Ready for reviewRunning indicator
For your app, use a subtle pulse when the agent is active.
Rules:
- Pulse should be calm.
- Do not blink aggressively.
- Do not animate everything.
- Pair pulse with text like “Running” or “Thinking”.
- Respect reduced motion.
SwiftUI reduced motion:
@Environment(\.accessibilityReduceMotion) private var reduceMotionSuccess feedback
Use short confirmation.
Task created
Report exported
Skill validated
Project opened
Settings savedAvoid dramatic success messages.
Error feedback
Good error message structure:
What failed
Why it may have failed
What to do nextExample:
Ollama Not Running
The app could not connect to http://127.0.0.1:11434.
Start Ollama, then retry.
[Retry] [Open Settings]SwiftUI status chip
struct StatusChip: View {
let title: String
let symbol: String
var body: some View {
Label(title, systemImage: symbol)
.font(.caption)
.foregroundStyle(.secondary)
.padding(.horizontal, 8)
.padding(.vertical, 4)
.background(.quaternary, in: Capsule())
.accessibilityLabel(title)
}
}Banner pattern
struct StatusBanner: View {
let title: String
let message: String
let symbol: String
let actionTitle: String?
let action: (() -> Void)?
var body: some View {
HStack(alignment: .top, spacing: 12) {
Image(systemName: symbol)
.foregroundStyle(.secondary)
VStack(alignment: .leading, spacing: 4) {
Text(title).font(.headline)
Text(message).font(.callout).foregroundStyle(.secondary)
}
Spacer()
if let actionTitle, let action {
Button(actionTitle, action: action)
}
}
.padding(12)
.background(.regularMaterial, in: RoundedRectangle(cornerRadius: 12))
}
}Alert pattern
Use alerts for blocking or dangerous operations.
.alert("Delete Project?", isPresented: $showDeleteAlert) {
Button("Delete", role: .destructive) {
deleteProject()
}
Button("Cancel", role: .cancel) {}
} message: {
Text("This removes the project from the app. Files on disk will not be deleted.")
}Notifications
Use notifications for background completion:
Agent finished the task
Report is ready
Run failed and needs attentionDo not notify for every minor state change.
Review checklist
[ ] Every async operation has visible feedback
[ ] No fake progress percentages
[ ] Agent states use consistent vocabulary
[ ] Running/thinking states are clear
[ ] Success messages are short
[ ] Errors explain recovery
[ ] Destructive actions require confirmation
[ ] Offline/service errors offer retry/settings
[ ] Reduced motion is respected
[ ] Status does not rely on color aloneCommon mistakes
Fake progress
Blinking aggressive indicators
Silent failure
Vague “Something went wrong”
Success messages that stay forever
Too many notifications
Color-only status
No retry actionPrompt template
Drop this into any coding agent (Claude Code, Codex, Cursor, …) to apply the skill:
Use the apple-hig-feedback-status skill to add clear status and feedback.
Rules:
- Use consistent state vocabulary.
- Show inline status for local state.
- Use banners for screen-level issues.
- Use alerts for destructive/blocking actions.
- Use notifications only for background completion or failure.
- Do not use fake percentages.
- Prefer step labels for agent work.
- Pair symbols with text.
- Respect reduced motion.
- Add retry/settings actions for offline/service errors.
After coding:
1. List statuses added.
2. Explain loading/progress behavior.
3. Explain error recovery.
4. Explain notification behavior.
5. 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.

