platform-gotchas

Platform Gotchas

iOS development has quirks that Claude Code's training data may not cover, especially for iOS 26 and Liquid Glass. When you hit one, document it immediately so you never hit it again.

The Pattern

Add a ## Known Gotchas section to your CLAUDE.md. Every time you or Claude Code discovers a platform-specific issue, add it as a one-liner. This section grows over the life of your project.

## Known Gotchas
- NO .background() before .glassEffect() — causes rendering issues
- NavigationStack inside TabView, not the other way around
- @Query must be used in views, not in ViewModels
- SwiftData @Model classes must be final
- [Add new gotchas here as you discover them]

Seed Gotchas (Known Issues as of iOS 26)

Start every new project CLAUDE.md with these. Sourced from community experience:

SwiftUI

- Use @Observable macro, not ObservableObject (iOS 17+)
- @Query properties only work in SwiftUI views, not in standalone classes
- NavigationStack must be inside TabView, never wrap TabView in NavigationStack
- .searchable modifier must be inside NavigationStack to render correctly
- .sheet and .fullScreenCover retain their content view, beware of state leaks
- GeometryReader is rarely needed — use layout priorities and flexible frames first
- .task modifier cancels automatically on view disappear (preferred over .onAppear)
- List selection requires NavigationSplitView on iPad, NavigationStack on iPhone
- Text(AttributedString) silently drops paragraphStyle — even with the \.uiKit AttributedScopes requested, SwiftUI's Text doesn't honor NSParagraphStyle.minimumLineHeight / maximumLineHeight on multi-line strings; bridge to UILabel via UIViewRepresentable when you need an absolute line-height lock
- .lineSpacing(N) is additive, not absolute — it adds to the font's natural line height; there is no SwiftUI-native way to lock multi-line text to an exact line height
- UIFont.systemFont(...) ignores scene-level .fontDesign(.rounded) — when bridging to UIKit, resolve fontDescriptor.withDesign(.rounded) explicitly or your bridged label renders in default SF Pro while the rest of the app stays Rounded
- Canvas without an explicit .frame() grows to fill its GeometryReader and can intercept hit-tests via its backing layer — add .allowsHitTesting(false) to render-only Canvas surfaces or taps meant for views below it get eaten
- @FocusState on a vertical-axis TextField (axis: .vertical) is unreliable for keyboard dismissal — setting it to false doesn't always lower the keyboard; pair with window.endEditing(true) via the UIKit responder chain as a fallback
- .frame(maxWidth: .infinity) on a frosted-glass capsule with leading-aligned inner content leaves visible empty trailing space — for snug-fit bars, omit maxWidth so the capsule shrinks to its content
- SwiftUI's Text body type-checker can stack-overflow on monolithic bodies — extract nested view chunks into @ViewBuilder properties or wrap conditional sub-trees in AnyView when the compiler complains