Hig Components Status

Apple HIG: Status Components

Check for .claude/apple-design-context.md before asking questions. Use existing context and only ask for information not already covered.

Key Principles

1. Show progress for operations longer than a second or two.

2. Determinate when duration/percentage is known. A filling progress bar gives users a clear sense of remaining work. Use for downloads, uploads, or any measurable process.

3. Indeterminate when duration is unknown. A spinner communicates work is happening without promising a timeframe. Use for unpredictable network requests.

4. Prefer progress bars over spinners. Determinate progress feels faster and more trustworthy.

5. Place indicators where content will appear. Inline progress near the content area, not modal or distant.

6. Don't stack multiple indicators. Aggregate simultaneous operations into one representation or show the most relevant.

7. Don't hide the status bar without good reason. Reserve hiding for immersive experiences (full-screen media, games, AR).

8. Match status bar style to your content. Light or dark for adequate contrast.

9. Respect safe areas. No interactive content behind the status bar.

10. Restore the status bar promptly when exiting immersive contexts.

11. Activity rings are for Move, Exercise, and Stand goals. Don't repurpose the ring metaphor for unrelated data.

12. Respect ring color conventions. Red (Move), green (Exercise), blue (Stand) are strongly associated with Apple Fitness.

13. Use HealthKit APIs for activity data rather than manual tracking.

14. Celebrate completions with animation and haptics when rings close.

Reference Index

Output Format

1. Indicator type recommendation with rationale (determinate vs indeterminate). 2. Timing and animation guidance -- duration thresholds, animation style, transitions. 3. Accessibility -- VoiceOver progress announcements, live region updates. 4. Platform-specific behavior across targeted platforms.

Questions to Ask

1. Is the duration known or unknown? 2. Which platforms? 3. How long does the operation typically take? 4. System-level or in-app indicator?

Related Skills

• hig-components-system -- Widgets and complications displaying progress or status
• hig-inputs -- Gestures triggering progress states (pull-to-refresh)
• hig-technologies -- HealthKit for activity ring data; VoiceOver for progress announcements

---

Built by [Raintree Technology](https://raintree.technology) · [More developer tools](https://raintree.technology)

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/activity-rings.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Activity rings

Best practices

Display Activity rings when they’re relevant to the purpose of your app.

Use Activity rings only to show Move, Exercise, and Stand information.

Use Activity rings to show progress for a single person.

Always keep the visual appearance of Activity rings the same, regardless of where you display them.

• Never change the colors of the rings; for example, don’t use filters or modify opacity.

• Always display Activity rings on a black background.

• Prefer enclosing the rings and background within a circle. To do this, adjust the corner radius of the enclosing view rather than applying a circular mask.

• Ensure that the black background remains visible around the outermost ring. If necessary, add a thin, black stroke around the outer edge of the ring, and avoid including a gradient, shadow, or any other visual effect.

• Always scale the rings appropriately so they don’t seem disconnected or out of place.

• When necessary, design the surrounding interface to blend with the rings; never change the rings to blend with the surrounding interface.

To display a label or value that’s directly associated with an Activity ring, use the colors that match it.

Maintain Activity ring margins.

Differentiate other ring-like elements from Activity rings.

Don’t send notifications that repeat the same information the Activity app sends.

Don’t use Activity rings for decoration.

Don’t use Activity rings for branding.

Platform considerations

iOS

• With an Apple Watch paired, iOS shows all three Activity rings.

• Without an Apple Watch paired, iOS shows the Move ring only, which represents an approximation of a person’s activity based on their steps and workout information from other apps.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/activity-rings

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/progress-indicators.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Progress indicators

• _Determinate_ , for a task with a well-defined duration, such as a file conversion

• _Indeterminate_ , for unquantifiable tasks, such as loading or synchronizing complex data

Best practices

When possible, use a determinate progress indicator.

Be as accurate as possible when reporting advancement in a determinate progress indicator.

Keep progress indicators moving so people know something is continuing to happen.

When possible, switch a progress bar from indeterminate to determinate.

Don’t switch from the circular style to the bar style.

If it’s helpful, display a description that provides additional context for the task.

Display a progress indicator in a consistent location.

When it’s feasible, let people halt processing.

Let people know when halting a process has a negative consequence.

Platform considerations

iOS, iPadOS

Refresh content controls

Perform automatic content updates.

Supply a short title only if it adds value.

macOS

Prefer an activity indicator (spinner) to communicate the status of a background operation or when space is constrained.

Avoid labeling a spinning progress indicator.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/progress-indicators

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/status-bars.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Status bars

Best practices

Obscure content under the status bar.

Consider temporarily hiding the status bar when displaying full-screen media.

Avoid permanently hiding the status bar.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/status-bars