buildanything 1.7.1 → 2.0.0

package/skills/ios/ios-26-platform/references/automatic-adoption.md

@@ -0,0 +1,161 @@
+# Automatic vs Explicit Adoption
+
+**iOS 26+**
+
+## What Changes Automatically (Recompile Only)
+
+### Standard Components Get Liquid Glass
+Simply recompile with Xcode 26 — no code changes:
+
+```swift
+// All these get glass automatically:
+NavigationView { ... }
+TabView { ... }
+.toolbar { ... }
+.sheet { ... }
+.popover { ... }
+List { ... }
+```
+
+### Controls Get New Appearance
+- Toggles, segmented pickers, sliders
+- Knobs transform into glass during interaction
+- Buttons morph into menus/popovers
+
+### Search Placement
+```swift
+NavigationSplitView {
+    List { }
+        .searchable(text: $searchText)
+}
+// Automatically:
+// - Bottom-aligned on iPhone (ergonomic)
+// - Top trailing on iPad
+```
+
+### Performance Improvements
+- **6x faster loading** for 100k+ item lists (macOS)
+- **16x faster updates** for large lists
+- Reduced dropped frames during scrolling
+- Better nested ScrollView performance with lazy stacks
+
+## What Requires Code Changes
+
+### Toolbar Customization
+```swift
+.toolbar {
+    ToolbarItemGroup(placement: .topBarTrailing) {
+        Button("Up") { }
+        Button("Down") { }
+
+        Spacer(.fixed) // NEW: Separates button groups
+
+        Button("Settings") { }
+    }
+}
+```
+
+### Prominent Toolbar Buttons
+```swift
+Button("Add Trip") {
+    addTrip()
+}
+.buttonStyle(.borderedProminent)
+.tint(.blue) // Tinting in glass toolbars
+```
+
+### Glass Effect for Custom Views
+```swift
+CustomPhotoGrid()
+    .glassBackgroundEffect() // Reflects surrounding content
+```
+
+### Search Tab Role
+```swift
+TabView {
+    SearchView()
+        .tabItem { Label("Search", systemImage: "magnifyingglass") }
+        .tabRole(.search) // Separates from tabs, morphs into search
+}
+```
+
+### Tab Bar Minimization
+```swift
+TabView { ... }
+    .tabBarMinimizationBehavior(.onScrollDown) // Recedes on scroll
+```
+
+## Audit Checklist
+
+### Remove These (Interfere with Glass)
+```swift
+// Remove custom backgrounds on navigation
+NavigationView { }
+    .background(Color.blue.opacity(0.5)) // Remove
+
+// Remove custom blur effects
+.background(
+    VisualEffectView(effect: UIBlurEffect(style: .systemMaterial))
+) // Remove — let system handle
+
+// Remove hard-coded dimensions
+Slider(value: $volume)
+    .frame(width: 250, height: 44) // Remove — new metrics
+```
+
+### Update These
+```swift
+// Section headers: Use title-style capitalization
+Section(header: Text("User Settings")) { } // Not "user settings"
+
+// Forms: Use grouped style
+Form { ... }
+    .formStyle(.grouped) // Platform-optimized metrics
+```
+
+## Safe Area Considerations
+
+```swift
+// When glass extends edge-to-edge with .ignoresSafeArea()
+// Use .safeAreaPadding() for content (not .padding())
+
+ZStack {
+    RoundedRectangle(cornerRadius: 12)
+        .fill(.thinMaterial)
+        .ignoresSafeArea()
+
+    VStack {
+        content
+    }
+    .safeAreaPadding(.horizontal, 20) // Respects notch/home indicator
+}
+```
+
+## Testing Required
+
+1. **Light/dark modes** — Glass adapts independently
+2. **Reduce Transparency** — Glass becomes frostier
+3. **Increase Contrast** — Elements become black/white
+4. **Reduce Motion** — Elastic properties disabled
+5. **Dynamic Type** — Larger text sizes
+6. **Content scrolling** — Verify scroll edge effects
+
+## Platform-Specific Changes
+
+### iPad
+- Tab bar can adapt to sidebar
+- Resizable windows (UIRequiresFullscreen deprecated)
+- Menu bar via swipe down
+
+### macOS
+- Synchronized window resize animations
+- Window controls adapt automatically
+- Glassy sidebars reflect content
+
+### watchOS
+- Minimal changes, automatic adoption
+- Use standard toolbar APIs and button styles
+
+### tvOS
+- Focus-based glass appearance
+- Apple TV 4K 2nd gen+ required for full effects

package/skills/ios/ios-26-platform/references/backward-compat.md

@@ -0,0 +1,238 @@
+# Backward Compatibility
+
+**iOS 17/18 + iOS 26**
+
+## UIDesignRequiresCompatibility Key
+
+### Opt Out of Liquid Glass (Temporarily)
+```xml
+<!-- Info.plist -->
+<key>UIDesignRequiresCompatibility</key>
+<true/>
+```
+
+**Effect**:
+- App built with iOS 26 SDK
+- Appearance matches iOS 18 and earlier
+- Liquid Glass effects disabled
+- Previous blur/material styles used
+
+### Migration Strategy
+1. Ship with `UIDesignRequiresCompatibility` enabled
+2. Audit interface changes in separate build
+3. Update interface incrementally
+4. Remove key when ready for Liquid Glass
+
+## @available Patterns
+
+### Basic Check
+```swift
+if #available(iOS 26, *) {
+    content
+        .glassEffect()
+} else {
+    content
+        .background(.ultraThinMaterial)
+}
+```
+
+### View Modifier Pattern
+```swift
+extension View {
+    @ViewBuilder
+    func adaptiveGlass() -> some View {
+        if #available(iOS 26, *) {
+            self.glassEffect()
+        } else {
+            self.background(.regularMaterial)
+        }
+    }
+}
+
+// Usage
+Button("Action") { }
+    .adaptiveGlass()
+```
+
+### Toolbar Spacer Fallback
+```swift
+extension View {
+    @ViewBuilder
+    func adaptiveToolbar() -> some View {
+        if #available(iOS 26, *) {
+            self.toolbar {
+                ToolbarItemGroup(placement: .topBarTrailing) {
+                    Button("Up") { }
+                    Button("Down") { }
+                    Spacer(.fixed) // iOS 26 feature
+                    Button("Settings") { }
+                }
+            }
+        } else {
+            self.toolbar {
+                ToolbarItem(placement: .topBarTrailing) {
+                    Button("Up") { }
+                }
+                ToolbarItem(placement: .topBarTrailing) {
+                    Button("Down") { }
+                }
+                ToolbarItem(placement: .topBarTrailing) {
+                    Button("Settings") { }
+                }
+            }
+        }
+    }
+}
+```
+
+## WebView Fallback
+
+```swift
+struct ArticleView: View {
+    let url: URL
+
+    var body: some View {
+        if #available(iOS 26, *) {
+            WebView(url: url)
+        } else {
+            WebViewRepresentable(url: url) // UIViewRepresentable wrapper
+        }
+    }
+}
+
+// iOS 17/18 fallback
+struct WebViewRepresentable: UIViewRepresentable {
+    let url: URL
+
+    func makeUIView(context: Context) -> WKWebView {
+        WKWebView()
+    }
+
+    func updateUIView(_ webView: WKWebView, context: Context) {
+        webView.load(URLRequest(url: url))
+    }
+}
+```
+
+## @Animatable Fallback
+
+```swift
+#if swift(>=6.0)
+@Animatable
+struct ModernShape: Shape {
+    var progress: Double
+
+    @AnimatableIgnored
+    var style: ShapeStyle
+}
+#else
+struct LegacyShape: Shape {
+    var progress: Double
+
+    var animatableData: Double {
+        get { progress }
+        set { progress = newValue }
+    }
+}
+#endif
+```
+
+## Search Tab Role Fallback
+
+```swift
+TabView {
+    if #available(iOS 26, *) {
+        SearchView()
+            .tabItem { Label("Search", systemImage: "magnifyingglass") }
+            .tabRole(.search)
+    } else {
+        SearchView()
+            .tabItem { Label("Search", systemImage: "magnifyingglass") }
+    }
+}
+```
+
+## AttributedString TextEditor
+
+```swift
+struct CommentEditor: View {
+    @State private var richText = AttributedString("Comment")
+    @State private var plainText = "Comment"
+
+    var body: some View {
+        if #available(iOS 26, *) {
+            TextEditor(text: $richText) // Rich text support
+        } else {
+            TextEditor(text: $plainText) // Plain text only
+        }
+    }
+}
+```
+
+## Migration from Previous Materials
+
+### From UIBlurEffect
+```swift
+// Before (UIKit)
+let blurEffect = UIBlurEffect(style: .systemMaterial)
+let blurView = UIVisualEffectView(effect: blurEffect)
+
+// After (SwiftUI with fallback)
+extension View {
+    @ViewBuilder
+    func adaptiveMaterial() -> some View {
+        if #available(iOS 26, *) {
+            self.glassEffect()
+        } else {
+            self.background(.regularMaterial)
+        }
+    }
+}
+```
+
+### From Custom Materials
+Keep custom materials when:
+- Backward compatibility with iOS < 26 required
+- Specific artistic effect not achievable with glass
+- Non-standard UI paradigm
+
+## Testing Checklist
+
+### iOS 26 Tests
+- [ ] Liquid Glass appearance correct
+- [ ] Scroll edge effects working
+- [ ] Toolbar grouping renders properly
+- [ ] Search placement is platform-appropriate
+- [ ] Accessibility settings respected
+
+### iOS 17/18 Tests
+- [ ] Fallback materials render correctly
+- [ ] No runtime crashes from @available checks
+- [ ] Functionality preserved without glass
+- [ ] Layout doesn't break
+
+## Deprecated APIs
+
+### iPadOS 26
+```xml
+<!-- Remove entirely — deprecated in iPadOS 26 -->
+<key>UIRequiresFullscreen</key>
+```
+Apps must support resizable windows on iPad.
+
+### SwiftUI Updates
+```swift
+// Old (deprecated)
+.onChange(of: value, perform: { newValue in })
+
+// New (iOS 17+)
+.onChange(of: value) { oldValue, newValue in }
+```
+
+## Performance Considerations
+
+When supporting multiple iOS versions:
+- Use `@available` checks at view level, not inside body
+- Prefer conditional view modifiers over entire view branches
+- Test performance on oldest supported version
+- Profile with Instruments on both old and new iOS

package/skills/ios/ios-26-platform/references/liquid-glass.md

@@ -0,0 +1,255 @@
+# Liquid Glass Design System
+
+**iOS 26+, iPadOS 26+, macOS Tahoe+, visionOS 3+**
+
+## What is Liquid Glass?
+
+Apple's next-generation material that dynamically bends light (lensing) rather than scattering it. Unlike blur effects, Liquid Glass:
+- Moves organically like lightweight liquid
+- Adapts automatically to size, environment, and light/dark modes
+- Provides separation through instinctive visual cues
+
+## Visual Properties
+
+### Lensing (Primary Characteristic)
+```swift
+// Glass warps and bends light in real-time
+Text("Hello")
+    .glassEffect() // Lensing effect, not blur
+```
+- Concentrates and shapes light dynamically
+- Elements feel ultra-lightweight yet distinguishable
+- Materializes in/out by modulating light bending (not fading)
+
+### Motion & Fluidity
+- Instant flex and energize on interaction
+- Gel-like flexibility for transient UI
+- Dynamic morphing between app states
+- Lightweight transitions (menus pop open in-line)
+
+### Adaptive Behavior
+- Shadows increase when text scrolls underneath
+- Independently switches light/dark per element
+- Larger elements (menus, sidebars) simulate thicker material
+- Ambient environment subtly spills onto surface
+
+## Variants: Regular vs Clear
+
+**CRITICAL**: Never mix Regular and Clear in the same interface.
+
+### Regular Variant (Default - Use 95% of Time)
+```swift
+// Regular is the default — most versatile
+NavigationView {
+    Content()
+}
+.glassEffect() // Full adaptive effects, auto-legibility
+
+// With custom shape
+Button("Tap Me") { }
+    .glassEffect(in: RoundedRectangle(cornerRadius: 12))
+```
+- Works in any size, over any content
+- Provides legibility regardless of context
+- Anything can be placed on top
+
+### Clear Variant (Special Cases Only)
+```swift
+// Use ONLY when ALL THREE conditions are met:
+// 1. Over media-rich content
+// 2. Dimming layer acceptable
+// 3. Content above is bold and bright
+
+ZStack {
+    VideoPlayer(player: player)
+        .overlay(.black.opacity(0.3)) // Required dimming layer
+
+    PlayButton()
+        .glassEffect(.clear) // Clear variant
+}
+```
+
+**WARNING**: Clear without meeting all three conditions = poor legibility.
+
+## Layer Architecture
+
+### Navigation Layer (Use Glass Here)
+```swift
+// Correct — glass on navigation elements
+.toolbar {
+    ToolbarItem {
+        Button("Add") { }
+            .glassEffect()
+    }
+}
+```
+
+### Content Layer (No Glass)
+```swift
+// Wrong — don't apply glass to content
+List(items) { item in
+    ItemRow(item)
+        .glassEffect() // Never do this
+}
+```
+
+## DO: Best Practices
+
+```swift
+// Reserve glass for navigation layer
+TabView { ... } // Gets glass automatically
+
+// Use fills for elements ON TOP of glass
+ZStack {
+    NavigationBar()
+        .glassEffect()
+
+    FloatingButton()
+        .foregroundStyle(.primary) // Fills, not glass
+}
+
+// Use adaptive tinting for primary actions
+Button("View Bag") { }
+    .tint(.red)
+    .glassEffect()
+```
+
+## DON'T: Common Mistakes
+
+```swift
+// Don't stack glass on glass
+ZStack {
+    Toolbar().glassEffect()
+    Button().glassEffect() // Wrong
+}
+
+// Don't use solid fills on glass
+Button("Action") { }
+    .background(.red) // Breaks glass character
+    .glassEffect()
+
+// Don't tint everything
+VStack {
+    Button("A").tint(.blue).glassEffect()
+    Button("B").tint(.green).glassEffect() // No hierarchy
+}
+```
+
+## Scroll Edge Effects
+
+```swift
+ScrollView {
+    Content()
+}
+.scrollEdgeEffectStyle(.hard, for: .top) // Uniform effect
+
+// .soft for gradual fade
+// .hard for pinned accessories
+// .automatic for system default
+```
+
+## Accessibility
+
+All features automatic when using glass:
+- **Reduced Transparency**: Makes glass frostier
+- **Increased Contrast**: Black/white with contrasting border
+- **Reduced Motion**: Decreases effect intensity
+
+## GlassEffectContainer
+
+Group multiple glass effects for performance and morphing animations:
+
+```swift
+GlassEffectContainer(spacing: 8) {
+    HStack(spacing: 8) {
+        Button { } label: { Image(systemName: "plus") }
+            .glassEffect()
+            .glassEffectID("add", in: namespace)
+
+        Button { } label: { Image(systemName: "share") }
+            .glassEffect()
+            .glassEffectID("share", in: namespace)
+    }
+}
+```
+
+- Groups glass effects for better rendering performance
+- Enables morphing transitions between elements
+- Use `spacing` parameter to control when effects blend together
+
+## Morphing with glassEffectID
+
+Use `@Namespace` and `.glassEffectID()` for smooth morphing transitions:
+
+```swift
+@Namespace var namespace
+
+// Elements with same ID morph into each other during transitions
+if isExpanded {
+    ExpandedView()
+        .glassEffect()
+        .glassEffectID("panel", in: namespace)
+} else {
+    CollapsedView()
+        .glassEffect()
+        .glassEffectID("panel", in: namespace)
+}
+```
+
+## Interactive Glass
+
+Add touch response with `.interactive()` chained on the glass variant:
+
+```swift
+// Correct - chain .interactive() on the variant
+Button("Tap") { }
+    .glassEffect(.regular.interactive())
+
+// With tint
+Button("Tap") { }
+    .glassEffect(.regular.interactive().tint(.blue))
+
+// With custom shape
+Button("Tap") { }
+    .glassEffect(.regular.interactive(), in: .rect(cornerRadius: 12))
+```
+
+**Caution**: Avoid `.interactive()` on draggable rows - it can interfere with drag gestures.
+
+## Known Limitations
+
+**Drag previews**: Glass effects don't render correctly in drag previews. When using `.contentShape(.dragPreview, ...)`, the glass material won't appear during the lift animation. Use simple shapes for drag previews:
+
+```swift
+// Glass won't show in drag preview - this is expected
+MyGlassCard()
+    .glassEffect()
+    .contentShape(.dragPreview, RoundedRectangle(cornerRadius: 12))
+```
+
+## API Reference
+
+```swift
+// Basic glass effect
+func glassEffect<S: Shape>(
+    _ glass: Glass = .regular,
+    in shape: S = Capsule()
+) -> some View
+
+// Glass variant modifiers (chainable)
+Glass.regular.interactive()           // Adds touch response
+Glass.regular.tint(.color)            // Adds color tint
+Glass.regular.interactive().tint(.color) // Both
+
+// Morphing support
+func glassEffectID<ID: Hashable>(_ id: ID, in namespace: Namespace.ID) -> some View
+
+// Container for multiple effects
+GlassEffectContainer(spacing: CGFloat) { content }
+
+// For custom views (reflects surrounding content)
+func glassBackgroundEffect() -> some View
+
+// Scroll edge styling
+func scrollEdgeEffectStyle(_ style: ScrollEdgeStyle, for edges: Edge.Set) -> some View
+```