@mmerterden/multi-agent-pipeline 20.17.1 → 20.17.2

package/pipeline/skills/shared/external/ios-iphone-duo/references/api-map.md

@@ -0,0 +1,212 @@
+# iPhone Duo API map
+
+Every API this skill relies on, grouped by job, with the iOS version that
+introduced it. *(27.1 beta)* marks symbols documented as beta in the iOS 27.1
+SDK; their names and behaviour may change before release.
+
+## Contents
+
+1. Size, screen and shape
+2. Reserved regions
+3. Arrangements
+4. Vertical bars
+5. Sheets
+6. Hinge
+7. Scenes and accessories
+
+## 1. Size, screen and shape
+
+| Job | SwiftUI | UIKit | iOS |
+|---|---|---|---|
+| Size class | `horizontalSizeClass`, `verticalSizeClass` environment | trait collection size classes | 13 |
+| Space actually available | `GeometryReader`, `onGeometryChange(for:of:action:)` | `view.bounds`, `viewDidLayoutSubviews`, `layoutSubviews` | 13 / 16 |
+| Display scale | `displayScale` environment | `traitCollection.displayScale` | 13 / 8 |
+| A window for a scene | | `UIWindow(windowScene:)` | 13 |
+| The scene's screen, if truly needed | | `view.window?.windowScene?.screen` | 13 |
+| Choose among layouts | `ViewThatFits`, `AnyLayout` | | 16 |
+| Size relative to container | `containerRelativeFrame(_:alignment:)` | Auto Layout | 17 |
+| Corners concentric with the device | `ConcentricRectangle` | `UICornerConfiguration`, `UIView.cornerConfiguration` | 26 |
+
+`UIScreen.main` is deprecated as of iOS 26. Apple's guidance is to base layout
+on the scene or containing view's bounds and on size classes, and not to use
+`userInterfaceIdiom` or `UIInterfaceOrientation` for layout decisions.
+
+## 2. Reserved regions
+
+| Job | SwiftUI | UIKit |
+|---|---|---|
+| Region type | `ReservedRegion` *(27.1 beta)* | `UIView.ReservedRegion` *(27.1 beta)* |
+| Query | `GeometryProxy.reservedRegions(kind:options:layoutDirectionBehavior:)` *(27.1 beta)* | `UIView.reservedRegions(kind:options:)` *(27.1 beta)* |
+| Kinds | `.division` (fold), `.occlusion` (cameras) | same |
+| Options | `.includeInactive` | same |
+| Properties | `frame` (includes margins), `margins`, `isActive`, `kind`, `id` | `frame`, `margins`, `isActive`, `kind` (no `id`) |
+
+```swift
+struct FoldAwareGrid<Content: View>: View {
+    @ViewBuilder var content: (_ columns: Int) -> Content
+
+    var body: some View {
+        GeometryReader { proxy in
+            let hasFold = !proxy.reservedRegions(kind: .division, options: .includeInactive).isEmpty
+            let base = proxy.size.width > proxy.size.height ? 3 : 2
+            content(hasFold && base.isMultiple(of: 2) == false ? base + 1 : base)
+        }
+    }
+}
+```
+
+Notes:
+
+- The query returns regions that intersect the view whether active or not.
+  Filter `isActive` when positioning for the current pose.
+- `frame` already contains `margins`, the clearance kept for interactive
+  content. Avoiding `frame` is enough for controls; inset `frame` by
+  `margins` when full-bleed media may run up to the bare hardware area.
+- SwiftUI mirrors region frames for right-to-left by default
+  (`layoutDirectionBehavior: .mirrors`), so a custom `Layout` can compare them
+  with subview frames directly. Pass `.fixed` for the physical frames.
+- System containers (split views, lists, scroll views, sheets, alerts, menus)
+  already avoid reserved regions; custom views and custom layouts are the
+  ones that need this API.
+
+## 3. Arrangements
+
+| Job | SwiftUI | UIKit |
+|---|---|---|
+| Container | `ArrangementView(primary:secondary:)` *(27.1 beta)* | `UIArrangementViewController` *(27.1 beta)* |
+| Choose style | `.arrangementViewStyle(.split)` / `.overlay` / `.automatic` | `updateArrangement(_:animated:)` with `UISplitArrangement` / `UIOverlayArrangement` |
+| Limit axes | `.split.axes(.vertical)`, `.overlay.axes(...)` | `axes(_:)` on the arrangement |
+| Assign content | the two view builders | `setViewController(_:for:animated:)` with `.primary` / `.secondary` |
+| Split sizing | `splitArrangementLayoutRatio(_:)`, `splitArrangementLayoutSize(...)`, `splitArrangementFixedLayoutSize(...)` | `UISplitArrangement.Dimension` |
+| Overlay details | `overlayArrangementEdge(_:)`, `overlayArrangementZIndex` environment | `state(for:)` |
+
+```swift
+ArrangementView {
+    NowPlayingView()
+} secondary: {
+    LyricsView()
+}
+.arrangementViewStyle(.split)
+
+ArrangementView {
+    PlayerControls()
+} secondary: {
+    VideoSurface()
+}
+.arrangementViewStyle(.overlay)
+```
+
+The automatic style resolves to split. Split goes side by side when wider than
+tall and stacks when taller than wide; overlay layers primary over secondary
+when closed or fully open and places them on either side of the fold when
+partially open (primary trailing or bottom, secondary leading or top).
+
+Placement rules: navigation containers go around an arrangement, never inside
+it; an arrangement does not go inside `NavigationSplitView`, `List`,
+`ScrollView` or another container that could make part of it unreachable.
+
+## 4. Vertical bars
+
+| Job | SwiftUI | UIKit | iOS |
+|---|---|---|---|
+| Bars that can go vertical | `.toolbar` on `NavigationStack` / `NavigationSplitView` | items on a view controller in a navigation controller | |
+| Custom Back or Close | `ToolbarItem(placement: .cancellationAction)` | `leadingItemGroups` | 14 / 16 |
+| Prominent action | `topBarPinnedTrailing` | `pinnedTrailingGroup` | 27 / 16 |
+| Group items | `ToolbarItemGroup` | `UIBarButtonItemGroup` | 14 |
+| Title plus symbol | `Label` | `UIBarButtonItem` title and image | |
+| Overflow order | `visibilityPriority(_:)`, `ToolbarItemVisibilityPriority` (`.automatic`, `.low`, `.high`, `init(higherThan:)`, `init(lowerThan:)`) | `visibilityPriority`, `UIBarButtonItemVisibilityPriority` | 27 |
+| Put items in overflow | `ToolbarOverflowMenu` | `additionalOverflowItems` | 27 / 16 |
+| Keep an item horizontal | `axisBehavior(_:)` with `ToolbarItemAxisBehavior` (`.automatic`, `.horizontalOnly`, `.verticalPreferred`) | `axisBehavior`, `UIBarButtonItem.AxisBehavior` | *(27.1 beta)* |
+| Tab bar versus toolbar when tight | `toolbarVerticalCompressionBehavior(_:)` (`.automatic`, `.prefersTabBar`, `.prefersToolbarItems`) | `UIVerticalBarCompressionBehavior` | *(27.1 beta)* |
+| Opt a screen out | `toolbarVerticalBehavior(.disabled)` | `preferredVerticalBarBehavior`, `setNeedsUpdateOfVerticalBarConfiguration()` | *(27.1 beta)* |
+| Which edge the bar prefers | `toolbarVerticalEdge` environment (`HorizontalEdge?`) | `verticalBarEdge` trait (`UIVerticalBarEdge`) | *(27.1 beta)* |
+| Image under the bar | `backgroundExtensionEffect()` | `UIBackgroundExtensionView` | 26 |
+
+```swift
+NavigationStack {
+    EditorView()
+        .toolbar {
+            ToolbarItem(placement: .cancellationAction) {
+                Button("Close", systemImage: "xmark") { dismiss() }
+            }
+            ToolbarItem(placement: .topBarPinnedTrailing) {
+                Button("Done", systemImage: "checkmark") { save() }
+            }
+            ToolbarItemGroup {
+                Button("Bold", systemImage: "bold") { toggleBold() }
+                Button("Italic", systemImage: "italic") { toggleItalic() }
+            }
+            .visibilityPriority(.low)
+        }
+}
+```
+
+How items are shown: vertically with their icon; horizontally with icon or
+title (icon preferred); in overflow with both. An item with only a title or a
+custom view is never placed vertically.
+
+Contexts that choose differently: inspectors keep horizontal bars; a split
+view uses horizontal bars for sidebar and content columns and vertical bars
+for the detail column; sheets on the outer display go vertical by default.
+
+`toolbarVerticalBehavior` is resolved per container: the top view of a
+`NavigationStack`, the selected tab of a `TabView`, the trailing column of a
+`NavigationSplitView`. To hide bars rather than change their axis, use
+`toolbarVisibility(_:for:)`.
+
+`toolbarVerticalEdge` reports the preferred edge even when no vertical bar is
+currently visible, and nil where the system never uses one:
+
+```swift
+@Environment(\.toolbarVerticalEdge) private var barEdge
+
+FloatingPalette()
+    .frame(maxWidth: .infinity, alignment: barEdge == .leading ? .leading : .trailing)
+```
+
+## 5. Sheets
+
+On the inner display, sheets use horizontal toolbars when centred or leading
+and vertical ones when trailing. Choose placement with
+`presentationPlacement(_:)` (iOS 27) or `UISheetPresentationController.preferredPlacement`
+(iOS 27). On the outer display, a sheet with a single action can opt out of the
+vertical bar with `toolbarVerticalBehavior(.disabled)`.
+
+## 6. Hinge
+
+| | SwiftUI *(27.1 beta)* | UIKit *(27.1 beta)* |
+|---|---|---|
+| Observe | `onHingeChange(isEnabled:_:)`, old and new `DeviceHingeContext` | `UIHingeInteraction(updateHandler:)`, `(interaction, update)` |
+| Hinge value | `DeviceHingeContext.hinge: DeviceHinge?` | `Update.hinge: UIHinge?` |
+| Angle | `angle: Angle` | `angle: CGFloat`, radians |
+| Status | `DeviceHinge.Status` struct: `.closed`, `.partiallyOpen`, `.fullyOpen` | `UIHinge.Status` enum: same plus `.unknown` |
+
+```swift
+@State private var hingeStatus: DeviceHinge.Status?
+
+var body: some View {
+    Canvas3DView(tilted: hingeStatus == .partiallyOpen)
+        .onHingeChange { _, new in
+            hingeStatus = new.hinge?.status
+        }
+}
+```
+
+- `hinge` is nil where there is no hinge; treat that as the normal phone case.
+- The UIKit handler runs with the initial state, on changes, and when the
+  interaction moves between hierarchies. It escapes, so capture weakly.
+- Status comes from angle and orientation together; do not rebuild it from
+  angle thresholds. Update rate and precision are system policy.
+- Use the hinge for interactions and effects. Layout belongs to reserved
+  regions, arrangements and size classes.
+
+## 7. Scenes and accessories
+
+- `sceneAccessory(content:)` (iOS 27) and UIKit's scene accessory
+  registration (`registerSceneAccessory(_:)`) attach content to another
+  display, for example a camera capture accessory on the outer display while
+  the app runs on the inner one. See Apple's article on registering a camera
+  capture accessory on iPhone Duo.
+- New windows depend on what the current display allows. Prefer
+  `UIWindowScene.ActivationAction` for "open in new window" menu items, and
+  handle a failed scene request instead of assuming success.

package/pipeline/skills/shared/external/ios-iphone-duo/references/fixed-assumptions.md

@@ -0,0 +1,145 @@
+# Fixed assumptions: grep list and replacements
+
+Run these from the repository root. Every hit is a candidate, not a verdict:
+read the surrounding code, decide whether it affects layout, and confirm on
+the iPhone Duo simulator. Exclude vendored and generated code from the count.
+
+## Contents
+
+1. The search
+2. Orientation
+3. The screen
+4. Cached sizes
+5. Idiom and size class
+6. Device sizes and thresholds
+7. Insets
+8. Bars
+9. Media
+10. Recording the result
+
+## 1. The search
+
+```bash
+rg -n --type swift \
+  -e 'UIScreen\.main' \
+  -e 'UIScreen\.screens' \
+  -e 'UIDevice\.current\.orientation' \
+  -e 'interfaceOrientation' \
+  -e 'statusBarOrientation' \
+  -e 'userInterfaceIdiom' \
+  -e 'horizontalSizeClass\s*==\s*\.regular' \
+  -e 'UIWindow\(frame:' \
+  -e 'safeAreaInsets\.(left|right|top|bottom)\s*\*\s*2' \
+  -e '(width|height)\s*(==|>=|<=|>|<)\s*(320|375|390|393|402|414|428|430|440)\b' \
+  -e 'UIToolbar\(|UINavigationBar\(|UITabBar\(' \
+  -e 'scaleAspectFill|contentMode:\s*\.fill' \
+  .
+```
+
+Add Objective-C (`--type objc`) and storyboards (`-g '*.storyboard'` for
+fixed-size constraints) when the project has them.
+
+## 2. Orientation
+
+Hits: `UIDevice.current.orientation`, `interfaceOrientation` (including
+`windowScene.effectiveGeometry.interfaceOrientation`), `statusBarOrientation`.
+
+Why: on a foldable device orientation no longer says whether the app is wide
+or tall, and Apple's guidance is not to use `UIInterfaceOrientation` for
+layout decisions.
+
+Replace: compare the width and height of the space you have, `view.bounds` in
+a view controller, `bounds` of the superview in a view, the size from
+`GeometryReader` or `onGeometryChange` in SwiftUI. Keep orientation only for
+things that are about the device's physical attitude (camera capture
+rotation), not about layout.
+
+## 3. The screen
+
+Hits: `UIScreen.main` (deprecated in iOS 26), `UIScreen.screens`,
+`UIWindow(frame: UIScreen.main.bounds)`.
+
+| Instead of | Use |
+|---|---|
+| `UIScreen.main.bounds` | `view.bounds`, `window.bounds`, `GeometryReader`, `onGeometryChange` |
+| `UIScreen.main.scale` | `traitCollection.displayScale`, `@Environment(\.displayScale)` |
+| `UIWindow(frame: UIScreen.main.bounds)` | `UIWindow(windowScene:)` |
+| A stored `UIScreen` | `view.window?.windowScene?.screen`, read when needed |
+
+## 4. Cached sizes
+
+Hard to grep; look for sizes stored in properties at `viewDidLoad`,
+`viewIsAppearing`, `init`, `onAppear`, or a `GeometryReader` value copied into
+`@State` once.
+
+Why: folding and unfolding resizes the app during a session. A size read at
+launch is wrong after the first fold.
+
+Replace: do size-dependent layout in `viewDidLayoutSubviews` or
+`layoutSubviews`; use `viewWillTransition(to:with:)` for work tied to the
+change itself; in SwiftUI derive layout from the current geometry every time,
+or keep it current with `onGeometryChange`.
+
+## 5. Idiom and size class
+
+Hits: `userInterfaceIdiom == .pad`, `horizontalSizeClass == .regular` used to
+mean "iPad", and code that assumes iPhone is always compact.
+
+Why: the inner display is regular width on an iPhone. An iPad-only layout
+branch now runs on a phone, and a "phone means compact" branch never expects
+regular.
+
+Replace: branch on size class and available space only. Check both
+directions: code that fires on regular, and code that assumes compact.
+
+## 6. Device sizes and thresholds
+
+Hits: comparisons with known iPhone widths or heights, device lookup tables,
+"if width > 390" breakpoints.
+
+Why: no table contains this device, and Split View produces sizes no device
+has.
+
+Replace: size classes (compact for the outer display, regular for the inner),
+`ViewThatFits`, `containerRelativeFrame`, proportional and intrinsic sizing.
+
+## 7. Insets
+
+Hits: `safeAreaInsets.left * 2`, `width - 2 * inset`, `insets.left` used for
+both sides, padding that mirrors one edge onto the other.
+
+Why: side-mounted bars make safe areas and layout margins asymmetric, and the
+heavy side depends on pose and Split View position.
+
+Replace: inset each edge by its own value, or constrain to the safe area
+layout guide and layout margins and let the system resolve each edge.
+
+## 8. Bars
+
+Hits: `UIToolbar(`, `UINavigationBar(`, `UITabBar(` created by hand, or a
+SwiftUI `HStack` styled as a bar pinned to the top or bottom.
+
+Why: only bars provided by navigation containers take part in vertical
+placement. A custom bar stays where it is and collides with the system's
+vertical controls.
+
+Replace: toolbar items on `NavigationStack` / `NavigationSplitView` with
+`.toolbar`, or on a view controller inside a navigation controller; `TabView`
+or `UITabBarController` for tabs.
+
+## 9. Media
+
+Hits: `scaleAspectFill`, `.aspectRatio(contentMode: .fill)` on hero images
+and video.
+
+Why: wider displays crop more of the image and can lose the subject.
+
+Replace: choose fill or fit from the current size or aspect ratio, crop around
+a focal point, and extend backgrounds under bars with
+`backgroundExtensionEffect()` rather than stretching the image.
+
+## 10. Recording the result
+
+For each hit, record `file:line`, the category, keep or fix, and for fixes the
+replacement. Separate "confirmed on the simulator" from "found in code only".
+Pose-dependent behaviour is not proven until it has been seen running.

package/pipeline/skills/shared/external/ios-iphone-duo/references/poses-and-panes.md

@@ -0,0 +1,122 @@
+# Poses, panes and the design review
+
+Design guidance for iPhone Duo. The rules marked HIG come from Apple's
+Designing for iPhone Duo page; the pattern table is a recommendation built on
+those rules and on size classes, and should be adapted to the app's content.
+
+## Contents
+
+1. Poses
+2. Pose to pattern
+3. Using the inner display
+4. Dual-pane rules
+5. Controls on the side
+6. The fold
+7. Review checklist
+
+## 1. Poses
+
+People hold and set down iPhone Duo in several ways (HIG): closed, using the
+outer display; open flat on the inner display; partially folded like a book;
+placed on a surface; standing on its edges. Every pose can also be rotated,
+and Split View can put two apps side by side on the inner display.
+
+Supporting poses does not mean a custom layout per pose (HIG). A compact
+width layout for the outer display and a regular width layout for the inner
+display cover the fundamentals; the existing layout expands into the space.
+
+## 2. Pose to pattern
+
+| Pose | Size class | What usually works |
+|---|---|---|
+| Closed, outer display | compact width | The phone layout. Bars on the side free vertical space; content offset from the bar side |
+| Open, inner display, landscape | regular width | One more level of hierarchy: list and detail side by side, or content reflowed into columns. Bars stay on the side |
+| Open, inner display, portrait | regular width | Same hierarchy as landscape; horizontal bars return because vertical space is plentiful |
+| Partially folded (book) | regular width | A split that rebalances around the fold; even column counts in grids; nothing tappable in the curve |
+| On a surface, partly folded | regular width | Viewing on the upper part, touch on the lower, stable part; suits media and hands-free use |
+| Standing on edges | depends on orientation | Glanceable, hands-free content with few controls |
+| Split View | either, per half | Each app keeps its controls on its outer edge; the app must work at half width |
+
+The on-surface layout is optional and still has to offer every control the
+other poses offer.
+
+## 3. Using the inner display
+
+A stretched phone layout is the failure to avoid. Options, in rough order of
+cost:
+
+- **Split view**: `NavigationSplitView` shows list and detail together when
+  open and collapses to a stack when closed. The hierarchy is the same; the
+  inner display shows one more level of it (HIG). Mail shows the list or a
+  message when closed and both side by side when open.
+- **Reflow**: a single column becomes two columns when width allows
+  (`ViewThatFits`, `AnyLayout`, adaptive grids).
+- **Arrangement**: two related views (now playing and lyrics, controls and
+  video) in an `ArrangementView` that adapts to the fold.
+- **Sidebar tabs**: a sidebar-adaptable tab view for information-dense apps.
+
+## 4. Dual-pane rules
+
+- Same functions and state on both displays (HIG). Opening or closing the
+  device mid-task must not lose a selection, a scroll position or a draft.
+- Never tie a function to a pose (HIG). Everything reachable in one pose is
+  reachable in all of them, even if it moves into overflow.
+- The secondary pane depends on the primary: selecting in the list drives the
+  detail. When the device closes, the detail the person was reading should be
+  what they see, not the list.
+- Keep controls with the content they act on (HIG). Actions for the list sit
+  above the list pane, not in the side bar beside the detail.
+- Each pane keeps its own safe area and margins; do not let one pane's insets
+  bleed into the other.
+- Prefer containers that rebalance themselves around the fold over manual
+  positioning (HIG), and in grids prefer an even number of columns so content
+  divides cleanly.
+
+## 5. Controls on the side
+
+- Follow the system's vertical placement and do not override it without a
+  strong reason (HIG); it is one of the device's core patterns.
+- Top of the vertical axis: Back or Close, then prominent actions such as
+  Done; remaining items keep their original groupings (HIG).
+- Give every item a symbol and a title; keep text-only buttons to a minimum,
+  because text items stay in a horizontal bar (HIG).
+- Assign visibility priority so frequent actions and items with badges stay
+  visible longest (HIG).
+- Use the system overflow menu instead of a custom one; reserve the ellipsis
+  for overflow (HIG).
+- Content next to side controls is asymmetric. Offset content by the safe
+  area by default; centre on the full display only for immersive,
+  non-scrolling screens with nothing interactive under the controls; or let a
+  background span the full width while the scrollable, interactive content
+  stays inset (HIG).
+
+## 6. The fold
+
+- Keep interactive elements out of the folding region (HIG). System controls
+  are moved aside automatically; custom ones use reserved regions.
+- Move as little as possible as the device folds (HIG). Small adjustments
+  that keep elements visible beat controls that vanish or jump.
+- Scrolling content may pass through the fold; fixed text and controls
+  should not rest in it.
+
+## 7. Review checklist
+
+Use with `ios-design-review` for the general visual pass.
+
+1. Is anything interactive in the fold or under the side controls?
+2. Is any function or piece of state available in one pose but not another?
+3. Does state survive opening, closing and folding mid-task?
+4. Are there fixed widths or device breakpoints instead of size classes?
+5. Do toolbar items have symbols and titles, sensible priorities, and does the
+   overflow hold the right things?
+6. Does the inner display do better than stretching (split, reflow,
+   arrangement)?
+7. Is content offset from the side controls, deliberately centred, or mixed
+   with every control inside the inset area?
+8. Does the screen hold up in Split View on both sides, at half width?
+9. Do custom components reimplement fold avoidance the system components
+   would have provided?
+10. Are controls next to the content they affect?
+11. Do grids divide evenly around the fold?
+12. Which of the above were seen on the simulator, and which only reasoned
+    from design files or code?

package/pipeline/skills/shared/external/ios-sf-symbols/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: ios-sf-symbols
+description: "SF Symbols in SwiftUI and UIKit: rendering modes, variable values, symbol effects including Draw On and Off, matching weight and scale to text, custom symbols and accessibility labels. Use when picking, styling, animating or reviewing symbols, or building a custom symbol."
+metadata:
+  source: multi-agent-pipeline
+  date_added: "2026-10-08"
+---
+
+# SF Symbols
+
+SF Symbols are vector glyphs drawn to sit with San Francisco text: nine
+weights and three scales that line up with the font, layers that take colour,
+and built-in animations. Using them well is mostly about letting them follow
+the text and the container instead of sizing them by hand.
+
+## Versions and availability
+
+Symbols and symbol features introduced in a given year are not available on
+earlier systems, so check both the symbol's availability in the SF Symbols app
+and the API's introduction version.
+
+| Capability | API | iOS |
+|---|---|---|
+| Rendering modes | `symbolRenderingMode(_:)`, `SymbolRenderingMode` | 15 |
+| Variants | `symbolVariant(_:)`, `SymbolVariants` | 15 |
+| Variable value | `Image(systemName:variableValue:)` | 16 |
+| Symbol effects | `symbolEffect(_:options:value:)`, `symbolEffect(_:options:isActive:)`, `contentTransition(.symbolEffect(...))` | 17 |
+| Wiggle, Rotate, Breathe | `WiggleSymbolEffect`, `RotateSymbolEffect`, `BreatheSymbolEffect` | 18 |
+| Draw On, Draw Off | `DrawOnSymbolEffect`, `DrawOffSymbolEffect` (`.drawOn`, `.drawOff`) | 26 |
+| Variable Draw | `symbolVariableValueMode(_:)` with `.draw` | 26 |
+| Gradient rendering | `symbolColorRenderingMode(_:)` with `.gradient` | 26 |
+
+SF Symbols 7 introduced Draw, Variable Draw and gradients. The current SF
+Symbols app (27 releases) adds semantic search and new symbols. Check
+developer.apple.com/sf-symbols for the current app before relying on a symbol
+that may be new.
+
+## Sizing with text
+
+Symbols take their size and weight from the font, which is what keeps them
+aligned and scaling with Dynamic Type.
+
+```swift
+Label("Downloads", systemImage: "arrow.down.circle")
+    .font(.headline)
+
+Image(systemName: "bell")
+    .font(.body)
+    .imageScale(.large)
+```
+
+- Set size with `.font(...)` and a text style, not `.resizable().frame(...)`.
+  A resized image stops scaling with Dynamic Type and loses weight matching.
+- Use `imageScale(_:)` (small, medium, large) to change emphasis relative to
+  the text without breaking the weight match.
+- Match weight to adjacent text (`.fontWeight(.semibold)` on both).
+- In UIKit, `UIImage.SymbolConfiguration(textStyle:)` or
+  `init(font:scale:)` does the same job.
+
+## Rendering modes
+
+| Mode | What it does | Good for |
+|---|---|---|
+| Monochrome | One colour for every layer | Toolbars, lists, most UI |
+| Hierarchical | One colour, layers at decreasing opacity | Depth without extra colours |
+| Palette | One explicit colour per layer | Brand or status colour pairs |
+| Multicolor | The symbol's intrinsic colours | Weather, files, recognisable objects |
+
+```swift
+Image(systemName: "cloud.sun.rain.fill")
+    .symbolRenderingMode(.hierarchical)
+    .foregroundStyle(.tint)
+
+Image(systemName: "person.crop.circle.badge.checkmark")
+    .symbolRenderingMode(.palette)
+    .foregroundStyle(.green, .secondary)
+```
+
+Gradient rendering (iOS 26) adds a light linear gradient from a single colour
+in any mode: `.symbolColorRenderingMode(.gradient)`. It looks best at larger
+sizes. Prefer system colours in every mode so symbols adapt to dark mode,
+vibrancy and Increase Contrast. Check the automatic choice at small sizes and
+on busy backgrounds, where a different mode may read better.
+
+## Variants
+
+Outline is the default and sits best next to text. Fill gives emphasis and is
+what tab bars prefer; slash marks something unavailable; enclosed shapes help
+legibility at small sizes. Containers often pick the variant (a tab bar
+chooses fill), so set `symbolVariant(_:)` only when the context does not.
+
+## Variable values
+
+A variable value (0 to 1) shows a level: signal, volume, progress.
+
+```swift
+Image(systemName: "wifi", variableValue: strength)
+
+Image(systemName: "thermometer.high", variableValue: level)
+    .symbolVariableValueMode(.draw)
+```
+
+Variable Color changes layer opacity at thresholds; Variable Draw (iOS 26)
+draws the path to the value, which reads more precisely. Use variable values
+to show change, not depth; hierarchical rendering is for depth.
+
+## Effects
+
+Effects tell people that something happened or is happening. Each has a
+meaning; pick by meaning, not by look.
+
+| Effect | Use | Trigger |
+|---|---|---|
+| Bounce | An action happened | `value:` changes |
+| Pulse, Breathe | Ongoing activity | `isActive:` |
+| Variable Color | Progress or connecting | `isActive:` |
+| Wiggle | Draw attention to something easy to miss | `value:` |
+| Rotate | Work in progress, rotating parts | `isActive:` |
+| Scale | Persistent emphasis on a selection | `isActive:` |
+| Appear, Disappear | Show or hide a symbol | `isActive:` or transition |
+| Draw On, Draw Off | Draw in or out along the path (iOS 26) | `isActive:` or transition |
+| Replace, Magic Replace (18) | Swap one symbol for a related one | `contentTransition` |
+
+```swift
+Image(systemName: "bell")
+    .symbolEffect(.bounce, value: unreadCount)
+
+Image(systemName: isMuted ? "speaker.slash" : "speaker.wave.2")
+    .contentTransition(.symbolEffect(.replace))
+
+Image(systemName: "checkmark.circle")
+    .symbolEffect(.drawOff.byLayer, isActive: !isSaved)
+```
+
+Use effects sparingly; several animated symbols on one screen compete. Repeat
+indefinitely only while the condition holds. Respect Reduce Motion: read
+`accessibilityReduceMotion` and drop decorative repeating effects when it is
+on, keeping the state change itself visible. Full effect options and the
+UIKit equivalents are in `references/effects-and-custom-symbols.md`.
+
+## Custom symbols
+
+When no system symbol fits, build one from the SF Symbols template rather than
+drawing an icon from scratch, so it gets weights, scales, rendering modes and
+animations. In short: export the closest system symbol's template from the SF
+Symbols app, edit it in a vector tool, import it back, annotate layers (and
+Draw guide points if it animates), test every effect, export, and add it to an
+asset catalog as a symbol image. Load it with `Image("name")` or
+`UIImage(named:)`. The full process is in the reference.
+
+Symbols that depict Apple products or features cannot be customised; the SF
+Symbols app marks them with an Info badge.
+
+## Accessibility
+
+- Icon-only controls need a label. `Label("Share", systemImage: ...)` gives
+  VoiceOver and overflow menus a title even when only the icon shows.
+- Use `.accessibilityLabel(...)` when the label must differ from visible text,
+  and hide purely decorative symbols with `.accessibilityHidden(true)`.
+- Custom symbols need an accessibility description; VoiceOver cannot infer one.
+- Directional symbols have right-to-left variants; custom symbols need their
+  directionality set when exported.
+
+## Not in app icons
+
+The SF Symbols licence prohibits using symbols, or confusingly similar images,
+in app icons, logos or any trademarked use. Draw the icon's artwork
+separately; see `hig-app-icons`.
+
+## References
+
+- `references/effects-and-custom-symbols.md`: effect options, UIKit API, custom symbol workflow, review checklist.
+- HIG SF Symbols: https://developer.apple.com/design/human-interface-guidelines/sf-symbols
+- SF Symbols app: https://developer.apple.com/sf-symbols/
+- Symbols framework: https://developer.apple.com/documentation/symbols
+- Configuring and displaying symbol images: https://developer.apple.com/documentation/uikit/configuring-and-displaying-symbol-images-in-your-ui
+- Creating custom symbols: https://developer.apple.com/documentation/technologyoverviews/custom-sf-symbols