# System surfaces in detail

Companion to `../SKILL.md` for the `hig-components-system` skill.

## Widgets

- Design each supported family separately (`.systemSmall`, `.systemMedium`,
  `.systemLarge`, `.accessoryCircular`, `.accessoryRectangular`,
  `.accessoryInline`); do not just scale one layout.
- A small widget is one tap target. Medium and larger may contain several
  `Link`s or, since iOS 17, `Button` and `Toggle` backed by an `AppIntent`
  for interactive actions that run without opening the app.
- Provide a `containerBackground(for: .widget)` so the system can remove or
  tint it in StandBy, on the Lock Screen and in tinted or clear Home Screen
  appearances.
- Support accented rendering: mark the key elements with
  `.widgetAccentable()` and check images with
  `.widgetAccentedRenderingMode(_:)` (iOS 18) so the widget reads when the
  person tints their Home Screen or uses the iOS 26 clear style.
- Make widgets configurable through `AppIntentConfiguration` when people will
  want different content in different instances (which project, which list).
- Keep refreshes within the system budget: rely on timelines and
  `WidgetCenter.shared.reloadTimelines(ofKind:)` after real data changes.

## Controls

- A control does one thing: toggle a state or run an action, with a clear
  symbol and a short title. Use `ControlWidgetToggle` for state and
  `ControlWidgetButton` for actions.
- Controls also appear on the Lock Screen and the Action button, so the
  symbol must make sense with no surrounding app context.

## Live Activities and the Dynamic Island

- Use a Live Activity for an event with a clear start and end that people
  track actively (an order being prepared and delivered, a timer, a match).
  It is not a place for ads or general summaries.
- Design every presentation: Lock Screen banner, Dynamic Island compact
  leading and trailing, minimal (when another activity shares the island),
  and expanded regions.
- The compact and minimal views carry one glanceable value; put detail in
  the expanded view and the Lock Screen banner.
- Update through ActivityKit locally or with ActivityKit push notifications;
  keep content state small because the push payload is size limited.
- End the activity promptly when the event finishes, with a final state
  that shows the outcome, and set a dismissal policy so it does not linger.

## Notifications

- Send only what the person would want to be interrupted for, and let them
  choose categories inside the app.
- Ask for permission in context, after the value is clear, or use
  provisional authorisation so notifications arrive quietly first.
- Choose the interruption level honestly: `.passive` for background
  information, `.active` by default, `.timeSensitive` only for things that
  lose value within minutes, `.critical` only with Apple's entitlement.
- Group related notifications with a `threadIdentifier`, and add actionable
  buttons through a `UNNotificationCategory` so common responses happen in
  place.
- Write the title and body so they make sense on their own and never
  include information the person would not want on a locked screen.

## Complications and watch faces

- A complication shows one value that changes during the day (the next
  task, a count, a level). Use `Gauge` and SF Symbols so it adapts to tinted
  faces.
- Support the accessory families that fit the data, including
  `.accessoryCorner` on watchOS, and provide a meaningful placeholder.

## Home Screen quick actions

- Offer a small set of the most frequent tasks (new note, search, scan) and
  keep them stable; dynamic items may reflect recent content.
- Each needs a short verb-led title and an SF Symbol; handle them in the
  scene delegate so the app opens straight into the task.

## App Shortcuts and Siri

- Expose the actions people repeat through `AppIntent` and list the best ones
  in an `AppShortcutsProvider` with natural phrases that include the app name.
- Shortcuts work with no setup and appear in Spotlight, Siri and the Action
  button, so name them as the task, not the screen.
- Return a result dialog or snippet so the action completes without opening
  the app when possible.

## App Clips

- An App Clip does one task fast (pay for a parking spot, order at a table)
  and asks for no account up front; use Sign in with Apple or Apple Pay when
  identity or payment is needed.
- Keep it within the platform size limit and offer the full app afterwards
  with `SKOverlay`, never before the task is done.

## Top Shelf (tvOS)

- Feature content people are likely to resume or watch next, with artwork at
  the required sizes, and deep link each item into playback or its detail.