Hig Components System

Apple HIG: System Experiences

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

Key Principles

1. Glanceable, immediate value. System experiences bring your app's most important content to surfaces the user sees without launching your app. Design for seconds of attention.

2. Respect platform context. A Lock Screen widget has different constraints than a Home Screen widget. A complication is far smaller than a top shelf item.

3. Widgets: show relevant information, not everything. Display the most useful subset, updated appropriately.

4. Support multiple widget sizes with distinct layouts. Each size should be a thoughtful design, not a scaled version of another.

5. Deep-link on tap. Take users to the relevant content, not the app's root screen.

6. Live Activities: track events with a clear start and end. Deliveries, scores, timers, rides. Design for both Dynamic Island and Lock Screen.

7. Stay updated and timely. Stale data undermines trust. End promptly when the event concludes.

8. Respect user attention with notifications. Only send notifications for information users genuinely care about. No promotional or low-value notifications.

9. Notifications: actionable and self-contained. Include enough context to understand and act without opening the app. Support notification actions. Use threading and grouping.

10. Complications: focused data on the watch face. Design for the smallest useful representation. Support multiple families. Budget updates wisely.

11. Home Screen quick actions: 3-4 most common tasks. Short titles, optional subtitles, relevant SF Symbol icons.

12. Top Shelf: tvOS showcase. Feature content that entices: new episodes, featured items, recent content.

13. App Clips: instant, focused functionality within a strict size budget. Load quickly without App Store download. Only what's needed for the immediate task, then offer full app install.

14. App Shortcuts: surface key actions to Siri and Spotlight. Define shortcuts for frequent tasks. Use natural, conversational trigger phrases.

Reference Index

Output Format

1. System experience recommendation -- which surface best fits the use case. 2. Content strategy -- what to display, priority, what to omit. 3. Update frequency -- refresh rate including system budget constraints. 4. Size/family variants -- which to support and how layout adapts. 5. Deep link behavior -- where tapping takes the user.

Questions to Ask

1. What information needs to surface outside the app? 2. Which platform? 3. How frequently does the data update? 4. What is the primary glanceable need?

Related Skills

• hig-components-status -- Progress indicators in widgets or Live Activities
• hig-inputs -- Interaction patterns for system experiences (Digital Crown for complications)
• hig-technologies -- Siri for App Shortcuts, HealthKit for complications, NFC for App Clips

---

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/app-clips.

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.

App Clips

• A rental bike could come with an App Clip Code that people tap or scan to launch an App Clip that lets them rent the bike.

• A coffee shop could offer an App Clip for fast advance orders that customers launch from a Smart App Banner or an App Clip card on the shop’s website. Customers could share a link to the website from the Messages app, which recipients then tap to launch the App Clip from within Messages.

• A food truck could create marketing material (for example, a poster to promote a seasonal dish) that includes an App Clip Code. People can scan the App Clip Code with the Camera app on their device and instantly launch the App Clip to order the seasonal dish.

• A restaurant could let diners pay for a meal by launching an App Clip from the Maps app or a suggestion from Siri Suggestions, or by holding their device close to an App Clip Code or NFC tag at their table.

• A museum could have visitors scan App Clip Codes or QR codes on labels next to displayed works to launch an App Clip that reveals augmented reality content or provides audio commentary.

• A game might offer an App Clip that lets people play a demo version of the game, including a tutorial and the first level of the game.

• A fitness app might offer an App Clip with a free workout and a guided meditation.

• A text editor might allow people to create and save a document using the demo App Clip.

Designing your App Clip

Allow people to complete a task or a demo in your App Clip.

Focus on essential features.

Don’t use App Clips solely for marketing purposes.

Avoid using web views in your App Clip.

Design a linear, easy-to-use, and focused user interface.

On launch, show the most relevant part of your App Clip.

Ensure people can use your App Clip immediately.

Ensure your App Clip is small.

Make the App Clip shareable.

Make it easy to pay for a service or product.

Avoid requiring people to create an account before they can benefit from your App Clip.

Provide a familiar, focused experience in your app.

Preserving privacy

Limit the amount of data you store and handle yourself.

Consider offering Sign in with Apple.

Offer a secure way to pay for services or goods that also respects people’s privacy.

Showcasing your app

• On the App Clip card, people can either launch the App Clip or visit the full app’s page on the App Store.

• When people first launch the App Clip, the system displays an app banner at the top of the screen. Like the App Clip card, the banner allows people to visit the app’s page on the App Store.

Don’t compromise the user experience by asking people to install the full app.

Pick the right time to recommend your app.

Recommend your app in a nonintrusive, polite way.

Limiting notifications

Only ask for permission to use notifications for an extended period of time if it’s really needed.

Keep notifications focused.

Use notifications to help people complete a task.

Creating App Clips for businesses

Use consistent branding.

Consider multiple businesses.

Creating content for an App Clip card

Be informative.

Prefer photography and graphics.

Avoid using text.

Adhere to image requirements.

Use concise copy.

Pick a verb for the action button that best fits your App Clip.

App Clip Codes

Interacting with App Clip Codes

• A coffee shop could place an App Clip Code on their menu. A guest could hold their device close to the App Clip Code and instantly launch the shop’s App Clip to order a drink.

• A gas station could have an NFC-integrated App Clip Code attached to each pump. A traveler could hold their device close to it to launch the gas station’s App Clip and use it to pay for their refill.

• A video game creator could hand out marketing material at an industry event that includes an App Clip Code. An event attendee could scan the code to launch an App Clip that’s a playable demo of their latest video game.

Displaying App Clip Codes

• On a tabletop at a restaurant

• Near a register at a retail store

• In a storefront window

• On signage

• On a gift card or coupon

• On posters or printed advertising

• On signage behind a counter or unreachable in a storefront

• On digital materials such as digital displays, in emails, or on images you post to social media

Include the App Clip logo when space allows.

Place your App Clip Code on a flat or cylindrical surface only.

Help your App Clip Code remain as flat as possible so it’s easy for people to scan.

Place your App Clip Code in a location that helps ensure reliable scanning.

Make sure the App Clip Code is unobstructed.

Display the App Clip Code in an upright position.

Don’t create App Clip Codes that are too small.

Provide enough space between an App Clip Code and adjacent App Clip Codes, graphics, or materials.

Using clear messaging

• Scan to [_describe what people can do with your App Clip_].

• Scan using the camera on your iPhone or iPad to [describe what people can do with your App Clip].

• Scan to [_describe what people can do with your App Clip_].

• Hold your iPhone near the [_object name_] to launch an App Clip that [_describe what a person can do with your App Clip_].

Adhere to[Guidelines for Using Apple Trademarks](https://www.apple.com/legal/intellectual-property/guidelinesfor3rdparties.html) when referring to your App Clip and App Clip Codes.

Customizing your App Clip Code

Always use the generated App Clip Code.

Choose colors with enough contrast that ensure accurate scanning.

Printing guidelines

Use high-quality, non-textured print materials.

Use high-resolution images and printer settings.

Use correct color settings when you convert the generated SVG file to a CMYK image.

If you’re using a printer that only prints in grayscale, only generate grayscale App Clip Codes.

For NFC-integrated App Clip Codes, choose Type 5 NFC tags.

If you create large batches of App Clip Codes, thoroughly test your printing workflow, and verify printed App Clip Codes.

Verifying your printer’s calibration

Verify print quality of your chosen color pair with the printer calibration test sheet that shows text boxes for each default color pair.

Verify your printer’s grayscale settings by printing the printer calibration test sheet that shows two grayscale bars.

---

<!-- 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/app-clips

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

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

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.

App Shortcuts

Best practices

Offer App Shortcuts for your app’s most common and important tasks.

Add flexibility by letting people choose from a set of options.

Ask for clarification in response to a request that’s missing optional information.

Keep voice interactions simple.

Make App Shortcuts discoverable in your app.

Responding to App Shortcuts

• Snippets are great for custom views that display static information or dialog options, like showing the weather at a person’s location or confirming an order. For developer guidance, see `ShowsSnippetView`.

• Live Activities offer continuous access to information that’s likely to remain relevant and change over a period of time, and are great for timers and countdowns that appear until an event is complete. For developer guidance, see `LiveActivityIntent`.

Provide enough detail for interaction on audio-only devices.

Editorial guidelines

Provide brief, memorable activation phrases and natural variants.

When referring to App Shortcuts or the Shortcuts app, always use title case and make sure that _Shortcuts_ is plural.

When referring to individual shortcuts (not App Shortcuts or the Shortcuts app), use lowercase.

Platform considerations

iOS, iPadOS

Order shortcuts based on importance.

Offer an App Shortcut that starts a Live Activity.

---

<!-- 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/app-shortcuts

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

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

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.

Complications

Best practices

Identify essential, dynamic content that people want to view at a glance.

Support all complication families when possible.

Consider creating multiple complications for each family.

Define a different deep link for each complication you support.

Keep privacy in mind.

Carefully consider when to update data.

Visual design

Choose a ring or gauge style based on the data you need to display.

• The closed style can convey a value that’s a percentage of a whole, such as for a battery gauge.

• The open style works well when the minimum and maximum values are arbitrary — or don’t represent a percentage of the whole — like for a speed indicator.

• Similar to the open style, the segmented style also displays values within an app-defined range, and can convey rapid value changes, such as in the Noise complication.

Make sure images look good in tinted mode.

• Avoid using color as the only way to communicate important information. You want people to get the same information in tinted mode as they do in nontinted mode.

• When necessary, provide an alternative tinted-mode version of a full-color image. If your full-color image doesn’t look good when it’s desaturated, you can supply a different version of the image for the system to use in tinted mode.

Recognize that people might prefer to use tinted mode for complications, instead of viewing them in full color.

When creating complication content, generally use line widths of two points or greater.

Provide a set of static placeholder images for each complication you support.

Circular

• Style: Rounded

• Weight: Medium

• Text size: 12 pt (40mm), 12.5 pt (41mm), 13 pt (44mm), 14.5 pt (45mm/49mm)

• Style: Rounded

• Weight: Medium

• Text size: 34.5 pt (40mm), 36.5 pt (41mm), 36.5 pt (44mm), 41 pt (45mm/49mm)

Corner

• Style: Rounded

• Weight: Semibold

• Text size: 10 pt (40mm), 10.5 pt (41mm), 11 pt (44mm), 12 pt (45mm/49mm)

Rectangular

• By supplying background color or content that communicates information or aids in recognition

• By using intents to specify relevancy, and help ensure that your widget is displayed in the Smart Stack at times that are most appropriate and useful to people

• By creating a custom layout of your information that is optimized for the Smart Stack

• Style: Rounded

• Weight: Medium

• Text size: 16.5 pt (40mm), 17.5 pt (41mm), 18 pt (44mm), 19.5 pt (45mm/49mm)

---

<!-- 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/complications

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

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/home-screen-quick-actions.

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.

Home Screen quick actions

Best practices

Create quick actions for compelling, high-value tasks.

Avoid making unpredictable changes to quick actions.

For each quick action, provide a succinct title that instantly communicates the results of the action.

Provide a familiar interface icon for each quick action.

Don’t use an emoji in place of a symbol or interface icon.

---

<!-- 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/home-screen-quick-actions

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

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

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.

Live Activities

Anatomy

• Compact

• Minimal

• Expanded

• Lock Screen

Best practices

Offer Live Activities for tasks and events that have a defined beginning and end.

Focus on important information that people need to see at a glance.

Avoid displaying sensitive information.

Create a Live Activity that matches your app’s visual aesthetic and personality in both dark and light appearances.

If you include a logo mark, display it without a container.

Don’t add elements to your app that draw attention to the Dynamic Island.

Ensure text is easy to read.

Creating Live Activity layouts

Adapt to different screen sizes and presentations.

Adjust element size and placement for efficient use of space.

Use familiar layouts for custom views and layouts.

Use consistent margins and concentric placement.

When separating a block of content, place it in an inset container shape or use a thick line.

Dynamically change the height of your Live Activity on the Lock Screen or in the expanded presentation.

Choosing colors

Carefully consider using a custom background color and opacity.

Use color to express the character and identity of your app.

Tint your Live Activity’s key line color so that it matches your content.

Adding transitions and animating content updates

Use animations to reinforce the information you’re communicating and to bring attention to updates.

Animate layout changes.

Try to avoid overlapping elements.

Offering interactivity

Make sure tapping the Live Activity opens your app at the right location.

Focus on simple, direct actions.

Consider letting people respond to event or progress updates.

Starting, updating, and ending a Live Activity

Start Live Activities at appropriate times, and make it easy for people to turn them off in your app.

Offer an App Shortcut that starts your Live Activity.

Update a Live Activity only when new content is available.

Alert people only for essential updates that require their attention.

Let people track multiple events efficiently with a single Live Activity.

Always end a Live Activity immediately when the task or event ends, and consider setting a custom dismissal time.

Presentation

Start with the iPhone design, then refine it for other contexts.

Compact presentation

Focus on the most important information.

Ensure unified information and design of the compact presentations in the Dynamic Island.

Keep content as narrow as possible and ensure it’s snug against the TrueDepth camera.

Link to relevant app content.

Minimal presentation

Ensure that your Live Activity is recognizable in the minimal presentation.

Expanded presentation

Maintain the relative placement of elements to create a coherent layout between presentations.

Wrap content tightly around the TrueDepth camera.

Lock Screen presentation

Don’t replicate notification layouts.

Choose colors that work well on a personalized Lock Screen.

Make sure your design, assets, and colors look great and offer enough contrast in Dark Mode and on an Always-On display.

Verify the generated color of the dismiss button.

Use standard margins to align your design with notifications.

StandBy presentation

Update your layout for StandBy.

Consider using the default background color in StandBy.

Use standard margins and avoid extending graphic elements to the edge of the screen.

Verify your design in Night Mode.

CarPlay

Consider creating a custom layout if your Live Activity would benefit from larger text or additional information.

Carefully consider including buttons or toggles in your custom layout.

Platform considerations

watchOS

Consider creating a custom watchOS layout.

Carefully consider including buttons or toggles in your custom layout.

Focus on essential information and significant updates.

• Progress, like the estimated arrival time of a delivery

• Interactive elements, like stopwatch or timer controls

• Significant updates, like sports score changes

---

<!-- 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/live-activities

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

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

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.

Notifications

Anatomy

• A banner or view on a Lock Screen, Home Screen, Home View, or desktop

• A badge on an app icon

• An item in Notification Center

Best practices

Provide concise, informative notifications.

Avoid sending multiple notifications for the same thing, even if someone hasn’t responded.

Avoid sending a notification that tells people to perform specific tasks within your app.

Use an alert — not a notification — to display an error message.

Handle notifications gracefully when your app is in the foreground.

Avoid including sensitive, personal, or confidential information in a notification.

Content

Create a short title if it provides context for the notification content.

Write succinct, easy-to-read notification content.

Provide generically descriptive text to display when notification previews aren’t available.

Avoid including your app name or icon.

Consider providing a sound to supplement your notifications.

Notification actions

Provide beneficial actions that make sense in the context of your notification.

Avoid providing an action that merely opens your app.

Prefer nondestructive actions.

Provide a simple, recognizable interface icon for each notification action.

Badging

Use a badge only to show people how many unread notifications they have.

Make sure badging isn’t the only method you use to communicate essential information.

Keep badges up to date.

Avoid creating a custom image or component that mimics the appearance or behavior of a badge.

Platform considerations

watchOS

Short looks

Avoid using a short look as the only way to communicate important information.

Keep privacy in mind.

Long looks

Consider using a rich, custom long-look notification to let people get the information they need without launching your app.

At the minimum, provide a static interface; prefer providing a dynamic interface too.

Choose a background appearance for the sash.

Choose a background color for the content area.

Provide up to four custom actions below the content area.

Double tap

Keep double tap in mind when choosing the order of custom actions you present as responses to a notification.

---

<!-- 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/notifications

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

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

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.

Top Shelf

Best practices

Help people jump right into your content.

Feature new content.

Personalize people’s favorite content.

Avoid showing advertisements or prices.

Showcase compelling dynamic content that can help draw people in and encourage them to view more.

If you don’t provide the recommended full-screen content, supply at least one static image as a fallback.

Avoid implying interactivity in a static image.

Dynamic layouts

• A carousel of full-screen video and images that includes two buttons and optional details

• A row of focusable content

• A set of scrolling banners

Carousel actions

Provide a title.

Carousel details

Provide a title that identifies the currently playing content.

Sectioned content row

Provide enough content to constitute a complete row.

16:9

Be aware of additional scaling when combining image sizes.

Scrolling inset banner

Provide three to eight images.

If you need text, add it to your image.

---

<!-- 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/top-shelf

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

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

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.

Watch faces

Best practices

Help people discover your app by sharing watch faces that feature your complications.

Display a preview of each watch face you share.

Aim to offer shareable watch faces for all Apple Watch devices.

Respond gracefully if people choose an incompatible watch face.

---

<!-- 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/watch-faces

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

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

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.

Widgets

• On the Home Screen and Lock Screen of their iPhone and iPad

• On the desktop and Notification Center of their Mac

• On a horizontal or vertical surface when they wear Apple Vision Pro

• At a fixed position in the Smart Stack of Apple Watch

Anatomy

• The widget size to support

• The context — devices and system experiences — in which the widget may appear

• The rendering modes and color treatment that the widget receives based on the size and context

System family widgets

• Small
• Medium
• Large
• Extra large
• Extra large portrait

Accessory widgets

• Accessory circular
• Accessory corner
• Accessory inline
• Accessory rectangular

Appearances

• On the Home Screen of iPhone and iPad, people choose from different appearances for widgets: light, dark, clear, and tinted. In light and dark appearances, widgets have a full-color design. In a clear appearance, the system desaturates the widget and adds translucency, highlights, and the Liquid Glass material. In a tinted appearance, the system desaturates the widget and its content, then applies a person’s selected tint color.

• On Apple Vision Pro, the widget appears as a 3D object, surrounded by a frame. It takes on a full-color appearance with a glass- or paper-like coating layer that responds to lighting conditions. Additionally, people can choose a tinted appearance that applies a color from a set of system-provided color palettes.

• On the Lock Screen of iPad, the widget takes on a monochromatic appearance without a tint color.

• On the Lock Screen of iPhone in StandBy, the widget appears scaled up in size with the background removed. When the ambient light falls below a threshold, the system renders the widget with a monochromatic red tint.

• On the Lock Screen of iPhone and iPad, it takes on a monochromatic appearance without a tint color.

• On Apple Watch, the widget can appear as a watch complication in both full-color and tinted appearances, and it can also appear in the Smart Stack.

• iPhone Lock Screen
• Watch complication
• Smart Stack on Apple Watch

• The system uses the full color rendering mode for system family widgets across all platforms to display your widget in full color. It doesn’t change the color of your views.

• The system uses the accented rendering mode for system family widgets across all platforms and for accessory widgets on Apple Watch. In the accented rendering mode, the system removes the background and replaces it with a tinted color effect for a tinted appearance and a Liquid Glass background for a clear appearance. Additionally, it divides the widget’s views into an accent group and a primary group, and then applies a solid color to each group.

• The system uses the vibrant rendering mode for widgets on the Lock Screen of iPhone and iPad, and on iPhone in StandBy in low-light conditions. It desaturates text, images, and gauges, and creates a vibrant effect by coloring your content appropriately for the Lock Screen background or a macOS desktop. Note that people can customize the Lock Screen with a tint color, and the system applies a red tint for widgets that appear on iPhone in StandBy in low-light conditions.

Best practices

Choose simple ideas that relate to your app’s main purpose.

Aim to create a widget that gives people quick access to the content they want.

Prefer dynamic information that changes throughout the day.

Look for opportunities to surprise and delight.

Offer widgets in multiple sizes when doing so adds value.

Balance information density.

Display only the information that’s directly related to the widget’s main purpose.

Use brand elements thoughtfully.

Choose between automatically displaying content and letting people customize displayed information.

Avoid mirroring your widget’s appearance within your app.

Let people know when authentication adds value.

Updating widget content

Keep your widget up to date.

Use system functionality to refresh dates and times in your widget.

Use animated transitions to bring attention to data updates.

Adding interactivity

Offer simple, relevant functionality and reserve complexity for your app.

Ensure that a widget interaction opens your app at the right location.

Offer interactivity while remaining glanceable and uncluttered.

Choosing margins and padding

In general, use standard margins to ensure legibility.

Coordinate the corner radius of your content with the corner radius of the widget.

Displaying text in widgets

Prefer using the system font, text styles, and SF Symbols.

Avoid very small font sizes.

Avoid rasterizing text.

Using color

Use color to enhance a widget’s appearance without competing with its content.

Convey meaning without relying on specific colors to represent information.

Use full-color images judiciously.

Rendering modes

Full-color

Support light and dark appearances.

Accented

Group widget components into an accented and a primary group.

Vibrant

Offer enough contrast to ensure legibility.

Create optimized assets for the best vibrant effect.

Previews and placeholders

Design a realistic preview to display in the widget gallery.

Design placeholder content that helps people recognize your widget.

Write a succinct widget description.

Group your widget’s sizes together, and provide a single description.

Consider coloring the Add button.

Platform considerations

iOS, iPadOS

Support the Always-On display on iPhone.

Offer Live Activities to show real-time updates.

StandBy and CarPlay

Limit usage of rich images or color to convey meaning in StandBy.

• Correct usage
• Incorrect usage

visionOS

Adapt your design and content for the spatial experience Apple Vision Pro provides.

Test your widgets across the full range of system color palettes and in different lighting conditions.

Thresholds and sizes

Design a responsive layout that shows the right level of detail for each of the two thresholds.

Offer widget family sizes that fit a person’s surroundings well.

Display content in a way that remains legible from a range of distances.

Mounting styles

• [Elevated](https://developer.apple.com/documentation/WidgetKit/WidgetMountingStyle/elevated) style. On horizontal surfaces — for example, on a desk — the widget always appears elevated and gently tilts backward, providing a subtle angle that improves readability, and casts a soft shadow that helps it feel grounded on the surface. On vertical surfaces — for example, on a wall — the widget either appears elevated, sitting flush on the surface and similar to how you mount a picture frame.

• [Recessed](https://developer.apple.com/documentation/WidgetKit/WidgetMountingStyle/recessed) style. On vertical surfaces — for example, on a wall — the widget can appear recessed, with content set back into the surface, creating a depth effect that gives the illusion of a cutout in the surface. Horizontal surfaces don’t use the recessed mounting style.

Choose the mounting style that fits your content and the experience you want to create.

Test your elevated widget designs with each system-provided frame width.

Treatment styles

• The `paper` style creates a more grounded, print-like style that feels solid and makes the widget feel like part of its surroundings. When lighting conditions change, widgets in the paper style become darker or lighter in response.

• The `glass` style creates a lighter, layered look that adds depth and visual separation between foreground and background elements to emphasize clarity and contrast. The foreground elements always stay bright and legible, and don’t dim or brighten, even as ambient light changes.

Choose the paper style for a print-like look that feels more like a real object in the room.

Choose the glass style for information-rich widgets.

watchOS

Provide a colorful background that conveys meaning.

Encourage the system to display or elevate the position of your watchOS widget in the Smart Stack.

Specifications

iPadOS dimensions

• When Display Zoom is set to More Space.

---

<!-- 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/widgets