agentleFS
aka-kikaaka-kika/akakika-skills/skills/apple-hig/apple-hig-feedback-status/SKILL.md

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.

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

    Use this skill when designing or implementing feedback, status, progress, alerts, errors, success states, and live activity indicators in …

    line 8
  2. Distinctive:

    Use for local state near content.

    line 55
  3. Distinctive:

    Use for screen-level issues.

    line 65
  4. Distinctive:

    Use for destructive actions, permission issues, or blocking errors.

    line 74
  5. Distinctive:

    Use when work completes while user is elsewhere.

    line 78
  6. Distinctive:

    Use when time or steps matter.

    line 82
  7. Distinctive:

    Use loading indicators only when something is actually happening.

    line 104
  8. Distinctive:

    Use determinate progress only when you know the total.

    line 125
  9. Distinctive:

    Use indeterminate progress when the duration is unknown.

    line 131
  10. Distinctive:

    Do not blink aggressively.

    line 160
  11. Distinctive:

    Do not animate everything.

    line 161
  12. Distinctive:

    Avoid dramatic success messages.

    line 183
  13. Distinctive:

    Use alerts for blocking or dangerous operations.

    line 257
  14. Distinctive:

    Use notifications for background completion:

    line 272
  15. Distinctive:

    Do not notify for every minor state change.

    line 280

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

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

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
Cancelled

When 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 model

2. 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 user

Pair 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 review

Running 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 reduceMotion

Success feedback

Use short confirmation.

Task created
Report exported
Skill validated
Project opened
Settings saved

Avoid dramatic success messages.

Error feedback

Good error message structure:

What failed
Why it may have failed
What to do next

Example:

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 attention

Do 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 alone

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

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

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.