@mmerterden/multi-agent-pipeline 8.6.2 → 10.0.6

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

@@ -1,11 +1,11 @@
 ---
 name: swiftui-layout-components
-description: "Build SwiftUI layouts using stacks, grids, lists, scroll views, forms, and controls. Covers VStack/HStack/ZStack, LazyVGrid/LazyHGrid, List with sections and swipe actions, ScrollView with ScrollViewReader, Form with validation, Toggle/Picker/Slider, .searchable, and overlay patterns. Use when building data-driven layouts, collection views, settings screens, search interfaces, or transient overlay UI."
+description: "Build SwiftUI layouts using stacks, grids, lists, scroll views, forms, and controls. Covers VStack/HStack/ZStack, LazyVGrid/LazyHGrid, List with sections and swipe actions, ScrollView with ScrollPosition, Form with validation, Toggle/Picker/Slider, .searchable, and overlay patterns. Use when building data-driven layouts, collection views, settings screens, search interfaces, or transient overlay UI."
 ---
 
 # SwiftUI Layout & Components
 
-Layout and component patterns for SwiftUI apps targeting iOS 26+ with Swift 6.2. Covers stack and grid layouts, list patterns, scroll views, forms, controls, search, and overlays. Patterns are backward-compatible to iOS 17 unless noted.
+Layout and component patterns for SwiftUI apps targeting iOS 26+ with Swift 6.3. Covers stack and grid layouts, list patterns, scroll views, forms, controls, search, and overlays. Patterns are backward-compatible to iOS 17 unless noted.
 
 ## Contents
 
@@ -27,7 +27,7 @@ Layout and component patterns for SwiftUI apps targeting iOS 26+ with Swift 6.2.
 Use `VStack`, `HStack`, and `ZStack` for small, fixed-size content. They render all children immediately.
 
 ```swift
-VStack(alignment: .leading, spacing: 8) {
+VStack(alignment: .leading) {
     Text(title).font(.headline)
     Text(subtitle).font(.subheadline).foregroundStyle(.secondary)
 }
@@ -39,7 +39,7 @@ Use `LazyVStack` and `LazyHStack` inside `ScrollView` for large or dynamic colle
 
 ```swift
 ScrollView {
-    LazyVStack(spacing: 12) {
+    LazyVStack {
         ForEach(items) { item in
             ItemRow(item: item)
         }
@@ -60,7 +60,7 @@ Use `LazyVGrid` for icon pickers, media galleries, and dense visual selections.
 // Adaptive grid -- columns adjust to fit
 let columns = [GridItem(.adaptive(minimum: 120, maximum: 1024))]
 
-LazyVGrid(columns: columns, spacing: 6) {
+LazyVGrid(columns: columns) {
     ForEach(items) { item in
         ThumbnailView(item: item)
             .aspectRatio(1, contentMode: .fit)
@@ -79,9 +79,9 @@ LazyVGrid(columns: columns, spacing: 4) {
 }
 ```
 
-Use `.aspectRatio` for cell sizing. Never place `GeometryReader` inside lazy containers -- it forces eager measurement and defeats lazy loading. Use `.onGeometryChange` (iOS 18+) if you need to read dimensions.
+Use `.aspectRatio` for cell sizing. Never place `GeometryReader` inside lazy containers -- it forces eager measurement and defeats lazy loading. Use `.onGeometryChange` (iOS 16+) if you need to read dimensions.
 
-See `references/grids.md` for full grid patterns and design choices.
+See [references/grids.md](references/grids.md) for full grid patterns and design choices.
 
 ## List Patterns
 
@@ -104,13 +104,13 @@ List {
 - `.listStyle(.plain)` for feed layouts, `.insetGrouped` for settings
 - `.scrollContentBackground(.hidden)` + custom background for themed surfaces
 - `.listRowInsets(...)` and `.listRowSeparator(.hidden)` for spacing and separator control
-- Pair with `ScrollViewReader` for scroll-to-top or jump-to-id
+- Use `ScrollPosition` with `.scrollPosition($scrollPosition)` for scroll-to-top or jump-to-id
 - Use `.refreshable { }` for pull-to-refresh feeds
 - Use `.contentShape(Rectangle())` on rows that should be tappable end-to-end
 
 **iOS 26:** Apply `.scrollEdgeEffectStyle(.soft, for: .top)` for modern scroll edge effects.
 
-See `references/list.md` for full list patterns including feed lists with scroll-to-top.
+See [references/list.md](references/list.md) for full list patterns including feed lists with scroll-to-top.
 
 ## ScrollView
 
@@ -118,7 +118,7 @@ Use `ScrollView` with lazy stacks when you need custom layout, mixed content, or
 
 ```swift
 ScrollView(.horizontal, showsIndicators: false) {
-    LazyHStack(spacing: 8) {
+    LazyHStack {
         ForEach(chips) { chip in
             ChipView(chip: chip)
         }
@@ -126,25 +126,27 @@ ScrollView(.horizontal, showsIndicators: false) {
 }
 ```
 
-**ScrollViewReader:** Enables programmatic scrolling to specific items.
+**ScrollPosition:** Enables declarative, bidirectional scroll position tracking and programmatic scrolling.
 
 ```swift
-ScrollViewReader { proxy in
-    ScrollView {
-        LazyVStack {
-            ForEach(messages) { message in
-                MessageRow(message: message).id(message.id)
-            }
-        }
-    }
-    .onChange(of: messages.last?.id) { _, newValue in
-        if let id = newValue {
-            withAnimation { proxy.scrollTo(id, anchor: .bottom) }
+@State private var scrollPosition = ScrollPosition(edge: .bottom)
+
+ScrollView {
+    LazyVStack {
+        ForEach(messages) { message in
+            MessageRow(message: message)
         }
     }
+    .scrollTargetLayout()
+}
+.scrollPosition($scrollPosition)
+.onChange(of: messages.last?.id) {
+    withAnimation { scrollPosition.scrollTo(edge: .bottom) }
 }
 ```
 
+See [references/scrollview.md](references/scrollview.md) for full `ScrollPosition` patterns including scroll-to-id and user-scroll detection.
+
 **`safeAreaInset(edge:)`** pins content (input bars, toolbars) above the keyboard without affecting scroll layout.
 
 **iOS 26 additions:**
@@ -152,7 +154,7 @@ ScrollViewReader { proxy in
 - `.backgroundExtensionEffect()` -- mirror/blur at safe area edges (use sparingly, one per screen)
 - `.safeAreaBar(edge:)` -- attach bar views that integrate with scroll effects
 
-See `references/scrollview.md` for full scroll patterns and iOS 26 edge effects.
+See [references/scrollview.md](references/scrollview.md) for full scroll patterns and iOS 26 edge effects.
 
 ## Form and Controls
 
@@ -216,7 +218,7 @@ Picker("Default Visibility", selection: $visibility) {
 
 Avoid `.pickerStyle(.segmented)` for large sets; use menu or inline styles. Don't hide labels for sliders; always show context.
 
-See `references/form.md` for full form examples.
+See [references/form.md](references/form.md) for full form examples.
 
 ## Searchable
 
@@ -312,6 +314,7 @@ Prefer overlays for transient UI rather than embedding in layout stacks. Use tra
 8. Running searches on empty strings -- always guard against empty queries
 9. Mixing `List` and `ScrollView` in the same hierarchy -- gesture conflicts
 10. Using `.pickerStyle(.segmented)` for large option sets -- use menu or inline styles
+11. Hard-coding `spacing:` on stacks and grids by default -- omit to get platform-adaptive spacing; only specify for intentional tight (0-4pt) or wide gaps
 
 ## Review Checklist
 
@@ -325,12 +328,13 @@ Prefer overlays for transient UI rather than embedding in layout stacks. Use tra
 - [ ] Overlays use transitions and auto-dismiss timers
 - [ ] `.contentShape(Rectangle())` on tappable rows
 - [ ] `@FocusState` manages keyboard focus in forms
+- [ ] Stack/grid `spacing:` omitted unless a specific value is required
 
 ## References
 
-- Grid patterns: `references/grids.md`
-- List and section patterns: `references/list.md`
-- ScrollView and lazy stacks: `references/scrollview.md`
-- Form patterns: `references/form.md`
+- Grid patterns: [references/grids.md](references/grids.md)
+- List and section patterns: [references/list.md](references/list.md)
+- ScrollView and lazy stacks: [references/scrollview.md](references/scrollview.md)
+- Form patterns: [references/form.md](references/form.md)
 - Architecture and state management: see `swiftui-patterns` skill
 - Navigation patterns: see `swiftui-navigation` skill

package/pipeline/skills/shared/external/swiftui-layout-components/references/form.md

@@ -94,4 +94,4 @@ struct AddRemoteServerView: View {
 
 - Avoid heavy custom layouts inside a `Form`; it can lead to spacing issues.
 - If you need highly custom layouts, prefer `ScrollView` + `VStack`.
-- Don’t mix multiple background strategies; pick either default Form styling or custom colors.
+- Don't mix multiple background strategies; pick either default Form styling or custom colors.

package/pipeline/skills/shared/external/swiftui-layout-components/references/grids.md

@@ -1,69 +1,230 @@
 # Grids
 
+## Contents
+- Intent
+- Choosing the right grid type
+- Column strategies
+- Cell sizing and aspect ratio
+- Example: adaptive icon grid
+- Example: fixed 3-column media grid
+- Example: sectioned grid
+- Selection and interaction patterns
+- Performance guardrails
+- Accessibility and polish
+- Pitfalls
+
 ## Intent
 
-Use `LazyVGrid` for icon pickers, media galleries, and dense visual selections where items align in columns.
+Use grids for dense visual collections where row-based layouts waste space or
+make scanning harder.
+
+Good fits:
+
+- icon pickers
+- media galleries
+- template choosers
+- settings tiles
+- dashboards with repeatable cards
+
+Default to `LazyVGrid` for vertically scrolling collections on iOS. Reach for
+`Grid` when content is small and non-scrollable, or when you need explicit row
+composition rather than a large lazy container.
+
+## Choosing the right grid type
+
+### `LazyVGrid`
+
+Use for the common iPhone/iPad case: many items, vertical scrolling, and a
+column definition that should adapt to width.
+
+### `LazyHGrid`
+
+Use when horizontal scrolling is the dominant interaction and rows are easier to
+define than columns.
+
+### `Grid`
+
+Use when:
+
+- the item count is small
+- the content is mostly static
+- row/column relationships matter more than lazy loading
+- you need `GridRow` composition instead of a repeated collection layout
+
+For large scrolling datasets, `LazyVGrid` is usually the safer default.
+
+## Column strategies
+
+### Adaptive columns
+
+Use `.adaptive` when you want the number of columns to respond to available
+width.
+
+```swift
+let columns = [GridItem(.adaptive(minimum: 120, maximum: 240))]
+```
+
+This is the best default for icon pickers, template choosers, and photo grids
+that should scale naturally across iPhone and iPad sizes.
+
+### Flexible columns
+
+Use multiple `.flexible` columns when you want a predictable column count.
+
+```swift
+let columns = [
+    GridItem(.flexible(minimum: 100)),
+    GridItem(.flexible(minimum: 100)),
+    GridItem(.flexible(minimum: 100)),
+]
+```
+
+This works well when design requires a fixed 2-column or 3-column rhythm.
+
+### Fixed columns
+
+Use `.fixed` only when the design truly requires exact widths. Fixed columns are
+less resilient across device sizes and dynamic type changes.
 
-## Core patterns
+## Cell sizing and aspect ratio
 
-- Use `.adaptive` columns for layouts that should scale across device sizes.
-- Use multiple `.flexible` columns when you want a fixed column count.
-- Keep spacing consistent and small to avoid uneven gutters.
-- Use `.aspectRatio(1, contentMode: .fit)` on grid cells for square thumbnails. Avoid `GeometryReader` inside lazy containers (it defeats lazy layout and causes performance issues).
+Grid cells should usually define their own shape without reading parent
+geometry.
+
+Preferred sizing tools:
+
+- `.aspectRatio(1, contentMode: .fit)` for square thumbnails
+- `.frame(maxWidth: .infinity)` when content should fill the available column
+- internal padding instead of outer geometry math
+
+Avoid `GeometryReader` inside lazy containers. It defeats lazy layout and adds
+extra measurement work.
 
 ## Example: adaptive icon grid
 
 ```swift
-let columns = [GridItem(.adaptive(minimum: 120, maximum: 1024))]
-
-LazyVGrid(columns: columns, spacing: 6) {
-  ForEach(icons) { icon in
-    Button {
-      select(icon)
-    } label: {
-      ZStack(alignment: .bottomTrailing) {
-        Image(icon.previewName)
-          .resizable()
-          .aspectRatio(contentMode: .fit)
-          .cornerRadius(6)
-        if icon.isSelected {
-          Image(systemName: "checkmark.seal.fill")
-            .padding(4)
-            .tint(.green)
+let columns = [GridItem(.adaptive(minimum: 120, maximum: 240))]
+
+LazyVGrid(columns: columns) {
+    ForEach(icons) { icon in
+        Button {
+            select(icon)
+        } label: {
+            ZStack(alignment: .bottomTrailing) {
+                Image(icon.previewName)
+                    .resizable()
+                    .aspectRatio(contentMode: .fit)
+                    .clipShape(.rect(cornerRadius: 6))
+
+                if icon.isSelected {
+                    Image(systemName: "checkmark.seal.fill")
+                        .padding(4)
+                        .tint(.green)
+                }
+            }
         }
-      }
+        .buttonStyle(.plain)
+        .contentShape(Rectangle())
     }
-    .buttonStyle(.plain)
-  }
 }
 ```
 
+Why this works:
+
+- adaptive columns scale across width classes
+- square-ish cells come from image aspect ratio, not geometry reads
+- the whole tile remains tappable
+
 ## Example: fixed 3-column media grid
 
 ```swift
 LazyVGrid(
-  columns: [
-    .init(.flexible(minimum: 100), spacing: 4),
-    .init(.flexible(minimum: 100), spacing: 4),
-    .init(.flexible(minimum: 100), spacing: 4),
-  ],
-  spacing: 4
+    columns: [
+        .init(.flexible(minimum: 100), spacing: 4),
+        .init(.flexible(minimum: 100), spacing: 4),
+        .init(.flexible(minimum: 100), spacing: 4),
+    ],
+    spacing: 4
 ) {
-  ForEach(items) { item in
-    ThumbnailView(item: item)
-      .aspectRatio(1, contentMode: .fit)
-  }
+    ForEach(items) { item in
+        ThumbnailView(item: item)
+            .aspectRatio(1, contentMode: .fit)
+            .clipShape(.rect(cornerRadius: 8))
+    }
 }
 ```
 
-## Design choices to keep
+Use this when the design language wants a consistent three-up gallery instead of
+an adaptive count.
+
+## Example: sectioned grid
+
+Sectioned grids work well for grouped content like categories or recents.
+
+```swift
+LazyVGrid(columns: [GridItem(.adaptive(minimum: 140))]) {
+    ForEach(sections) { section in
+        Section {
+            ForEach(section.items) { item in
+                Tile(item: item)
+            }
+        } header: {
+            Text(section.title)
+                .font(.headline)
+                .frame(maxWidth: .infinity, alignment: .leading)
+                .padding(.top)
+        }
+    }
+}
+```
+
+Keep headers visually lightweight. Dense grids lose scan efficiency when every
+section header is oversized or heavily decorated.
+
+## Selection and interaction patterns
+
+Grid interactions should stay obvious and forgiving.
+
+Useful defaults:
+
+- make the entire cell tappable with `.contentShape(Rectangle())`
+- show selection state in one consistent corner or border treatment
+- keep hover/focus/pressed states subtle but visible
+- avoid stacking too many overlays on every item
+
+For multi-select grids, prefer clear selection affordances instead of hidden
+state changes triggered only by long press.
+
+## Performance guardrails
+
+- Use `LazyVGrid` for large collections.
+- Keep overlay count low in every cell.
+- Downsample large images before display.
+- Avoid expensive formatting or filtering in cell bodies.
+- Prefer stable item identity in `ForEach`.
+- Precompute grouped or filtered collections before rendering.
+
+If scrolling stutters, profile image decoding, per-cell overlays, and repeated
+state invalidation before changing the grid structure itself.
+
+## Accessibility and polish
+
+- Maintain clear visual grouping and consistent spacing.
+- Test with Dynamic Type even if cells are primarily visual.
+- Ensure VoiceOver labels describe the item and selection state.
+- Use meaningful focus order on iPad and keyboard-driven flows.
+- Avoid tiny hit targets even when cells are visually dense.
 
-- Use `LazyVGrid` for large collections; avoid non-lazy grids for big sets.
-- Keep tap targets full-bleed using `.contentShape(Rectangle())` when needed.
-- Prefer adaptive grids for settings pickers and flexible layouts.
+A dense grid should still feel calm and legible, not like a wall of competing
+badges and borders.
 
 ## Pitfalls
 
 - Avoid heavy overlays in every grid cell; it can be expensive.
-- Don’t nest grids inside other grids without a clear reason.
-- **Never place `GeometryReader` inside lazy containers** (`LazyVGrid`, `LazyHGrid`, `LazyVStack`, `LazyHStack`). It forces eager measurement and defeats lazy loading. Use `.aspectRatio` for sizing, or `.onGeometryChange` (iOS 18+) if you need to read dimensions.
+- Don't nest grids inside other grids without a clear reason.
+- Don't put filtering logic inline in `ForEach`.
+- Don't use fixed columns where adaptive columns better match the product goal.
+- **Never place `GeometryReader` inside lazy containers** (`LazyVGrid`,
+  `LazyHGrid`, `LazyVStack`, `LazyHStack`). It forces eager measurement and
+  defeats lazy loading. Use `.aspectRatio` for sizing, or `.onGeometryChange`
+  (iOS 18+) if you need to read dimensions.

package/pipeline/skills/shared/external/swiftui-layout-components/references/list.md

@@ -8,12 +8,12 @@ Use `List` for feed-style content and settings-style rows where built-in row reu
 
 - Prefer `List` for long, vertically scrolling content with repeated rows.
 - Use `Section` headers to group related rows.
-- Pair with `ScrollViewReader` when you need scroll-to-top or jump-to-id.
+- Use `ScrollPosition` with `.scrollPosition($scrollPosition)` for scroll-to-top or jump-to-id.
 - Use `.listStyle(.plain)` for modern feed layouts.
 - Use `.listStyle(.grouped)` for multi-section discovery/search pages where section grouping helps.
 - Apply `.scrollContentBackground(.hidden)` + a custom background when you need a themed surface.
 - Use `.listRowInsets(...)` and `.listRowSeparator(.hidden)` to tune row spacing and separators.
-- Use `.environment(\\.defaultMinListRowHeight, ...)` to control dense list layouts.
+- Use `.environment(\.defaultMinListRowHeight, ...)` to control dense list layouts.
 
 ## Example: feed list with scroll-to-top
 
@@ -21,32 +21,23 @@ Use `List` for feed-style content and settings-style rows where built-in row reu
 @MainActor
 struct TimelineListView: View {
   @Environment(\.selectedTabScrollToTop) private var selectedTabScrollToTop
-  @State private var scrollToId: String?
+  @State private var scrollPosition = ScrollPosition(idType: String.self)
 
   var body: some View {
-    ScrollViewReader { proxy in
-      List {
-        ForEach(items) { item in
-          TimelineRow(item: item)
-            .id(item.id)
-            .listRowInsets(.init(top: 12, leading: 16, bottom: 6, trailing: 16))
-            .listRowSeparator(.hidden)
-        }
-      }
-      .listStyle(.plain)
-      .environment(\\.defaultMinListRowHeight, 1)
-      .onChange(of: scrollToId) { _, newValue in
-        if let newValue {
-          proxy.scrollTo(newValue, anchor: .top)
-          scrollToId = nil
-        }
+    List {
+      ForEach(items) { item in
+        TimelineRow(item: item)
+          .id(item.id)
+          .listRowInsets(.init(top: 12, leading: 16, bottom: 12, trailing: 16))
+          .listRowSeparator(.hidden)
       }
-      .onChange(of: selectedTabScrollToTop) { _, newValue in
-        if newValue == 0 {
-          withAnimation {
-            proxy.scrollTo(ScrollToView.Constants.scrollToTop, anchor: .top)
-          }
-        }
+    }
+    .listStyle(.plain)
+    .environment(\.defaultMinListRowHeight, 1)
+    .scrollPosition($scrollPosition)
+    .onChange(of: selectedTabScrollToTop) {
+      withAnimation {
+        scrollPosition.scrollTo(edge: .top)
       }
     }
   }

package/pipeline/skills/shared/external/swiftui-layout-components/references/scrollview.md

@@ -5,6 +5,7 @@
 - [Intent](#intent)
 - [Core patterns](#core-patterns)
 - [Example: vertical custom feed](#example-vertical-custom-feed)
+- [ScrollPosition capabilities](#scrollposition-capabilities)
 - [Example: horizontal chips](#example-horizontal-chips)
 - [Example: adaptive grid](#example-adaptive-grid)
 - [Design choices to keep](#design-choices-to-keep)
@@ -20,7 +21,7 @@ Use `ScrollView` with `LazyVStack`, `LazyHStack`, or `LazyVGrid` when you need c
 - Prefer `ScrollView` + `LazyVStack` for chat-like or custom feed layouts.
 - Use `ScrollView(.horizontal)` + `LazyHStack` for chips, tags, avatars, and media strips.
 - Use `LazyVGrid` for icon/media grids; prefer adaptive columns when possible.
-- Use `ScrollViewReader` for scroll-to-top/bottom and anchor-based jumps.
+- Use `ScrollPosition` for programmatic scrolling: scroll-to-id, scroll-to-edge, and point-based offsets.
 - Use `safeAreaInset(edge:)` for input bars that should stick above the keyboard.
 
 ## Example: vertical custom feed
@@ -28,40 +29,84 @@ Use `ScrollView` with `LazyVStack`, `LazyHStack`, or `LazyVGrid` when you need c
 ```swift
 @MainActor
 struct ConversationView: View {
-  private enum Constants { static let bottomAnchor = "bottom" }
-  @State private var scrollProxy: ScrollViewProxy?
+  @State private var scrollPosition = ScrollPosition(edge: .bottom)
 
   var body: some View {
-    ScrollViewReader { proxy in
-      ScrollView {
-        LazyVStack {
-          ForEach(messages) { message in
-            MessageRow(message: message)
-              .id(message.id)
-          }
-          Color.clear.frame(height: 1).id(Constants.bottomAnchor)
-        }
-        .padding(.horizontal, .layoutPadding)
-      }
-      .safeAreaInset(edge: .bottom) {
-        MessageInputBar()
-      }
-      .onAppear {
-        scrollProxy = proxy
-        withAnimation {
-          proxy.scrollTo(Constants.bottomAnchor, anchor: .bottom)
+    ScrollView {
+      LazyVStack {
+        ForEach(messages) { message in
+          MessageRow(message: message)
         }
       }
+      .scrollTargetLayout()
+      .padding(.horizontal, .layoutPadding)
+    }
+    .scrollPosition($scrollPosition)
+    .safeAreaInset(edge: .bottom) {
+      MessageInputBar()
+    }
+    .onChange(of: messages.last?.id) {
+      withAnimation { scrollPosition.scrollTo(edge: .bottom) }
     }
   }
 }
 ```
 
+## ScrollPosition capabilities
+
+`ScrollPosition` (iOS 18+) replaces `ScrollViewReader` for programmatic scrolling. It is declarative, supports bidirectional position tracking, and does not require a closure wrapper.
+
+**Setup:** Declare state and attach to the scroll view. Apply `.scrollTargetLayout()` to the inner layout container so SwiftUI can track individual view identities.
+
+```swift
+@State private var scrollPosition = ScrollPosition(idType: Message.ID.self)
+
+ScrollView {
+    LazyVStack {
+        ForEach(messages) { message in
+            MessageRow(message: message)
+        }
+    }
+    .scrollTargetLayout()
+}
+.scrollPosition($scrollPosition)
+```
+
+**Scroll to a specific item:**
+
+```swift
+scrollPosition.scrollTo(id: message.id, anchor: .top)
+```
+
+**Scroll to an edge:**
+
+```swift
+scrollPosition.scrollTo(edge: .bottom)
+```
+
+**Read the current position:**
+
+```swift
+if let currentID = scrollPosition.viewID(type: Message.ID.self) {
+    // The view with this ID is currently at the scroll anchor
+}
+```
+
+**Detect user-initiated scrolls:**
+
+```swift
+.onChange(of: scrollPosition.isPositionedByUser) { _, byUser in
+    if byUser {
+        // User scrolled manually -- show "scroll to bottom" button
+    }
+}
+```
+
 ## Example: horizontal chips
 
 ```swift
 ScrollView(.horizontal, showsIndicators: false) {
-  LazyHStack(spacing: 8) {
+  LazyHStack {
     ForEach(chips) { chip in
       ChipView(chip: chip)
     }
@@ -75,12 +120,12 @@ ScrollView(.horizontal, showsIndicators: false) {
 let columns = [GridItem(.adaptive(minimum: 120))]
 
 ScrollView {
-  LazyVGrid(columns: columns, spacing: 8) {
+  LazyVGrid(columns: columns) {
     ForEach(items) { item in
       GridItemView(item: item)
     }
   }
-  .padding(8)
+  .padding()
 }
 ```
 
@@ -88,7 +133,7 @@ ScrollView {
 
 - Use `Lazy*` stacks when item counts are large or unknown.
 - Use non-lazy stacks for small, fixed-size content to avoid lazy overhead.
-- Keep IDs stable when using `ScrollViewReader`.
+- Keep IDs stable for `ScrollPosition` tracking; changing IDs causes position jumps.
 - Prefer explicit animations (`withAnimation`) when scrolling to an ID.
 
 ## iOS 26 Scroll Edge Effects
@@ -141,7 +186,7 @@ content
 ## Pitfalls
 
 - Avoid nesting scroll views of the same axis; it causes gesture conflicts.
-- Don’t combine `List` and `ScrollView` in the same hierarchy without a clear reason.
+- Don't combine `List` and `ScrollView` in the same hierarchy without a clear reason.
 - Overuse of `LazyVStack` for tiny content can add unnecessary complexity.
 - Apply `scrollEdgeEffectStyle` on the ScrollView, not on inner content.
 - Use `backgroundExtensionEffect()` on only one view per screen.