@mmerterden/multi-agent-pipeline 20.2.1 → 20.3.1

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

@@ -1,81 +1,78 @@
 ---
 name: hig-components-content
-description: "Apple Human Interface Guidelines for content display components. Use when designing or reviewing how content is displayed on an Apple platform."
-risk: unknown
-source: community
-date_added: '2026-02-27'
+description: "Apple HIG for content views mapped to SwiftUI: lists, tables, grids, charts, images, text, web views, empty states. Use when choosing or reviewing how an Apple-platform app presents content."
+metadata:
+  risk: safe
+  source: multi-agent-pipeline
+  date_added: "2026-09-25"
 ---
 
-# Apple HIG: Content Components
+# HIG: Content Views
 
-Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.
+Content views are the part of a screen people came for. The container around
+them (split view, tab bar, sheet) is covered by `hig-components-layout`; this
+skill picks the view that holds the data and checks it behaves the way the
+platform trains people to expect.
 
-## Key Principles
+## Start from the shape of the data
 
-1. **Adapt to different sizes and contexts.** Content components must work across screen sizes, orientations, and multitasking configurations. Use Auto Layout and size classes.
+Pick the view from the data, not from a mockup. The same product catalogue can
+be a list, a grid or a table depending on what the reader compares.
 
-2. **Make content accessible.** Charts need audio graph support. Images need alt text. Collections need proper VoiceOver navigation order. All content components need labels and descriptions.
-
-3. **Maintain visual hierarchy.** Use spacing, sizing, and grouping to establish clear information hierarchy. Primary content should be visually prominent.
-
-4. **Use system components first.** Evaluate UICollectionView, SwiftUI Charts, WKWebView before building custom. System components come with built-in accessibility and platform adaptation.
-
-5. **Respect platform conventions.** A collection on tvOS uses large lockups with parallax. The same collection on iOS uses compact cells with touch targets. On visionOS, content gains depth and hover effects.
-
-6. **Handle empty states.** Show a meaningful empty state with guidance on how to populate it, not a blank screen.
-
-7. **Optimize for performance.** Use lazy loading, cell reuse, pagination, and prefetching for large datasets.
-
-## Topics
-
-| Topic | Key content |
-|---|---|
-| Charts | Swift Charts, bar/line/area/point marks, chart accessibility, audio graphs |
-| Collections | Grid/list layouts, compositional layout, selection, reordering, diffable data sources |
-| Image Views | Aspect ratio handling, content modes, SF Symbol images, accessibility |
-| Image Wells | Drag-and-drop image selection, macOS-specific, placeholder content |
-| Color Wells | Color selection UI, system color picker, custom color spaces |
-| Web Views | WKWebView, SFSafariViewController, navigation controls, content restrictions |
-| Activity Views | Share sheets, activity items, custom activities, action extensions |
-| Lockups | Image+text elements, tvOS card layouts, focus effects, shelf layouts |
-
-## Component Selection Guide
-
-| Content Need | Recommended Component | Platform Notes |
+| The reader needs to... | Reach for | SwiftUI |
 |---|---|---|
-| Visualizing quantitative data | Charts (Swift Charts) | iOS 16+, macOS 13+, watchOS 9+ |
-| Browsing a grid or list of items | Collection View | Compositional layout for complex arrangements |
-| Displaying a single image | Image View | Support aspect ratio fitting; provide accessibility description |
-| Selecting an image via drag or browse | Image Well | macOS primarily; use image pickers on iOS |
-| Selecting a color | Color Well | Triggers system color picker; macOS, iOS 14+ |
-| Showing web content inline | Web View (WKWebView) | Use SFSafariViewController for external browsing |
-| Sharing content to other apps | Activity View | System share sheet with configurable activity types |
-| Content card (image + text) | Lockup | Primarily tvOS; adaptable to other platforms |
-
-## Output Format
-
-1. **Component recommendation with rationale**, referencing the relevant HIG topic.
-2. **Configuration guidance** -- key properties and setup.
-3. **Accessibility requirements** for the recommended component.
-4. **Platform-specific notes** for targeted platforms.
-
-## Questions to Ask
-
-1. What type of content? (Quantitative data, images, web content, browsable collection, share action?)
-2. Which platforms?
-3. Static or dynamic content?
-4. How much content? (Few items vs hundreds/thousands affects component choice and optimization.)
-
-## Related Skills
-
-- **hig-foundations** -- Color, typography, accessibility, and image guidelines
-- **hig-patterns** -- Data visualization, sharing, and loading patterns
-- **hig-components-layout** -- Structural containers (scroll views, lists, split views) hosting content
-- **hig-platforms** -- Platform-specific component behavior (lockups on tvOS, web views on macOS)
-
----
-
-*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.
+| Scan rows of mostly text and act on one | List | `List`, `Section`, `.listStyle(.insetGrouped)` |
+| Compare several attributes across many rows | Table (iPad, Mac) | `Table` with `TableColumn`, `sortOrder:` binding |
+| Browse items where the picture carries the meaning | Grid / collection | `LazyVGrid`, `LazyHGrid`, `Grid` for small fixed layouts |
+| See a trend, distribution or proportion | Chart | Swift Charts: `Chart`, `BarMark`, `LineMark`, `SectorMark` |
+| Read or edit longer prose | Text view | `Text`, `TextEditor`, `TextField(axis: .vertical)` |
+| Look at one image closely | Image view | `Image`, `AsyncImage`, zoom via gesture or `ScrollView` |
+| Show web content the app does not own | Web view | `WebView` / `WebPage` (iOS 26), `SFSafariViewController` for external links |
+| Send the current thing elsewhere | Share sheet | `ShareLink` with a `Transferable` item |
+| Nothing to show yet | Empty state | `ContentUnavailableView` |
+
+A table collapses to its first column in compact width. Put the identifying
+value (the order number, the product name) in that column and let the rest
+reappear when there is room.
+
+## Details on demand
+
+Load `references/content-views.md` for per-view rules and SwiftUI examples for lists, tables, grids, charts, images, text, web content and sharing.
+
+## Empty, loading and error states
+
+- Use `ContentUnavailableView` for "no notes yet" and
+  `ContentUnavailableView.search` for "no results", with an action button when
+  there is an obvious next step.
+- While loading, show placeholder rows with `.redacted(reason: .placeholder)`
+  rather than a blank screen; progress guidance is in `hig-components-status`.
+- An error state explains what happened and what to do, in plain language,
+  and keeps whatever content was already on screen.
+
+## Review checklist
+
+1. Does the chosen view match what the reader compares or scans?
+2. Does every swipe or gesture action also exist in a visible place?
+3. Do lists and grids use system selection, refresh and context menus?
+4. Does every chart say its conclusion and work without colour?
+5. Do images carry labels, keep their aspect ratio while loading, and zoom?
+6. Does text use text styles and scale to the largest accessibility sizes?
+7. Are external links handed to Safari instead of an embedded browser?
+8. Is there a designed empty state, loading state and error state?
+
+## Related skills
+
+- `hig-components-layout` for the container: split views, tabs, sheets.
+- `hig-components-status` for progress, gauges and loading feedback.
+- `hig-foundations` for colour, typography, SF Symbols and accessibility.
+- `swift-charts` and `swiftui-webkit` for implementation detail.
+
+## References
+
+- https://developer.apple.com/design/human-interface-guidelines/lists-and-tables
+- https://developer.apple.com/design/human-interface-guidelines/collections
+- https://developer.apple.com/design/human-interface-guidelines/charts
+- https://developer.apple.com/design/human-interface-guidelines/image-views
+- https://developer.apple.com/design/human-interface-guidelines/text-views
+- https://developer.apple.com/design/human-interface-guidelines/web-views
+- https://developer.apple.com/design/human-interface-guidelines/activity-views

package/pipeline/skills/shared/external/hig-components-content/references/content-views.md

@@ -0,0 +1,111 @@
+# Content views in detail
+
+Companion to `../SKILL.md` for the `hig-components-content` skill.
+
+## Lists and tables
+
+- Rows should read left to right as: leading image or symbol, primary text,
+  secondary text, trailing value or accessory. Keep that order stable across
+  every row in a list so the eye can run down one column.
+- Swipe actions are shortcuts, not the only path. Anything in
+  `.swipeActions` must also be reachable from a context menu or the detail
+  screen, because swipes are undiscoverable and awkward with VoiceOver.
+- Destructive swipe actions use `role: .destructive`, and a full swipe should
+  only trigger an action that can be undone or that asks first.
+- Use `.contextMenu` for secondary actions on a row, with a preview when the
+  row opens into something visual.
+- Selection: `List(selection:)` gives the system edit mode, multi-select with
+  two-finger pan on iPad, and keyboard selection on Mac. Do not build custom
+  checkmark rows for this.
+- `.refreshable` gives the standard pull-to-refresh; do not add a manual
+  refresh button to the same list on iOS.
+- Section headers are for grouping, not decoration. If every section has one
+  row, the grouping is probably wrong.
+
+```swift
+List(selection: $selectedOrderIDs) {
+    ForEach(orders) { order in
+        OrderRow(order: order)
+            .swipeActions(edge: .trailing) {
+                Button("Archive", systemImage: "archivebox") { archive(order) }
+                    .tint(.indigo)
+            }
+            .contextMenu {
+                Button("Archive", systemImage: "archivebox") { archive(order) }
+                ShareLink(item: order.receiptURL)
+            }
+    }
+}
+.refreshable { await store.reload() }
+```
+
+## Collections and grids
+
+- Prefer adaptive columns (`GridItem(.adaptive(minimum: 140))`) so the grid
+  reflows from iPhone portrait to a Mac window without per-device code.
+- Keep item spacing consistent and let the content define the item, not a
+  heavy card border. On iOS 26, avoid stacking glass effects on grid items;
+  glass belongs to controls and navigation layered above content.
+- Large data sets need the lazy stacks and grids; `Grid` lays out every child
+  eagerly and suits a dozen cells, not a thousand.
+- Give tappable cells a clear pressed state and a context menu, the same as
+  list rows.
+
+## Charts
+
+- A chart must answer one question at a glance. Title it with the question or
+  the conclusion ("Orders per week, last quarter"), not the data source.
+- Choose the mark from the comparison: bars for discrete categories, lines for
+  change over continuous time, sectors only for a few parts of one whole.
+- Colour is never the only carrier of meaning. Add `.foregroundStyle(by:)`
+  with a legend and a second cue (symbol shape, direct labels, pattern).
+- Provide `.accessibilityLabel` and `.accessibilityValue` on marks, or an
+  audio graph via `AXChartDescriptorRepresentable`, so VoiceOver users get
+  the same answer.
+- Use `.chartXSelection` / `.chartScrollableAxes` for exploration instead of
+  bespoke gesture code.
+- Small inline charts (sparklines in a row or widget) drop axes and legends
+  entirely and must still make sense without them.
+
+## Images and media
+
+- Supply images at the scales the device needs, or use SF Symbols and vector
+  assets so they scale with Dynamic Type and the display.
+- Every meaningful image gets an accessibility label; decorative ones get
+  `.accessibilityHidden(true)` or `Image(decorative:)`.
+- `AsyncImage` needs a placeholder with the final aspect ratio so layout does
+  not jump when the image arrives.
+- Let people zoom and pan full-screen images with the standard gestures; a
+  double tap toggles between fit and a closer zoom.
+- For video use `VideoPlayer` or `AVPlayerViewController` so people get
+  system controls, Picture in Picture and AirPlay for free.
+
+## Text
+
+- Use text styles (`.body`, `.headline`, `.caption`) so Dynamic Type works;
+  never fix a point size for reading text.
+- Make read-only text selectable with `.textSelection(.enabled)` when people
+  might want to copy it (an order number, a tracking code, an address).
+- Long editable text belongs in `TextEditor` or a multi-line `TextField`, not
+  a single-line field that scrolls sideways.
+
+## Web content
+
+- Use an embedded web view only for content that is part of the app's own
+  experience (help pages, rendered documents). For arbitrary external links,
+  hand off to Safari or `SFSafariViewController` so people keep their
+  cookies, autofill and content blockers.
+- On iOS 26, the SwiftUI `WebView` with a `WebPage` model replaces most
+  `UIViewRepresentable` wrappers around `WKWebView`.
+- Do not rebuild a browser: no custom address bar, no custom back stack
+  unless the web content is the whole product.
+
+## Sharing
+
+- `ShareLink` presents the system share sheet; make the shared item a
+  `Transferable` type so it exports the richest representation available
+  and falls back gracefully (a file, then a URL, then plain text).
+- Put the share action where the object is shown (toolbar of the detail view,
+  context menu of the row), and use the standard `square.and.arrow.up` symbol.
+- Provide a `SharePreview` with a title and image so the sheet shows what is
+  being sent.

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

@@ -1,95 +1,86 @@
 ---
 name: hig-components-layout
-description: "Apple Human Interface Guidelines for layout and navigation components. Use when designing or reviewing layout and navigation on an Apple platform."
-risk: unknown
-source: community
-date_added: '2026-02-27'
+description: "Apple HIG for app structure mapped to SwiftUI: tab bars, split views, navigation stacks, toolbars, sheets, popovers, alerts, windows, iOS 26 Liquid Glass bars. Use when designing layout and navigation on an Apple platform."
+metadata:
+  risk: safe
+  source: multi-agent-pipeline
+  date_added: "2026-09-25"
 ---
 
-# Apple HIG: Layout and Navigation Components
+# HIG: Layout and Navigation Containers
 
-Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.
+This skill decides the frame of an app: how top-level areas are reached, how
+people drill in and back out, and when something should appear modally. The
+views inside the frame are covered by `hig-components-content`.
 
-## Key Principles
+## Pick the top-level structure
 
-1. **Organize hierarchically.** Structure information from broad categories to specific details. Sidebars for top-level sections, lists for browsable items, detail views for individual content.
+Count the app's peer areas and ask how people switch between them.
 
-2. **Use standard navigation patterns.** Tab bars for flat navigation between peer sections (iPhone). Sidebars for deep hierarchical navigation (iPad, Mac). Match the pattern to the information architecture and platform.
-
-3. **Adapt to screen size.** Three-column on iPad collapses to single-column on iPhone. Use size classes and adaptive APIs (NavigationSplitView) for automatic adaptation.
-
-4. **Support multitasking on iPad.** Respond gracefully to Split View, Slide Over, and Stage Manager. Test at every split ratio and size class transition.
-
-5. **Maintain spatial consistency on visionOS.** Windows, volumes, and ornaments in shared space. Position predictably. Use ornaments for toolbars and controls without occluding content.
-
-6. **Use scroll views for overflow content.** Enable paging for discrete content units. Support pull-to-refresh where appropriate. Respect safe areas.
-
-7. **Keep navigation predictable.** Users should always know where they are, how they got there, and how to go back. Use back buttons, breadcrumbs, and clear section titles.
-
-8. **Prefer system components.** UINavigationController, UISplitViewController, NavigationSplitView, and TabView provide built-in adaptivity, accessibility, and state restoration.
-
-## Topics
-
-| Topic | Key content |
-|---|---|
-| Sidebars | Source lists, selection state, collapsible sections, iPad/Mac patterns |
-| Column Views | Finder-style browsing, progressive disclosure through columns |
-| Outline Views | Expandable hierarchies, disclosure triangles, tree structures |
-| Split Views | Two/three column layouts, NavigationSplitView, adaptive collapse |
-| Tab Views | Segmented tabs, page-style tabs, macOS tab grouping |
-| Tab Bars | Bottom tab bars (iOS), badge counts, max tab count |
-| Scroll Views | Paging, scroll indicators, content insets, pull-to-refresh |
-| Windows | macOS/visionOS window management, sizing, full-screen, restoration |
-| Panels | Inspector panels, utility panels, floating panels, macOS conventions |
-| Lists and Tables | Plain/grouped/inset-grouped styles, swipe actions, section headers |
-| Boxes | Content grouping containers, labeled boxes, macOS grouping |
-| Ornaments | visionOS toolbar attachments, positioning, visibility |
-
-## Navigation Pattern Selection
-
-| App Structure | Recommended Pattern | Platform Adaptation |
+| Situation | Structure | SwiftUI |
 |---|---|---|
-| 3-5 peer top-level sections | Tab Bar | iPhone: bottom tab bar. iPad: sidebar (`.sidebarAdaptable`, iPadOS 18+). Mac: sidebar or toolbar tabs |
-| Deep hierarchical content | Sidebar + NavigationSplitView | iPhone: single column stack. iPad: two/three columns. Mac: full multi-column |
-| Deep file/folder tree | Column View | Mac: Finder-style. iPad: adaptable. iPhone: push navigation |
-| Flat list with detail | Split View (two column) | iPhone: push/pop stack. iPad/Mac: primary + detail columns |
-| Document-based with inspectors | Window + Panels | Mac: main window with inspector. iPad: sheet or popover |
-| Spatial app with tools | Window + Ornaments | visionOS: ornaments on window. Other platforms: toolbars |
-
-## Layout Adaptation Checklist
-
-- [ ] **Compact width (iPhone portrait):** Navigation collapses to single stack? Tab bars visible?
-- [ ] **Regular width (iPad landscape, Mac):** Navigation expands to sidebar + detail? Space used well?
-- [ ] **Multitasking (iPad):** Adapts at every split ratio? Works in Slide Over?
-- [ ] **Accessibility:** Supports Dynamic Type at all sizes? VoiceOver order logical?
-- [ ] **Orientation:** Content reflows between portrait and landscape?
-- [ ] **visionOS:** Windows positioned ergonomically? Ornaments accessible? Depth meaningful?
-
-## Output Format
-
-1. **Recommended navigation pattern** with rationale for the app's information architecture.
-2. **Layout hierarchy** from root container down (e.g., TabView > NavigationSplitView > List > Detail).
-3. **Platform adaptation** across targeted platforms and size classes.
-4. **Size class behavior** at each transition.
-
-## Questions to Ask
-
-1. What is the app's information architecture? (Sections, hierarchy depth, top-level categories?)
-2. How many top-level sections?
-3. Which platforms?
-4. Need multitasking on iPad?
-5. SwiftUI or UIKit?
-
-## Related Skills
-
-- **hig-foundations** -- Layout spacing, margins, safe areas, alignment
-- **hig-platforms** -- Platform-specific navigation conventions
-- **hig-patterns** -- Multitasking, full-screen, and launching patterns
-- **hig-components-content** -- Content displayed within layout containers
-
----
-
-*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.
+| A few peer areas used often (orders, products, account) | Tab bar | `TabView` with `Tab` values |
+| Many areas, or areas people customise, on iPad and Mac | Sidebar | `TabView` + `.tabViewStyle(.sidebarAdaptable)`, or `NavigationSplitView` |
+| One list that opens details | Stack | `NavigationStack` with `navigationDestination(for:)` |
+| List, detail and a third level on large screens | Three columns | `NavigationSplitView(sidebar:content:detail:)` |
+| Contextual settings for the current selection | Inspector | `.inspector(isPresented:)` |
+| A single focused task that ends in done or cancel | Sheet | `.sheet`, `.fullScreenCover` for immersive tasks |
+
+A tab bar switches context and never navigates within one; do not use a tab
+to trigger an action like "new note". A sidebar-adaptable `TabView` gives a
+tab bar on iPhone and a sidebar on iPad and Mac from one declaration.
+
+## Details on demand
+
+Load `references/containers.md` for tab bars, sidebars, navigation bars, toolbars, scroll views, windows and size adaptation, with SwiftUI examples.
+
+## Modality: sheets, popovers, alerts
+
+Modality interrupts. Use it for a self-contained task or a decision that must
+happen now, and always give an obvious way out.
+
+- **Sheet** for a task with its own steps (compose a note, edit an address).
+  Title it, put Cancel on the leading side and the confirming action on the
+  trailing side. Use `.presentationDetents([.medium, .large])` for resizable
+  sheets; on iOS 26 partial-height sheets float with a glass background and
+  inset edges.
+- Protect unsaved input with `.interactiveDismissDisabled(hasChanges)` plus a
+  confirmation, rather than silently discarding it on swipe down.
+- **Popover** on iPad and Mac for short contextual content anchored to a
+  control; it adapts to a sheet in compact width.
+- **Alert** only for information that needs acknowledgement or a decision
+  with two or three outcomes. Use `role: .destructive` and `role: .cancel`.
+- **Confirmation dialog** (`.confirmationDialog`) for choosing among actions
+  triggered by the person, such as "Delete order" with a cancel.
+- Avoid stacking modals. If a sheet needs another sheet, the flow wants a
+  navigation stack inside the first sheet.
+
+## Review checklist
+
+- Is the top-level structure chosen from the number and use of peer areas?
+- Does every tab keep its own state, and is no tab used as an action?
+- Do modals have a clear cancel, and is unsaved work protected?
+- Does content run under glass bars rather than behind opaque fills (iOS 26)?
+- Are toolbar items declared with semantic placements?
+- Does the layout adapt across size classes, windows and orientations?
+
+## Related skills
+
+- `hig-components-content` for lists, grids, charts inside these containers.
+- `hig-patterns` for flows such as first launch, search and settings.
+- `hig-platforms` for per-platform differences.
+- `swiftui-navigation` and `swiftui-liquid-glass` for implementation detail.
+
+## References
+
+- https://developer.apple.com/design/human-interface-guidelines/tab-bars
+- https://developer.apple.com/design/human-interface-guidelines/sidebars
+- https://developer.apple.com/design/human-interface-guidelines/split-views
+- https://developer.apple.com/design/human-interface-guidelines/toolbars
+- https://developer.apple.com/design/human-interface-guidelines/scroll-views
+- https://developer.apple.com/design/human-interface-guidelines/sheets
+- https://developer.apple.com/design/human-interface-guidelines/popovers
+- https://developer.apple.com/design/human-interface-guidelines/alerts
+- https://developer.apple.com/design/human-interface-guidelines/windows
+- https://developer.apple.com/design/human-interface-guidelines/panels
+- https://developer.apple.com/design/human-interface-guidelines/layout

package/pipeline/skills/shared/external/hig-components-layout/references/containers.md

@@ -0,0 +1,98 @@
+# Layout containers in detail
+
+Companion to `../SKILL.md` for the `hig-components-layout` skill.
+
+## Tab bars
+
+- Keep tabs few and stable. Each tab keeps its own navigation state; switching
+  back returns people to where they left off.
+- Never hide or disable a tab because of state. Show the tab and explain
+  inside it (an empty state or sign-in prompt).
+- On iOS 18 and later, `Tab(role: .search)` places search as a dedicated tab;
+  on iOS 26 it is set apart at the trailing end of the floating glass tab bar.
+- iOS 26 renders the tab bar as floating Liquid Glass above content. Let
+  content scroll underneath it; do not paint an opaque background behind it.
+- `.tabBarMinimizeBehavior(.onScrollDown)` (iOS 26) shrinks the bar while
+  reading; `.tabViewBottomAccessory` places a persistent control such as a
+  playback bar above it.
+- Badges (`.badge(3)`) are for counts people act on, not marketing.
+
+```swift
+TabView(selection: $selection) {
+    Tab("Orders", systemImage: "shippingbox", value: .orders) {
+        OrdersView()
+    }
+    .badge(pendingCount)
+    Tab("Products", systemImage: "square.grid.2x2", value: .products) {
+        ProductsView()
+    }
+    Tab(value: .search, role: .search) {
+        SearchView()
+    }
+}
+.tabViewStyle(.sidebarAdaptable)
+.tabBarMinimizeBehavior(.onScrollDown)
+```
+
+## Sidebars and split views
+
+- The sidebar lists destinations, grouped into sections when there are many.
+  It does not hold actions or forms.
+- Let the system collapse columns in compact width;
+  `NavigationSplitView` becomes a stack on iPhone automatically. Use
+  `preferredCompactColumn` to choose what shows first.
+- Keep selection visible: the chosen sidebar row stays highlighted while its
+  detail is shown.
+- iOS 26 draws the sidebar as a glass layer floating over content. Use
+  `.backgroundExtensionEffect()` on hero images in the detail column so they
+  extend visually beneath the sidebar instead of stopping at its edge.
+
+## Navigation stacks and bars
+
+- The title names the current place. Use large titles at the root of a
+  hierarchy and inline titles deeper in.
+- The back button shows the previous title or "Back"; never replace it with a
+  custom control that breaks the edge-swipe gesture.
+- Drive navigation from data: a `NavigationPath` or a typed selection binding
+  makes deep links and state restoration straightforward.
+- Put no more than a couple of frequent actions in the bar. Secondary actions
+  go in a `Menu` behind an ellipsis item.
+
+## Toolbars
+
+- Declare actions with `.toolbar` and placements (`.primaryAction`,
+  `.topBarTrailing`, `.bottomBar`, `.confirmationAction`,
+  `.cancellationAction`) so the system positions them per platform.
+- On iOS 26 toolbar items sit on glass and are grouped automatically;
+  `ToolbarSpacer` separates groups. Prefer SF Symbols over text for bar items
+  and let the system apply glass; do not add your own backgrounds.
+- Use `.toolbarRole(.editor)` on document-style screens and let people
+  customise Mac and iPad toolbars with `id`-based toolbar items.
+
+## Scroll views
+
+- Content should scroll under bars and the tab bar; the scroll edge effect
+  keeps controls legible on iOS 26.
+- Show scroll indicators for long content, and use `.scrollTargetBehavior(.paging)`
+  or `.viewAligned` only when the content really is paged.
+- Never nest two scroll views on the same axis.
+- Use `.safeAreaInset(edge:)` for a persistent footer (a checkout summary)
+  so the content scrolls clear of it.
+
+## Windows and panels (iPadOS, macOS, visionOS)
+
+- Support multiple windows when people might compare two items; use
+  `WindowGroup(for:)` with a value so each window restores its item.
+- Open auxiliary windows with `openWindow(value:)`; a Mac utility panel is a
+  `Window` or `UtilityWindow` scene, not a sheet.
+- Size layouts with flexible frames and size classes so the same scene works
+  from a narrow iPad split to a full Mac display.
+- Add `Settings` for Mac preferences instead of a settings tab.
+
+## Adapting across sizes
+
+1. Check compact width (iPhone portrait, iPad slide over) and regular width.
+2. Confirm split views collapse to a sensible first column.
+3. Confirm tab bars turn into a sidebar where `.sidebarAdaptable` is used.
+4. Test the largest Dynamic Type size: bars stay usable, content scrolls.
+5. Test right-to-left: back buttons, sidebars and swipe edges mirror.