@mmerterden/multi-agent-pipeline 20.2.1 → 20.3.0

package/pipeline/skills/shared/external/hig-components-status/SKILL.md

@@ -1,82 +1,154 @@
 ---
 name: hig-components-status
-description: "Apple HIG guidance for status and progress UI components including progress indicators, status bars, and activity rings. Use when designing or reviewing progress, status or feedback UI on an Apple platform."
-risk: unknown
-source: community
-date_added: '2026-02-27'
+description: "Apple HIG for status UI mapped to SwiftUI: progress views, gauges, placeholders, status bar, activity rings, success and failure feedback. Use when showing progress or state on an Apple platform."
+metadata:
+  risk: safe
+  source: multi-agent-pipeline
+  date_added: "2026-09-25"
 ---
 
-# 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
-
-### Progress Indicators
-
-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.
-
-### Status Bars
-
-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 promptly** when exiting immersive contexts.
-
-### Activity Rings
-
-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.
-
-## Topics
-
-| Topic | Key content |
-|---|---|
-| Progress bars and spinners | Determinate, indeterminate, inline placement, duration |
-| iOS/iPadOS status bar | System info, visibility, style, safe areas |
-| watchOS activity rings | Move/Exercise/Stand, HealthKit, fitness tracking, color |
-
-## 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)*
-
-## When to Use
-This skill is applicable to execute the workflow or actions described in the overview.
+# HIG: Status and Progress
+
+People tolerate waiting when they can see that something is happening and
+roughly how long it will take. This skill picks the right indicator for the
+situation and checks it is honest, calm and accessible.
+
+## Decide what you know
+
+The first question is whether the app knows how much work remains.
+
+| What the app knows | Indicator | SwiftUI |
+|---|---|---|
+| Fraction complete (bytes, items, steps) | Determinate bar | `ProgressView(value: done, total: count)` |
+| A deadline or countdown | Timer progress | `ProgressView(timerInterval: range, countsDown: true)` |
+| Nothing about duration | Indeterminate spinner | `ProgressView()` |
+| A level within a range (storage, battery, score) | Gauge | `Gauge(value:in:)` with a `.gaugeStyle` |
+| A value on a fixed scale people set | Rating | a custom control of SF Symbols with `.accessibilityAdjustableAction` |
+| Daily goal completion (Move, Exercise, Stand) | Activity rings | `HKActivityRingView` via `UIViewRepresentable` on iOS |
+| Content is coming, layout is known | Placeholder | `.redacted(reason: .placeholder)` on real row views |
+
+Switch from indeterminate to determinate as soon as a total becomes known.
+Never fake a determinate bar that creeps forward on a timer.
+
+## Progress indicators
+
+- Show nothing for work that finishes almost instantly; a spinner flashing on
+  screen reads as a glitch. Delay showing it briefly, then keep it up long
+  enough to be read.
+- Put the indicator where the result will appear: inside the button that
+  started the upload, in the row that is syncing, not in a blocking overlay.
+- Label long operations with what is happening ("Uploading 3 of 12 photos")
+  and let people cancel or leave the screen while it continues.
+- Keep the app usable while work runs. A full-screen blocking spinner is a
+  last resort for work that truly prevents every other action.
+- A bar only moves forward. If an estimate turns out wrong, pause rather than
+  jump backwards.
+- In compact spaces such as a toolbar item, show determinate progress as a
+  ring with `Gauge` and `.gaugeStyle(.accessoryCircularCapacity)` rather than
+  a squeezed bar.
+
+```swift
+struct UploadRow: View {
+    let task: UploadTask
+
+    var body: some View {
+        LabeledContent(task.fileName) {
+            if let fraction = task.fraction {
+                ProgressView(value: fraction)
+                    .frame(width: 80)
+            } else {
+                ProgressView()
+            }
+        }
+        .accessibilityValue(task.fraction.map { $0.formatted(.percent) } ?? "Waiting")
+    }
+}
+```
+
+## Loading content
+
+- Prefer placeholders shaped like the final content (`.redacted`) over a
+  centred spinner; the screen stops jumping when data arrives.
+- Keep previously loaded content visible during a refresh, and show the
+  refresh with the standard pull-to-refresh control from `.refreshable`.
+- If loading fails, replace the placeholder with a short explanation and a
+  retry action, not an alert that has to be dismissed.
+
+## Gauges
+
+- Use a gauge for a current value within known bounds, not for progress of a
+  task. Storage used out of capacity is a gauge; an upload is progress.
+- `.gaugeStyle(.accessoryCircular)`, `.accessoryCircularCapacity` and
+  `.accessoryLinear` match the look of widgets and watch complications.
+- Label the bounds when they matter (`currentValueLabel`,
+  `minimumValueLabel`, `maximumValueLabel`) and tint with a gradient only when
+  the colour change carries meaning, backed by the numeric label.
+
+## Rating indicators
+
+- Show ratings with filled, half and empty symbols and the numeric value for
+  VoiceOver ("4.5 out of 5 stars").
+- When people set a rating, make the whole row one adjustable accessibility
+  element so swipe up and down changes it.
+
+## Activity rings
+
+- Rings belong to Apple's fitness system. Show them only with real
+  HealthKit activity summary data, using `HKActivityRingView`; never redraw a
+  lookalike for unrelated progress such as task completion.
+- Do not recolour, relabel or repurpose the rings, and keep enough dark
+  background around them for contrast.
+
+## The status bar
+
+- Leave the status bar visible in most apps; people rely on time, battery and
+  connectivity. Hide it (`.statusBarHidden()`) only for immersive media, and
+  use `.persistentSystemOverlays(.hidden)` to reduce the home indicator in
+  games or video.
+- Keep content legible under it: the system matches its style to the colour
+  scheme, so avoid busy imagery right behind it.
+
+## Feedback after an action
+
+- Confirm success quietly and in place: a checkmark in the button, a row that
+  updates, a short haptic with `.sensoryFeedback(.success, trigger:)`.
+- Reserve alerts for failures that need a decision. For everything else,
+  explain inline next to the thing that failed.
+- Network and sync status belongs near the affected content (a banner above
+  the list, a badge on the row), and disappears when resolved.
+
+## Accessibility and motion
+
+- Every indicator needs an accessibility label; determinate ones expose their
+  value, and changes that matter are announced with
+  `AccessibilityNotification.Announcement`.
+- Respect Reduce Motion (`@Environment(\.accessibilityReduceMotion)`): swap
+  pulsing or shimmering placeholders for a static state.
+- Never rely on colour alone to show state; pair it with a symbol or text.
+
+## Review checklist
+
+1. Is the indicator determinate whenever the app knows the total?
+2. Is it placed where the result appears, without blocking unrelated work?
+3. Can long work be cancelled or continued in the background?
+4. Do loading states use placeholders and keep old content during refresh?
+5. Is a gauge used for levels and progress for tasks, never swapped?
+6. Is the status bar left alone outside immersive content?
+7. Are success and failure communicated inline, with alerts only for decisions?
+8. Do VoiceOver and Reduce Motion users get the same information?
+
+## Related skills
+
+- `hig-components-content` for empty and error states of lists and grids.
+- `hig-components-system` for progress shown in widgets and Live Activities.
+- `hig-foundations` for motion, colour and accessibility basics.
+- `healthkit` for reading the activity summary that feeds activity rings.
+
+## References
+
+- https://developer.apple.com/design/human-interface-guidelines/progress-indicators
+- https://developer.apple.com/design/human-interface-guidelines/gauges
+- https://developer.apple.com/design/human-interface-guidelines/rating-indicators
+- https://developer.apple.com/design/human-interface-guidelines/activity-rings
+- https://developer.apple.com/design/human-interface-guidelines/status-bars
+- https://developer.apple.com/design/human-interface-guidelines/feedback

package/pipeline/skills/shared/external/hig-components-system/SKILL.md

@@ -1,101 +1,80 @@
 ---
 name: hig-components-system
-description: 'Apple HIG guidance for system experience components: widgets, live activities, notifications, complications, home screen quick actions, top shelf, watch faces, app clips, and app shortcuts. Use when designing or reviewing widgets, Live Activities or notifications on an Apple platform.'
-risk: unknown
-source: community
-date_added: '2026-02-27'
+description: "Apple HIG for system surfaces: widgets, controls, Live Activities, Dynamic Island, notifications, complications, quick actions, App Shortcuts, App Clips. Use when an app appears outside its own window."
+metadata:
+  risk: safe
+  source: multi-agent-pipeline
+  date_added: "2026-09-25"
 ---
 
-# 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
-
-### General
-
-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.
-
-### Widgets
-
-3. **Show relevant information, not everything.** Display the most useful subset, updated appropriately.
-
-4. **Support multiple 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.
-
-### Live Activities
-
-6. **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.
-
-### Notifications
-
-8. **Respect user attention.** Only send notifications for information users genuinely care about. No promotional or low-value notifications.
-
-9. **Actionable and self-contained.** Include enough context to understand and act without opening the app. Support notification actions. Use threading and grouping.
-
-### Complications
-
-10. **Focused data on the watch face.** Design for the smallest useful representation. Support multiple families. Budget updates wisely.
-
-### Home Screen Quick Actions
-
-11. **3-4 most common tasks.** Short titles, optional subtitles, relevant SF Symbol icons.
-
-### Top Shelf
-
-12. **tvOS showcase.** Feature content that entices: new episodes, featured items, recent content.
-
-### App Clips
-
-13. **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.
-
-### App Shortcuts
-
-14. **Surface key actions to Siri and Spotlight.** Define shortcuts for frequent tasks. Use natural, conversational trigger phrases.
-
-## Topics
-
-| Topic | Key content |
-|---|---|
-| Widgets | Glanceable info, sizes, deep linking, timeline |
-| Live Activities | Real-time tracking, Dynamic Island, Lock Screen |
-| Notifications | Attention, actions, grouping, content |
-| Complications | Watch face data, families, budgeted updates |
-| Quick actions | Haptic Touch, common tasks, SF Symbols |
-| Top shelf | Featured content, showcase |
-| App Clips | Instant use, lightweight, focused task, NFC/QR |
-| Watch faces | Custom complications, face sharing |
-| App Shortcuts | Siri, Spotlight, voice triggers |
-
-## 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)*
-
-## When to Use
-This skill is applicable to execute the workflow or actions described in the overview.
+# HIG: System Surfaces
+
+System surfaces show a slice of the app where people already are: the Home
+Screen, the Lock Screen, Control Center, the watch face, Siri and Spotlight.
+Each is small, glanceable and shared with every other app, so the bar is
+relevance first and decoration last.
+
+## Choose the surface
+
+| People want to... | Surface | Framework |
+|---|---|---|
+| Glance at current information without opening the app | Widget | WidgetKit `Widget`, `TimelineProvider` |
+| Flip a setting or start an action in one tap | Control | WidgetKit `ControlWidget` (iOS 18) |
+| Follow something happening right now, minute by minute | Live Activity | ActivityKit + WidgetKit `ActivityConfiguration` |
+| Learn that something changed while away | Notification | UserNotifications, APNs |
+| See one value on the watch face | Complication | WidgetKit accessory families on watchOS |
+| Jump to a frequent task from the app icon | Quick action | `UIApplicationShortcutItem` |
+| Ask Siri, Spotlight or the Action button to do something | App Shortcut | App Intents `AppShortcutsProvider` |
+| Finish a small task without installing the app | App Clip | App Clip target + invocation URL |
+| Browse featured content on Apple TV | Top Shelf | `TVTopShelfContentProvider` |
+
+Pick one primary surface per job. A delivery that is en route is a Live
+Activity; the order being placed is a notification; the list of open orders
+is a widget.
+
+## Shared rules
+
+- Show the one thing that matters now, then stop. Anything needing reading or
+  typing belongs in the app.
+- Tapping a surface opens the app at the exact item shown, via `widgetURL`,
+  `Link` or the intent's result, never at the root screen.
+- Content must stay correct without the app running: plan timelines and
+  pushes so stale data is never shown as current. Use relative dates
+  (`Text(date, style: .relative)`, `Text(timerInterval:)`) so time moves
+  without refreshes.
+- Respect privacy on shared screens: mark sensitive text with
+  `.privacySensitive()` so it redacts when the device is locked.
+
+## Details on demand
+
+Load `references/surfaces.md` for the rules and SwiftUI/WidgetKit/ActivityKit APIs for each surface in the table above.
+
+## Review checklist
+
+1. Is each job on the single surface that fits it best?
+2. Does every tap land on the exact item shown?
+3. Is displayed data correct without the app running, with relative times?
+4. Do widgets support every declared family, tinted and clear appearances?
+5. Do Live Activities cover all presentations and end promptly?
+6. Do notifications use honest interruption levels, threads and actions?
+7. Is sensitive content redacted on locked screens?
+8. Are App Shortcuts phrased as tasks and usable without opening the app?
+
+## Related skills
+
+- `widgetkit`, `live-activities`, `push-notifications`, `app-intents`,
+  `app-clips` for implementation detail.
+- `hig-components-status` for progress and gauges inside these surfaces.
+- `hig-technologies` for Siri, Apple Pay and other system technologies.
+
+## References
+
+- https://developer.apple.com/design/human-interface-guidelines/widgets
+- https://developer.apple.com/design/human-interface-guidelines/controls
+- https://developer.apple.com/design/human-interface-guidelines/live-activities
+- https://developer.apple.com/design/human-interface-guidelines/notifications
+- https://developer.apple.com/design/human-interface-guidelines/complications
+- https://developer.apple.com/design/human-interface-guidelines/home-screen-quick-actions
+- https://developer.apple.com/design/human-interface-guidelines/app-shortcuts
+- https://developer.apple.com/design/human-interface-guidelines/app-clips
+- https://developer.apple.com/design/human-interface-guidelines/top-shelf

package/pipeline/skills/shared/external/hig-components-system/references/surfaces.md

@@ -0,0 +1,98 @@
+# 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.