@mmerterden/multi-agent-pipeline 20.17.0 → 20.17.2

package/pipeline/skills/shared/external/hig-foundations/evals/trigger-eval.json

@@ -0,0 +1,21 @@
+[
+  {"query": "what's the minimum font size apple allows on iphone? design wants 9pt captions", "should_trigger": true},
+  {"query": "our custom font doesn't scale with dynamic type, we use Font.custom(name, size: 16) everywhere", "should_trigger": true},
+  {"query": "is #8E8E93 text on white ok for accessibility? it's a 14pt price label", "should_trigger": true},
+  {"query": "which font weights should I avoid in the app, designer loves Ultralight for headlines", "should_trigger": true},
+  {"query": "how much padding between rows and what margins does apple recommend, we keep guessing 7, 9, 13", "should_trigger": true},
+  {"query": "dark mode: our hardcoded Color.white backgrounds and gray dividers look awful, what colors should we use", "should_trigger": true},
+  {"query": "headline vs body vs callout - what sizes are these text styles on iOS and when do I make one bold", "should_trigger": true},
+  {"query": "tiny 20pt close button in the corner, testers keep missing it - what size should tap targets be", "should_trigger": true},
+  {"query": "status shown only with red/green dots in our order list, is that a problem per HIG", "should_trigger": true},
+  {"query": "make my glass toolbar buttons tinted with the brand color on iOS 26", "should_trigger": false},
+  {"query": "which SF Symbol rendering mode should I use for the battery icon with a level", "should_trigger": false},
+  {"query": "design the app icon dark and tinted variants in Icon Composer", "should_trigger": false},
+  {"query": "set up VoiceOver labels and rotors for our custom chart", "should_trigger": false},
+  {"query": "tab bar or sidebar for an iPad app with 9 sections?", "should_trigger": false},
+  {"query": "onboarding flow: should we ask for notification permission on first launch", "should_trigger": false},
+  {"query": "Material 3 typography scale for our Compose app", "should_trigger": false},
+  {"query": "take screenshots of the checkout screen at AX5 and dark mode and review them", "should_trigger": false},
+  {"query": "CSS rem vs px for our marketing site font sizes", "should_trigger": false},
+  {"query": "add a gentle haptic when a row is deleted", "should_trigger": false}
+]

package/pipeline/skills/shared/external/hig-foundations/references/foundations-detail.md

@@ -2,6 +2,18 @@
 
 Companion to `../SKILL.md` for the `hig-foundations` skill.
 
+## Contents
+
+- [1. Typography](#1-typography)
+- [2. Color](#2-color)
+- [3. Layout, margins and safe areas](#3-layout-margins-and-safe-areas)
+- [4. Icons and SF Symbols](#4-icons-and-sf-symbols)
+- [5. Materials, Liquid Glass and depth](#5-materials-liquid-glass-and-depth)
+- [6. Motion](#6-motion)
+- [7. App icon](#7-app-icon)
+- [8. Writing](#8-writing)
+- [9. Accessibility, as a foundation](#9-accessibility-as-a-foundation)
+
 ## 1. Typography
 
 Ask: if the user sets the largest accessibility text size, does every string
@@ -19,7 +31,13 @@ still fit, wrap or scroll?
   `@Environment(\.dynamicTypeSize)` and check `.isAccessibilitySize`, or use
   `ViewThatFits` to let the layout choose.
 - Keep a clear hierarchy with weight and style, not with many sizes. Two or
-  three styles per screen is usually enough.
+  three styles per screen is usually enough; use a style's emphasized weight
+  (`.bold()`) before reaching for a bigger style.
+- Respect the floor: 17 pt default and 11 pt minimum on iOS, for custom fonts
+  too. Avoid Ultralight, Thin and Light weights for interface text.
+
+Numbers, the full text style table and custom-font code:
+[type-color-spacing.md](type-color-spacing.md).
 
 Review signal: truncated order totals, overlapping labels, or buttons whose
 titles are clipped at `accessibility3` and above.
@@ -37,8 +55,9 @@ with increased contrast, and to someone who cannot distinguish red from green?
 - Set the app accent once with `.tint(...)` near the root; controls pick it up.
 - Never carry meaning by color alone. A failed payment shows an icon and a
   word, not only a red row.
-- Aim for at least 4.5:1 contrast for body text and 3:1 for large text and
-  essential glyphs.
+- Meet at least 4.5:1 contrast for text up to 17 pt and 3:1 for 18 pt and
+  larger or bold text; if the default palette cannot, provide a
+  higher-contrast scheme under Increase Contrast.
 
 Review signal: hard-coded hex values, `Color.white` text on a brand color that
 fails contrast in dark mode, status conveyed only by hue.
@@ -66,34 +85,25 @@ rounded corners and the keyboard, while backgrounds still reach the edges?
 Ask: is there a system symbol for this, and does it match the weight of the
 text beside it?
 
-- Use `Image(systemName:)` and `Label` so symbols align with text baselines and
-  scale with Dynamic Type.
-- Pick a rendering mode on purpose: `.symbolRenderingMode(.hierarchical)` for
-  depth, `.palette` for brand pairs, `.multicolor` where the symbol ships it.
-- Use `.symbolVariant(.fill)` for selected states, as tab bars do.
-- Animate state with `.symbolEffect` (bounce on add-to-cart, pulse while
-  syncing) and `.contentTransition(.symbolEffect(.replace))` between glyphs.
-- Custom symbols belong in the asset catalog as symbol templates so they gain
-  weights and scales like system ones.
+Use `Image(systemName:)` and `Label` so symbols align with text and scale with
+Dynamic Type. Rendering modes, variable values, symbol effects and custom
+symbols are covered in `ios-sf-symbols`.
 
 ## 5. Materials, Liquid Glass and depth
 
 Ask: does this layer float above content, and does the content stay legible
 under it?
 
-- On iOS 26 and later, system bars, tab bars, sheets and toolbars adopt Liquid
-  Glass automatically when built with standard SwiftUI containers. Avoid
-  painting opaque backgrounds on them; that removes the effect.
-- For custom floating controls, apply `.glassEffect()` and group neighbors in a
-  `GlassEffectContainer` so shapes blend and morph together. Keep glass for the
-  navigation and control layer, not for content cards.
-- Use `.buttonStyle(.glass)` or `.glassProminent` for floating actions that
-  should match system controls.
-- Before iOS 26, use materials (`.regularMaterial`, `.thinMaterial`) for
-  overlays; gate newer APIs with `if #available(iOS 26, *)`.
+- Liquid Glass is for the navigation and control layer; content uses standard
+  materials (`.ultraThinMaterial` to `.thickMaterial`) or solid fills.
+- Vibrant label and fill colors keep text legible on materials; avoid the
+  quaternary label level on thin and ultra-thin materials.
 - Respect Reduce Transparency: system materials handle it, custom blurs must
   check `accessibilityReduceTransparency`.
 
+Everything about glass itself (variants, containers, fallbacks, UIKit) lives
+in `swiftui-liquid-glass`.
+
 ## 6. Motion
 
 Ask: does this animation explain a change, and what happens when Reduce Motion
@@ -110,10 +120,8 @@ is on?
 
 ## 7. App icon
 
-- Provide a single 1024 by 1024 source and let Xcode generate sizes; on iOS 18
-  and later supply dark and tinted variants. From iOS 26, author layered icons
-  in Icon Composer so the system can render the glass appearance.
-- Keep the icon a simple, recognizable shape without text or screenshots.
+Layered icons, Icon Composer, the default, dark, clear and tinted appearances
+and the asset catalog setup are covered in `hig-app-icons`.
 
 ## 8. Writing
 

package/pipeline/skills/shared/external/hig-foundations/references/type-color-spacing.md

@@ -0,0 +1,219 @@
+# Typography, color and spacing: numbers and code
+
+Companion to `../SKILL.md` for the `hig-foundations` skill. The numbers below
+come from Apple's Human Interface Guidelines (Typography, Accessibility,
+Color, Layout); the spacing scale is a design convention, marked as such.
+
+## Contents
+
+1. [Text sizes and weights](#1-text-sizes-and-weights)
+2. [iOS text styles at the default size](#2-ios-text-styles-at-the-default-size)
+3. [Custom fonts that still scale](#3-custom-fonts-that-still-scale)
+4. [Adapting layout at large sizes](#4-adapting-layout-at-large-sizes)
+5. [Color roles](#5-color-roles)
+6. [Contrast minimums](#6-contrast-minimums)
+7. [Color on Liquid Glass](#7-color-on-liquid-glass)
+8. [Spacing and margins](#8-spacing-and-margins)
+9. [Touch targets](#9-touch-targets)
+
+## 1. Text sizes and weights
+
+| Platform | Default size | Minimum size |
+|---|---|---|
+| iOS, iPadOS | 17 pt | 11 pt |
+| macOS | 13 pt | 10 pt |
+| tvOS | 29 pt | 23 pt |
+| visionOS | 17 pt | 12 pt |
+| watchOS | 16 pt | 12 pt |
+
+- The minimum applies to custom fonts too. A thin custom face needs to sit
+  above these sizes to stay legible.
+- Prefer Regular, Medium, Semibold or Bold. Avoid Ultralight, Thin and Light,
+  which are hard to read, especially at small sizes.
+- Keep the number of typefaces small; build hierarchy with weight, size and
+  color inside one family.
+
+## 2. iOS text styles at the default size
+
+Values at the Large (default) content size. Emphasized weight is what the
+style turns into with `.bold()` in SwiftUI or the bold symbolic trait in UIKit.
+
+| SwiftUI style | Weight | Size (pt) | Leading (pt) | Emphasized weight |
+|---|---|---|---|---|
+| `.largeTitle` | Regular | 34 | 41 | Bold |
+| `.title` | Regular | 28 | 34 | Bold |
+| `.title2` | Regular | 22 | 28 | Bold |
+| `.title3` | Regular | 20 | 25 | Semibold |
+| `.headline` | Semibold | 17 | 22 | Semibold |
+| `.body` | Regular | 17 | 22 | Semibold |
+| `.callout` | Regular | 16 | 21 | Semibold |
+| `.subheadline` | Regular | 15 | 20 | Semibold |
+| `.footnote` | Regular | 13 | 18 | Semibold |
+| `.caption` | Regular | 12 | 16 | Semibold |
+| `.caption2` | Regular | 11 | 13 | Semibold |
+
+```swift
+Text(order.total, format: .currency(code: order.currencyCode))
+    .font(.body)
+    .bold()
+```
+
+Use the emphasized variant for a second level of hierarchy inside a style
+instead of jumping to a bigger style. Bold Text (an accessibility setting) is
+honoured automatically by system fonts; read `legibilityWeight` when a custom
+drawing needs to follow it.
+
+## 3. Custom fonts that still scale
+
+A custom face keeps Dynamic Type only when it is tied to a text style:
+
+```swift
+extension Font {
+    static func brand(_ style: Font.TextStyle, size: CGFloat) -> Font {
+        .custom("BrandSans-Regular", size: size, relativeTo: style)
+    }
+}
+
+Text("Your trips")
+    .font(.brand(.title, size: 28))
+```
+
+`Font.custom(_:size:relativeTo:)` (iOS 14) scales the given size the way the
+named text style scales. `Font.custom(_:size:)` alone also scales relative to
+body; `Font.custom(_:fixedSize:)` does not scale and is only for content that
+must not grow. Numeric layout values next to text use `@ScaledMetric`:
+
+```swift
+@ScaledMetric(relativeTo: .body) private var iconSide: CGFloat = 24
+```
+
+In UIKit, `UIFontMetrics(forTextStyle:).scaledFont(for:)` with
+`adjustsFontForContentSizeCategory = true` does the same.
+
+## 4. Adapting layout at large sizes
+
+- Keep truncation to a minimum: aim to show as much useful text at the largest
+  accessibility size as at the largest standard size.
+- Switch side-by-side arrangements to stacked ones in horizontally constrained
+  places, and reduce the number of columns.
+- Keep primary elements toward the top even at very large sizes.
+- Not every word must grow: tab titles, for example, stay put while content
+  grows. Small fixed controls can offer the Large Content Viewer instead
+  (see `ios-accessibility`).
+
+```swift
+@Environment(\.dynamicTypeSize) private var typeSize
+
+var body: some View {
+    let layout = typeSize.isAccessibilitySize
+        ? AnyLayout(VStackLayout(alignment: .leading, spacing: 8))
+        : AnyLayout(HStackLayout(spacing: 12))
+    layout {
+        Text(item.title).font(.headline)
+        Text(item.subtitle).font(.subheadline).foregroundStyle(.secondary)
+    }
+}
+```
+
+## 5. Color roles
+
+| Role | SwiftUI |
+|---|---|
+| Labels | `.primary`, `.secondary`, `Color(uiColor: .tertiaryLabel)`, `Color(uiColor: .quaternaryLabel)` |
+| Backgrounds | `Color(uiColor: .systemBackground)`, `.secondarySystemBackground`, `.tertiarySystemBackground` |
+| Grouped backgrounds | `Color(uiColor: .systemGroupedBackground)` and its secondary and tertiary levels |
+| Fills and separators | `Color(uiColor: .systemFill)` and its levels, `Color(uiColor: .separator)` |
+| Accent | `.tint(...)` once near the root; controls pick it up |
+| Destructive | `Button(role: .destructive)` rather than painting text red |
+
+- Do not redefine a semantic color's meaning (no `separator` as text color, no
+  `secondaryLabel` as a background).
+- Do not hard-code the documented system values; they change between releases.
+- Custom colors live in the asset catalog with light, dark and
+  increased-contrast variants.
+- Use one color for one meaning across the app; do not reuse the brand color
+  that marks interactive text for non-interactive text.
+- Never carry meaning with color alone: add a symbol or a word.
+
+## 6. Contrast minimums
+
+From the HIG accessibility page:
+
+| Text size | Weight | Minimum contrast ratio |
+|---|---|---|
+| Up to 17 pt | All | 4.5:1 |
+| 18 pt and up | All | 3:1 |
+| All | Bold | 3:1 |
+
+If the default palette cannot meet these, the app must at least provide a
+higher-contrast scheme when Increase Contrast is on
+(`colorSchemeContrast == .increased`). Check both light and dark appearances.
+
+## 7. Color on Liquid Glass
+
+Glass takes its color from the content behind it. Toolbars and tab bars keep
+symbols and text monochrome by default, flipping dark or light with what is
+underneath. Add color sparingly: for a primary action, tint the background of
+that one control (as prominent buttons do) rather than coloring symbols on many
+controls. Over colorful content, keep bar items monochrome or pick an accent
+that differs clearly from the content. Implementation is in
+`swiftui-liquid-glass`.
+
+## 8. Spacing and margins
+
+Start by leaving `spacing:` off stacks; the adaptive default follows the
+platform. When a value is chosen on purpose, a 4 point grid is a widespread
+design convention (Apple does not mandate one). Do not invent values between
+its stops, and prefer the project's spacing tokens when they exist.
+
+| Points | Typical use |
+|---|---|
+| 4 | Icon to label, inline badge offset |
+| 8 | Related items in one group |
+| 12 | Row inner padding, label to secondary text |
+| 16 | Standard margin, gap between sections |
+| 24 | Card inner padding, section separators |
+| 32 | Major groups, header to content |
+| 48 | Hero and onboarding layouts |
+
+- Use system margins (`.padding()` with no value, layout margins, readable
+  content guides) before fixed numbers.
+- Keep content inside the safe area; let only backgrounds bleed with
+  `.ignoresSafeArea()` or `.background(_:ignoresSafeAreaEdges:)`.
+- Pin persistent actions with `.safeAreaInset(edge: .bottom)`, or
+  `safeAreaBar` on iOS 26 when the bar should get the scroll edge effect.
+- `.contentMargins(_:_:for:)` (iOS 17) keeps reading width comfortable in
+  scroll views on iPad and in landscape.
+
+```swift
+ScrollView {
+    LazyVStack { ForEach(lines) { OrderLineRow(line: $0) } }
+}
+.contentMargins(.horizontal, 20, for: .scrollContent)
+.safeAreaInset(edge: .bottom) {
+    Button("Place order", action: placeOrder)
+        .buttonStyle(.borderedProminent)
+        .padding()
+}
+```
+
+## 9. Touch targets
+
+| Platform | Default | Minimum |
+|---|---|---|
+| iOS, iPadOS | 44 x 44 pt | 28 x 28 pt |
+| macOS | 28 x 28 pt | 20 x 20 pt |
+| visionOS | 60 x 60 pt | 28 x 28 pt |
+| watchOS | 44 x 44 pt | 28 x 28 pt |
+
+Spacing matters as much as size: about 12 points of padding around bezeled
+elements and about 24 around elements without a bezel. Grow the hit area of a
+small visual with `.contentShape(Rectangle())` and a frame rather than
+enlarging the glyph.
+
+Sources:
+[Typography](https://developer.apple.com/design/human-interface-guidelines/typography),
+[Accessibility](https://developer.apple.com/design/human-interface-guidelines/accessibility),
+[Color](https://developer.apple.com/design/human-interface-guidelines/color),
+[Layout](https://developer.apple.com/design/human-interface-guidelines/layout),
+[Font.custom(_:size:relativeTo:)](https://developer.apple.com/documentation/swiftui/font/custom(_:size:relativeto:)).

package/pipeline/skills/shared/external/hig-inputs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hig-inputs
-description: "Apple HIG for input mapped to SwiftUI: touch gestures, keyboards, pointer, Apple Pencil, focus and game controllers, Digital Crown, eyes and hands, haptics. Use when designing or reviewing input on an Apple platform."
+description: "Apple HIG for input mapped to SwiftUI: gestures, keyboards, pointer, Apple Pencil, focus, game controllers and Digital Crown. Use when designing or reviewing input on an Apple platform."
 metadata:
   risk: safe
   source: multi-agent-pipeline
@@ -116,9 +116,9 @@ Hardware keyboard (iPad, Mac, visionOS):
 
 ## Haptics and motion input
 
-- Use haptics to confirm meaningful events, not every tap:
-  `.sensoryFeedback(.selection, trigger: selectedSize)` in a picker,
-  `.success` when an order is placed.
+- Haptics (when to play them, `sensoryFeedback`, feedback generators, Core
+  Haptics) are covered in `ios-haptics`. As an input rule: haptics confirm
+  meaningful events, never replace a visible change.
 - Shake is reserved for undo; avoid other shake gestures.
 - Motion-based input (tilt) needs a non-motion alternative.
 
@@ -136,6 +136,7 @@ accessibilityAction(named: "Archive").
 - `hig-components-system` for menus, controls and text fields.
 - `swiftui-gestures` for gesture implementation detail.
 - `pencilkit-drawing` for Apple Pencil canvases.
+- `ios-haptics` for haptic feedback.
 
 ## References
 

package/pipeline/skills/shared/external/hig-patterns/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hig-patterns
-description: "Apple HIG interaction patterns mapped to SwiftUI: modality, loading, empty and error states, feedback, undo, search, data entry, settings, sharing, accounts. Use when designing a UX flow on an Apple platform."
+description: "Apple HIG interaction patterns mapped to SwiftUI: onboarding, permission requests, loading, empty and error states, modality, search, settings. Use when designing a UX flow on an Apple platform."
 metadata:
   risk: safe
   source: multi-agent-pipeline
@@ -29,7 +29,22 @@ Each maps to a pattern in `references/patterns.md`.
 
 ## Details on demand
 
-Load `references/patterns.md` for launch, loading, empty and error states, feedback, undo, search, data entry, settings, sharing, accounts and notifications.
+- `references/onboarding-and-states.md`: onboarding rules, TipKit versus an
+  up-front flow, when and how to ask for permission, the HIG rules for a
+  pre-permission screen (one button that opens the alert), and empty, error
+  and loading states with `ContentUnavailableView`.
+- `references/patterns.md`: feedback, undo, search, data entry, settings,
+  sharing, accounts and notifications.
+
+## First launch and access in one glance
+
+- Onboarding is optional, short and interactive; context tips beat a carousel.
+- Ask for access when the feature is first used, not at launch, unless the app
+  cannot work without it.
+- A pre-permission screen has one button ("Continue", never "Allow") that
+  opens the system alert, and no way around it.
+- Empty states say what would be here and offer the next step; errors say
+  what happened and offer Retry while keeping input.
 
 ## Choosing how to present a task
 
@@ -64,7 +79,8 @@ Expected: sheet with Cancel and Save; discard confirmation when edited.
 
 - `hig-components-content`, `hig-components-system` for the parts of each pattern.
 - `swiftui-navigation` for push, sheet and deep link implementation.
-- `tipkit` for in-context onboarding.
+- `tipkit` for in-context tips that replace up-front onboarding pages.
+- `ios-haptics` for confirming success or failure with haptics.
 
 ## References
 

package/pipeline/skills/shared/external/hig-patterns/references/onboarding-and-states.md

@@ -0,0 +1,188 @@
+# Onboarding, permission requests, empty and error states
+
+Companion to `../SKILL.md` for the `hig-patterns` skill. Guidance follows
+Apple's HIG pages on onboarding, launching, privacy and loading; the SwiftUI
+code is ours.
+
+## Contents
+
+1. [Onboarding](#1-onboarding)
+2. [Teaching in context with TipKit](#2-teaching-in-context-with-tipkit)
+3. [Asking for permission](#3-asking-for-permission)
+4. [Pre-permission screens](#4-pre-permission-screens)
+5. [Empty states](#5-empty-states)
+6. [Error states](#6-error-states)
+7. [Loading before the empty state](#7-loading-before-the-empty-state)
+
+## 1. Onboarding
+
+Ideally people understand the app by using it. When onboarding is needed:
+
+- It comes after launch is complete; it is not part of the launch screen.
+- Teach by doing: let people try the action safely rather than read about it.
+- Prefer several context-specific tips over one long up-front flow.
+- Keep any required flow brief; do not ask people to memorize steps.
+- Make a tutorial optional. If someone skips it, do not show it again on the
+  next launch, but keep it reachable from help, account or settings.
+- Teach the app, not the device or the system.
+- Postpone nonessential setup; ship defaults good enough to start right away.
+- Let people use the app before asking for ratings, purchases or an account
+  where possible.
+- A splash screen, if any, is brief; do not hold people on downloads, and
+  leave licensing text to the App Store page.
+
+Remember completion with `@AppStorage` and present the flow from the root, not
+from inside a feature screen:
+
+```swift
+struct RootView: View {
+    @AppStorage("onboarding.completed") private var onboardingCompleted = false
+
+    var body: some View {
+        let showsOnboarding = Binding(
+            get: { !onboardingCompleted },
+            set: { isPresented in onboardingCompleted = !isPresented }
+        )
+        MainTabs()
+            .fullScreenCover(isPresented: showsOnboarding) {
+                OnboardingFlow { onboardingCompleted = true }
+            }
+    }
+}
+```
+
+Every onboarding page has a visible way to skip or finish; the last page ends
+on the app's first useful screen.
+
+## 2. Teaching in context with TipKit
+
+For a feature people discover later (filters, a gesture, a new toolbar item),
+a TipKit tip shown next to the control beats an onboarding page. Rules,
+display frequency, invalidation and testing are in the `tipkit` skill.
+
+## 3. Asking for permission
+
+- Ask only for what the feature needs, and as late as possible: when the
+  person first uses the feature that depends on it.
+- Ask at launch only when the app cannot work without it (a navigation app and
+  location), where the reason is obvious.
+- If the app needs access before it can function at all, the request can be
+  part of onboarding, with a sentence on why and what the person gains.
+- The purpose string (usage description) is a short, complete, specific
+  sentence in sentence case, active voice, ending with a period:
+  "Your location is used to show nearby gates and walking times."
+- Prefer controls that avoid a prompt altogether when they fit: the location
+  button, the photos picker, contact and calendar pickers.
+- After a denial, keep the feature visible with an explanation and a link to
+  Settings; never re-prompt in a loop.
+
+## 4. Pre-permission screens
+
+A custom screen before the system alert is allowed when the context alone does
+not explain the request. HIG rules for it:
+
+- **Exactly one button, and it opens the system alert.** Title it "Continue"
+  or "Next", never "Allow", which mimics the alert's own button.
+- **No other actions**, such as Close, Cancel or "Not now", unless a legal
+  consent requires one. The screen must lead to the alert.
+- **No manipulation.** No incentives, no imitation of the alert, no image of
+  the alert, no annotations pointing at the alert's buttons. App Review
+  rejects these, and tracking requests are watched especially closely.
+
+```swift
+struct CameraPrimer: View {
+    let onContinue: () -> Void
+
+    var body: some View {
+        VStack(spacing: 24) {
+            Image(systemName: "camera.viewfinder")
+                .font(.system(.largeTitle))
+                .foregroundStyle(.tint)
+                .accessibilityHidden(true)
+            Text("Scan boarding passes")
+                .font(.title2.bold())
+            Text("The camera reads the barcode on a paper pass so you can add it to your trip.")
+                .font(.body)
+                .multilineTextAlignment(.center)
+                .foregroundStyle(.secondary)
+            Button("Continue", action: onContinue)
+                .buttonStyle(.borderedProminent)
+                .controlSize(.large)
+        }
+        .padding()
+    }
+}
+```
+
+`onContinue` triggers the real request, for example
+`AVCaptureDevice.requestAccess(for: .video)`.
+
+## 5. Empty states
+
+`ContentUnavailableView` (iOS 17) is the standard empty and error view. An
+empty state says what would appear here and offers the next step.
+
+```swift
+ContentUnavailableView {
+    Label("No trips yet", systemImage: "airplane")
+} description: {
+    Text("Trips you book or add with a confirmation code appear here.")
+} actions: {
+    Button("Add a trip") { isAddingTrip = true }
+        .buttonStyle(.borderedProminent)
+}
+```
+
+- For search with no results use `ContentUnavailableView.search` or
+  `ContentUnavailableView.search(text:)`, which word the message for you.
+- Distinguish first use (nothing created yet: invite creation), filtered to
+  nothing (offer to clear filters) and cleared by the person (a quiet
+  confirmation is enough).
+- Never hide a tab or section because it is empty; show the empty state in it.
+
+## 6. Error states
+
+- Say what happened in plain words and what the person can do: "Couldn't
+  refresh your trips. Check your connection and try again."
+- Offer Retry for transient failures, and keep everything the person entered.
+- Show errors in place, next to the content that failed; reserve alerts for
+  failures that block the task.
+- Keep blame out of the copy and avoid codes unless support needs them; when
+  they do, show them in a secondary line.
+
+```swift
+ContentUnavailableView {
+    Label("Couldn't load trips", systemImage: "wifi.exclamationmark")
+} description: {
+    Text("Check your connection and try again.")
+} actions: {
+    Button("Try Again") { Task { await reload() } }
+}
+```
+
+## 7. Loading before the empty state
+
+Order the states so the screen never flashes "empty" while loading:
+
+```swift
+switch state {
+case .loading:
+    TripsList(trips: Trip.placeholders)
+        .redacted(reason: .placeholder)
+case .loaded(let trips) where trips.isEmpty:
+    ContentUnavailableView("No trips yet", systemImage: "airplane")
+case .loaded(let trips):
+    TripsList(trips: trips)
+case .failed:
+    LoadErrorView(retry: reload)
+}
+```
+
+Placeholders keep the layout in place; a spinner suits short, global waits.
+Screen-level loading recipes are in `swiftui-ui-patterns`.
+
+Sources:
+[HIG: Onboarding](https://developer.apple.com/design/human-interface-guidelines/onboarding),
+[HIG: Privacy](https://developer.apple.com/design/human-interface-guidelines/privacy),
+[HIG: Loading](https://developer.apple.com/design/human-interface-guidelines/loading),
+[ContentUnavailableView](https://developer.apple.com/documentation/swiftui/contentunavailableview).

package/pipeline/skills/shared/external/hig-patterns/references/patterns.md

@@ -7,10 +7,8 @@ Companion to `../SKILL.md` for the `hig-patterns` skill.
 - Launch straight into useful content. The launch screen should look like the
   first frame of the app, not a splash advert.
 - Restore where the person left off (`@SceneStorage` for per-window state).
-- Keep onboarding optional and short. Teach in context instead, for example a
-  TipKit tip the first time someone opens the filters on a product list.
-- Ask for permissions at the moment they are needed, with a sentence of
-  context before the system prompt. Never ask for everything at launch.
+- Onboarding, permission timing and pre-permission screens:
+  [onboarding-and-states.md](onboarding-and-states.md).
 - Let people try the app before creating an account whenever possible.
 
 ## Waiting: loading and progress
@@ -25,17 +23,13 @@ Companion to `../SKILL.md` for the `hig-patterns` skill.
 
 ## Nothing to show, or something went wrong
 
-- Empty states explain what would appear and offer the next step:
-  `ContentUnavailableView("No notes yet", systemImage: "note.text", description: ...)`
-  with a button to create one.
-- For search with no results use `ContentUnavailableView.search(text:)`.
-- Errors say what happened in plain language and what to do. Offer retry for
-  transient failures; keep entered data intact.
+Empty, no-results and error states with `ContentUnavailableView`:
+[onboarding-and-states.md](onboarding-and-states.md).
 
 ## Feedback and confirmation
 
 - Confirm success quietly and in place: a checkmark symbol effect, an updated
-  row, a brief haptic (`.sensoryFeedback(.success, trigger:)`).
+  row, a brief haptic (see `ios-haptics`).
 - Reserve alerts for failures that block progress.
 - Make destructive actions recoverable (undo, trash) rather than piling on
   confirmation dialogs. Where there is no undo, confirm with a destructive-role