Communitygithub.com

SwiftUI 디버깅

SwiftUI 뷰 업데이트, 프리뷰 크래시 또는 레이아웃 문제를 디버깅할 때 사용합니다. 빠르게 근본 원인을 파악하고 압박 속에서 오진을 방지하는 진단 결정 트리를 제공합니다.

SwiftUI 디버깅란 무엇인가요?

이 스킬은 SwiftUI 개발자가 가장 흔히 겪는 세 가지 유형의 문제(뷰 미업데이트, 프리뷰 크래시, 레이아웃 문제)를 체계적으로 진단하고 해결하는 방법을 제공합니다. 각 문제 유형에 대해 관찰 가능한 증상에서 시작해 원인을 하나씩 배제해 나가는 결정 트리(Decision Tree) 방식을 사용합니다. 특히 Self._printChanges()와 같은 디버깅 도구 활용법, @Observable 매크로(iOS 17+)를 포함한 최신 관찰 패턴, 뷰 항등성 유지 기법 등 실무에 바로 적용 가능한 구체적인 코드 예제를 다룹니다. Xcode 26+, iOS 17+ 환경에 최적화되어 있지만 iOS 14-16 패턴도 함께 설명하며, 관련 스킬(axiom-xcode-debugging, axiom-swift-concurrency 등)과의 연계를 통해 더 복잡한 시나리오로 확장할 수 있습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ComeOnOliver/skillshub/tree/HEAD/skills/CharlesWiltgen/Axiom/axiom-swiftui-debugging

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

SwiftUI 디버깅은(는) 무엇을 하나요?

개요

SwiftUI 디버깅은 세 가지 범주로 나뉘며, 각각 다른 진단 접근 방식이 필요합니다:

  1. 뷰가 업데이트되지 않음 – 무언가를 변경했지만 뷰가 다시 그려지지 않습니다. 구조체 변경, 바인딩 항등성 상실, 의도치 않은 뷰 재생성, 옵저버 패턴 누락 중 어떤 것인지 식별하는 결정 트리입니다.
  2. 프리뷰 크래시 – 프리뷰가 컴파일되지 않거나 즉시 크래시가 발생합니다. 누락된 의존성, 상태 초기화 실패, Xcode 캐시 손상 중 원인을 구분하는 결정 트리입니다.
  3. 레이아웃 문제 – 뷰가 잘못된 위치, 잘못된 크기로 나타나거나 예상치 않게 겹칩니다. 일반적인 시나리오에 대한 빠른 참조 패턴입니다.

핵심 원칙: 관찰 가능한 증상에서 시작하여 체계적으로 테스트하고, 원인을 하나씩 제거하세요. 추측하지 마세요.

필요 환경: Xcode 26+, iOS 17+ (iOS 14-16 패턴도 여전히 유효하며, 참고 사항 참조) 관련 스킬: axiom-xcode-debugging (캐시 손상 진단), axiom-swift-concurrency (옵저버 패턴), axiom-swiftui-performance (Instruments 프로파일링), axiom-swiftui-layout (적응형 레이아웃 패턴)

예시 프롬프트

다음은 이 스킬이 답변하도록 설계된 실제 개발자 질문입니다:

1. "목록 항목에서 즐겨찾기 버튼을 탭해도 업데이트되지 않습니다. 데이터는 변경되었는데요."

→ 스킬이 구조체 변경, 바인딩 항등성 상실, 옵저버 누락 중 원인을 식별하는 결정 트리를 안내합니다.

2. "프리뷰가 'Cannot find AppModel in scope' 오류와 함께 크래시되지만, 컴파일은 정상입니다."

→ 스킬이 .environment() 또는 .environmentObject()를 사용하여 누락된 의존성을 제공하는 방법을 보여줍니다.

3. "불리언 값을 토글할 때마다 카운터가 0으로 리셋됩니다. 이유가 뭘까요?"

→ 스킬이 조건문으로 인한 의도치 않은 뷰 재생성을 식별하고 .opacity() 수정 방법을 보여줍니다.

4. "@Observable을 사용 중인데 프로퍼티를 변경해도 뷰가 업데이트되지 않습니다."

→ 스킬이 @State와 @Observable 객체의 일반 프로퍼티를 언제 사용해야 하는지 설명합니다.

5. "텍스트 필드에 입력을 시작하면 포커스가 사라집니다. 매우 짜증납니다."

→ 스킬이 ForEach 항등성 문제를 식별하고 안정적인 ID를 사용하는 방법을 보여줍니다.

SwiftUI 디버깅 사용 시점

이 스킬을 사용해야 할 때

  • ✅ 예상한 대로 뷰가 업데이트되지 않을 때
  • ✅ 프리뷰가 크래시되거나 로드되지 않을 때
  • ✅ 특정 기기에서 레이아웃이 잘못 보일 때
  • ✅ @ObservedObject를 아무 곳에나 임시방편으로 사용하고 싶을 때

대신 axiom-xcode-debugging을 사용해야 할 때

  • 앱이 (프리뷰가 아닌) 런타임에 크래시될 때
  • 빌드가 완전히 실패할 때
  • 환경 진단이 필요할 때

대신 axiom-swift-concurrency를 사용해야 할 때

  • async/await 또는 MainActor 관련 질문이 있을 때
  • 데이터 경합 경고가 있을 때

디버깅 도구

Self._printChanges()

SwiftUI는 뷰의 body가 호출된 이유를 이해할 수 있는 디버그 전용 메서드를 제공합니다.

LLDB에서 사용법:

// 뷰의 body에 중단점 설정
// LLDB 콘솔에서:
(lldb) expression Self._printChanges()

코드에 임시로 추가 (출시 전 제거):

var body: some View {
    let _ = Self._printChanges() // 디버그 전용

    Text("Hello")
}

출력 해석:

MyView: @self changed
  - 뷰 값 자체가 변경되었음을 의미 (뷰에 전달된 파라미터)

MyView: count changed
  - @State 프로퍼티 "count"가 업데이트를 트리거했음을 의미

MyView: (no output)
  - body가 호출되지 않음; 뷰가 전혀 업데이트되지 않음

⚠️ 중요:

  • 밑줄 접두사 → 향후 릴리스에서 제거될 수 있음
  • 절대 App Store에 제출하지 마세요 _printChanges 호출이 포함된 상태로
  • 성능 영향 → 디버깅 중에만 사용

사용 시점:

  • 뷰 업데이트의 정확한 트리거를 이해해야 할 때
  • 예상치 못한 업데이트를 조사할 때
  • 리팩토링 후 의존성을 확인할 때

참고: 복잡한 업데이트 패턴의 경우 SwiftUI Instrument 사용 → axiom-swiftui-performance 스킬 참조


뷰 업데이트 안 됨 결정 트리

가장 흔한 좌절: @State를 변경했지만 뷰가 다시 그려지지 않습니다. 근본 원인은 항상 다음 네 가지 중 하나입니다.

1단계: 최소 프리뷰에서 재현할 수 있나요?

#Preview {
  YourView()
}

예 → 문제는 코드에 있습니다. 2단계로 계속 진행하세요.

아니요 → Xcode 상태 또는 캐시 손상일 가능성이 높습니다. 프리뷰 크래시 섹션으로 건너뛰세요.

2단계: 근본 원인 진단

근본 원인 1: 구조체 변경 (Struct Mutation)

증상: @State 값을 직접 수정했지만 뷰가 업데이트되지 않습니다.

이유: SwiftUI는 구조체에 대한 직접 변경을 감지하지 못합니다. 전체 값을 재할당해야 합니다.

// ❌ 잘못됨: 직접 변경은 업데이트를 트리거하지 않음
@State var items: [String] = []

func addItem(_ item: String) {
    items.append(item)  // SwiftUI가 이 변경을 감지하지 못함
}

// ✅ 올바름: 재할당이 업데이트를 트리거함
@State var items: [String] = []

func addItem(_ item: String) {
    var newItems = items
    newItems.append(item)
    self.items = newItems  // 전체 재할당
}

// ✅ 또한 올바름: 바인딩 사용
@State var items: [String] = []

var itemsBinding: Binding<[String]> {
    Binding(
        get: { items },
        set: { items = $0 }
    )
}

해결 방법: 항상 전체 구조체 값을 재할당하고, 일부만 변경하지 마세요.


근본 원인 2: 바인딩 항등성 상실 (Lost Binding Identity)

증상: 자식 뷰에 바인딩을 전달했지만, 자식에서 변경해도 부모가 업데이트되지 않습니다.

이유: .constant()를 전달하거나 매번 새 바인딩을 생성하여 양방향 연결이 끊어졌습니다.

// ❌ 잘못됨: 상수 바인딩은 읽기 전용
@State var isOn = false

ToggleChild(value: .constant(isOn))  // 변경 사항 무시됨

// ❌ 잘못됨: 렌더링할 때마다 새 바인딩 생성
@State var name = ""

TextField("Name", text: Binding(
    get: { name },
    set: { name = $0 }
))  // 부모가 렌더링될 때마다 새 바인딩 객체 생성

// ✅ 올바름: 실제 바인딩 전달
@State var isOn = false

ToggleChild(value: $isOn)

// ✅ 올바름 (iOS 17+): @Observable 객체에는 @Bindable 사용
@Observable class Book {
    var title = "Sample"
    var isAvailable = true
}

struct EditView: View {
    @Bindable var book: Book  // $book.title 문법 활성화

    var body: some View {
        TextField("Title", text: $book.title)
        Toggle("Available", isOn: $book.isAvailable)
    }
}

// ✅ 또한 올바름 (iOS 17+): 로컬 변수로 @Bindable 사용
struct ListView: View {
    @State private var books = [Book(), Book()]

    var body: some View {
        List(books) { book in
            @Bindable var book = book  // 인라인 바인딩
            TextField("Title", text: $book.title)
        }
    }
}

// ✅ 올바름 (iOS 17 미만): 바인딩을 한 번만 생성하고 body에서 생성하지 않음
@State var name = ""
@State var nameBinding: Binding<String>?

var body: some View {
    if nameBinding == nil {
        nameBinding = Binding(
            get: { name },
            set: { name = $0 }
        )
    }
    return TextField("Name", text: nameBinding!)
}

해결 방법: 가능하면 $state를 직접 전달하세요. @Observable 객체(iOS 17+)의 경우 @Bindable을 사용하세요. 커스텀 바인딩을 생성하는 경우(iOS 17 미만), init에서 생성하거나 캐시하고 body에서는 생성하지 마세요.


근본 원인 3: 의도치 않은 뷰 재생성 (Accidental View Recreation)

증상: 뷰가 업데이트되지만 @State 값이 초기 상태로 리셋됩니다. 초기 값이 잠깐 나타나는 현상이 보입니다.

이유: 뷰가 새 항등성을 얻었습니다(조건문에서 제거, 컨테이너에서 이동, 또는 컨테이너 자체가 재생성됨). SwiftUI는 이를 새 뷰로 취급합니다.

// ❌ 잘못됨: 조건이 변경될 때 뷰 항등성 변경
@State var count = 0

var body: some View {
    VStack {
        if showCounter {
            Counter()  // showCounter가 변경될 때마다 새 항등성 획득
        }
        Button("Toggle") {
            showCounter.toggle()
        }
    }
}

// Counter가 재생성되고 @State count가 0으로 리셋됨

// ✅ 올바름: opacity 또는 hidden으로 항등성 유지
@State var count = 0

var body: some View {
    VStack {
        Counter()
            .opacity(showCounter ? 1 : 0)
        Button("Toggle") {
            showCounter.toggle()
        }
    }
}

// ✅ 또한 올바름: 조건부로 표시해야 한다면 id() 사용
@State var count = 0

var body: some View {
    VStack {
        if showCounter {
            Counter()
                .id("counter")  // 안정적인 항등성
        }
        Button("Toggle") {
            showCounter.toggle()
        }
    }
}

해결 방법: 조건문 대신 .opacity()를 사용하여 뷰 항등성을 유지하거나, 안정적인 식별자와 함께 .id()를 적용하세요.


근본 원인 4: 옵저버 패턴 누락 (Missing Observer Pattern)

증상: 객체가 변경되었지만, 이를 관찰하는 뷰가 업데이트되지 않습니다.

이유: SwiftUI가 객체의 변경 사항을 감시하도록 설정되지 않았습니다.

// ❌ 잘못됨: 프로퍼티 변경이 업데이트를 트리거하지 않음
class Model {
    var count = 0  // 관찰 가능하지 않음
}

struct ContentView: View {
    let model = Model()  // 렌더링될 때마다 새 인스턴스, 관찰 불가능

    var body: some View {
        Text("\(model.count)")
        Button("Increment") {
            model.count += 1  // 뷰가 업데이트되지 않음
        }
    }
}

// ✅ 올바름 (iOS 17+): @State와 함께 @Observable 사용
@Observable class Model {
    var count = 0  // @Published 불필요
}

struct ContentView: View {
    @State private var model = Model()  // @State, @StateObject 아님

    var body: some View {
        Text("\(model.count)")
        Button("Increment") {
            model.count += 1  // 뷰 업데이트됨
        }
    }
}

// ✅ 올바름 (iOS 17+): 주입된 @Observable 객체
struct ContentView: View {
    var model: Model  // 일반 프로퍼티

    var body: some View {
        Text("\(model.count)")  // count가 변경되면 뷰 업데이트됨
    }
}

// ✅ 올바름 (iOS 17+): @Observable을 environment와 함께 사용
@Observable class AppModel {
    var count = 0
}

@main
struct MyApp: App {
    @State private var model = AppModel()

    var body: some Scene {
        WindowGroup {
            ContentView()
                .environment(model)  // 환경에 추가
        }
    }
}

struct ContentView: View {
    @Environment(AppModel.self) private var model  // 환경에서 읽기

    var body: some View {
        Text("\(model.count)")
    }
}

// ✅ 올바름 (iOS 17 미만): @StateObject/ObservableObject 사용
class Model: ObservableObject {
    @Published var count = 0
}

struct ContentView: View {
    @StateObject var model = Model()  // 소유한 인스턴스

    var body: some View {
        Text("\(model.count)")
        Button("Increment") {
            model.count += 1  // 뷰 업데이트됨
        }
    }
}

// ✅ 올바름 (iOS 17 미만): 주입된 인스턴스에는 @ObservedObject 사용
struct ContentView: View {
    @ObservedObject var model: Model  // 부모로부터 전달됨

    var body: some View {
        Text("\(model.count)")
    }
}

해결 방법 (iOS 17+): 클래스에 @Observable 매크로를 사용한 다음, @State로 저장하세요. 뷰는 읽는 프로퍼티의 의존성을 자동으로 추적합니다.

해결 방법 (iOS 17 미만): 객체를 소유한 경우 @StateObject, 주입된 경우 @ObservedObject, 트리 전체에서 공유되는 경우 @EnvironmentObject를 사용하세요.

@Observable이 더 나은 이유 (iOS 17+):

  • 자동 의존성 추적 (읽기 작업만 업데이트 트리거)
  • @Published 래퍼 불필요
  • @StateObject 대신 @State와 함께 작동
  • @ObservedObject 대신 일반 프로퍼티로 전달 가능

참고: Managing model data in your app


결정 트리 요약

digraph view_not_updating {
    start [label="뷰가 업데이트되지 않음?" shape=diamond];
    reproduce [label="프리뷰에서 재현 가능?" shape=diamond];
    cause [label="무엇이 변경되었나?" shape=diamond];

    start -> reproduce;
    reproduce -> cause [label="예: 코드 버그"];
    reproduce -> "캐시/Xcode 상태 → 프리뷰 크래시" [label="아니요"];

    cause -> "구조체 변경" [label="직접 구조체 수정"];
    cause -> "바인딩 항등성 상실" [label="자식에 바인딩 전달"];
    cause -> "의도치 않은 재생성" [label="조건문 안의 뷰"];
    cause -> "옵저버 누락" [label="객체 변경됨, 뷰는 안 됨"];
}

프리뷰 크래시 결정 트리

프리뷰가 로드되지 않거나 즉시 크래시되는 경우, 세 가지 근본 원인이 있습니다.

1단계: 오류는 무엇인가요?

오류 유형 1: "Cannot find in scope" 또는 "No such module"

근본 원인: 프리뷰에 필요한 의존성(@EnvironmentObject, @Environment, 가져온 모듈)이 누락되었습니다.

// ❌ 잘못됨: ContentView에 모델이 필요하지만 프리뷰가 제공하지 않음
struct ContentView: View {
    @EnvironmentObject var model: AppModel

    var body: some View {
        Text(model.title)
    }
}

#Preview {
    ContentView()  // 크래시: model을 찾을 수 없음
}

// ✅ 올바름: 의존성 제공
#Preview {
    ContentView()
        .environmentObject(AppModel())
}

// ✅ 또한 올바름: 누락된 임포트 확인
// 커스텀 타입을 사용하는 경우, 프리뷰 파일에서 임포트되었는지 확인

#Preview {
    MyCustomView()  // MyCustomView가 정의되었거나 임포트되었는지 확인
}

해결 방법: 오류를 추적하여 누락된 것을 찾고, 프리뷰에 제공하세요.


오류 유형 2: 치명적 오류 또는 조용한 크래시 (오류 메시지 없음)

근본 원인: 런타임에 상태 초기화가 실패했습니다. 뷰가 존재하지 않는 데이터에 접근하려고 했습니다.

// ❌ 잘못됨: 런타임에 인덱스 범위 초과
struct ListView: View {
    @State var selectedIndex = 10
    let items = ["a", "b", "c"]

    var body: some View {
        Text(items[selectedIndex])  // 크래시: 인덱스 10이 없음
    }
}

// ❌ 잘못됨: 옵셔널 강제 언래핑 실패
struct DetailView: View {
    @State var data: Data?

    var body: some View {
        Text(data!.title)  // data가 nil이면 크래시
    }
}

// ✅ 올바름: 안전한 기본값
struct ListView: View {
    @State var selectedIndex = 0  // 유효한 인덱스
    let items = ["a", "b", "c"]

    var body: some View {
        if selectedIndex < items.count {
            Text(items[selectedIndex])
        }
    }
}

// ✅ 올바름: 옵셔널 처리
struct DetailView: View {
    @State var data: Data?

    var body: some View {
        if let data = data {
            Text(data.title)
        } else {
            Text("데이터 없음")
        }
    }
}

해결 방법: 강제 언래핑(!)을 찾아 제거하고, 안전한 기본값을 사용하며, 옵셔널을 적절히 처리하세요.


오류 유형 3: 프리뷰 캔버스에 "렌더링 실패" 또는 빈 화면

근본 원인: Xcode 프리뷰 캐시가 손상되었거나, 프리뷰 프로세스가 알 수 없는 이유로 충돌했습니다.

해결 방법:

  1. 프리뷰 캐시 지우기

    • Xcode 메뉴: Product → Clear All Preview Cache
    • 또는: 프로젝트 폴더에서 ~/Library/Developer/Xcode/UserData/Previews 삭제
  2. 빌드 폴더 정리

    xcodebuild clean build -scheme YourScheme
    
  3. 작업 재개

    • Editor → Canvas → Refresh All Previews
    • 그래도 안 되면 Xcode 재시작
  4. 마지막 수단

    • Mac 재시동
    • ~/Library/Caches/com.apple.dt.Xcode 삭제

해결 방법: 위 방법들을 순서대로 시도하세요. 일반적으로 캐시 지우기가 문제를 해결합니다.


결정 트리 요약

digraph preview_crashes {
    start [label="프리뷰 크래시?" shape=diamond];
    error_type [label="오류 유형:" shape=box];
    scope [label="범위/모듈 누락"];
    silent [label="조용한 크래시"];
    cache [label="프리뷰 렌더링 실패"];

    start -> error_type;
    error_type -> scope [label="Cannot find in scope / No such module"];
    error_type -> silent [label="치명적 오류 / 메시지 없음"];
    error_type -> cache [label="렌더링 실패 / 빈 화면"];

    scope -> "의존성 제공 (.environment 등)";
    silent -> "강제 언래핑 제거, 안전한 기본값 사용";
    cache -> "프리뷰 캐시 지우기, 빌드 폴더 정리";
}

레이아웃 문제 빠른 참조

다음은 프리뷰나 시뮬레이터에서 즉시 확인할 수 있는 일반적인 레이아웃 문제 패턴입니다.

패턴 1: 뷰가 화면 밖으로 나감

증상: 뷰가 화면 가장자리를 넘어 확장됩니다.

// ❌ 잘못됨: 컨테이너에 뷰가 맞지 않음
HStack {
    Text("긴 텍스트...")
    Spacer()
    Button("확인") { }
}

// ✅ 올바름: 텍스트 줄 바꿈 허용
HStack {
    Text("긴 텍스트...")
        .lineLimit(2)  // 또는 .fixedSize(horizontal: true, vertical: false)
    Spacer()
    Button("확인") { }
}

// ✅ 또한 올바름: 오버플로우 방지를 위해 공간 제한
HStack {
    Text("긴 텍스트...")
        .frame(maxWidth: .infinity, alignment: .leading)
    Button("확인") { }
}

패턴 2: VStack/HStack의 예상치 않은 간격

증상: 뷰 사이에 예상보다 더 많은 또는 적은 공간이 있습니다.

// ❌ 잘못됨: Spacer() 누락
VStack {
    Text("상단")
    Text("하단")  // 바로 아래에 붙음
}

// ✅ 올바름: Spacer()로 공간 채우기
VStack {
    Text("상단")
    Spacer()
    Text("하단")
}

// ❌ 잘못됨: .frame()과 불일치하는 패딩
Text("Hello")
    .frame(height: 50)
    .padding(.bottom, 20)  // .frame() 안의 공간과 충돌

// ✅ 올바름: 일관된 공간 사용
Text("Hello")
    .padding(.bottom, 20)  // frame 없이 padding만 사용

패턴 3: ZStack 정렬 문제

증상: ZStack의 뷰가 예상과 다른 위치에 정렬됩니다.

// ❌ 잘못됨: 기본 정렬이 .center임
ZStack {
    Image("background")  // 전체 채움
    Text("Hello")  // 중앙
    Button("닫기") { }  // 중앙, 겹침
}

// ✅ 올바름: 명시적 정렬
ZStack(alignment: .topLeading) {
    Image("background")
        .resizable()
        .ignoresSafeArea()
    Text("Hello")
        .padding()
    Button("닫기") { }
        .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .topTrailing)
        .padding()
}

패턴 4: GeometryReader로 인한 예상치 않은 크기

증상: GeometryReader를 사용할 때 뷰가 너무 작거나 큽니다.

// ❌ 잘못됨: GeometryReader가 사용 가능한 모든 공간을 차지함
var body: some View {
    GeometryReader { geometry in
        Text("너비: \(geometry.size.width)")
    }
    .background(Color.blue)  // GeometryReader가 전체 공간을 채움
}

// ✅ 올바름: GeometryReader에 크기 제한
var body: some View {
    GeometryReader { geometry in
        Text("너비: \(geometry.size.width)")
    }
    .frame(height: 100)  // 높이 제한
    .background(Color.blue)
}

// ✅ 올바름: 명시적 프레임 없이 preferredSize 사용
var body: some View {
    MyCustomView()
        .fixedSize()  // 뷰의 이상적인 크기 사용
}

패턴 5: 아이폰 vs 아이패드 레이아웃 불일치

증상: 아이패드에서 뷰가 예상과 다르게 보입니다.

// ❌ 잘못됨: 아이패드에서 너무 넓게 퍼짐
Text("Hello")
    .frame(maxWidth: .infinity)

// ✅ 올바름: 읽기 쉬운 너비로 제한
Text("Hello")
    .frame(maxWidth: 400)  // 아이패드에서도 너무 넓지 않음

// ❌ 잘못됨: 아이패드에서 뷰가 세로로 늘어남
VStack {
    HStack {
        Text("왼쪽")
        Spacer()
        Text("오른쪽")
    }
}

// ✅ 올바름: 명시적 프레임 또는 크기 클래스 사용
struct MyView: View {
    @Environment(\.horizontalSizeClass) var sizeClass

    var body: some View {
        if sizeClass == .compact {
            VStack {
                Text("좁은 레이아웃")
            }
        } else {
            HStack {
                Text("넓은 레이아웃")
            }
        }
    }
}

패턴 6: 상태 표시줄 또는 세이프 에어리어 문제

증상: 뷰가 상태 표시줄 아래에서 시작하거나, 위젯과 겹칩니다.

// ❌ 잘못됨: 세이프 에어리어 무시로 겹침
Color.blue
    .ignoresSafeArea()
    .overlay(Text("위젯"))  // 상태 표시줄과 겹침

// ✅ 올바름: 세이프 에어리어 고려
Color.blue
    .ignoresSafeArea(edges: .bottom)  // 상단은 세이프 에어리어 유지

// ✅ 올바름: 세이프 에어리어 인셋 사용
VStack {
    Text("내용")
        .padding(.top, 20)  // 수동 세이프 에어리어
}

// ✅ 올바름: @Environment 세이프 에어리어 사용 (iOS 17+)
struct MyView: View {
    @Environment(\.safeAreaInsets) var safeAreaInsets

    var body: some View {
        Text("안전한 영역")
            .padding(.top, safeAreaInsets.top)
    }
}

모범 사례 요약

뷰 업데이트 문제 방지

패턴iOS 17+ 방법iOS 17 미만 방법
관찰 가능한 객체@Observable + @StateObservableObject + @StateObject
의존성 주입@Environment(T.self)@EnvironmentObject
자식에서 부모 업데이트$state 또는 @BindableObservedObject 또는 Binding
뷰 항등성 유지.opacity(), .id().opacity(), .id()

프리뷰 크래시 방지

  1. 프리뷰에 항상 필요한 의존성 제공
  2. 강제 언래핑 제거, 안전한 기본값 사용
  3. 주기적으로 프리뷰 캐시 지우기

레이아웃 문제 방지

  1. 명시적 프레임과 정렬 사용 (기본값에 의존하지 않음)
  2. 세이프 에어리어 존중 (무시하기보다는)
  3. 프레임 제한 없이 GeometryReader를 사용하면 전체 공간을 차지함을 명심
  4. 아이패드 레이아웃은 크기 클래스로 처리

관련 문서

관련 스킬:

  • axiom-xcode-debugging - Xcode 캐시 손상 진단 및 환경 문제
  • axiom-swift-concurrency - async/await, MainActor, 데이터 경합
  • axiom-swiftui-performance - Instruments 프로파일링, 성능 최적화
  • axiom-swiftui-layout - 적응형 레이아웃 패턴

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ComeOnOliver/skillshub

Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Use when the user wants to build a presentation, convert a PPT/PPTX to web, or create slides for a talk/pitch. Helps non-designers discover their aesthetic through visual exploration rather than abstract choices.

ComeOnOliver/skillshub

Next.js 16+ 和 Turbopack — 增量打包、文件系统缓存、开发速度,以及何时使用 Turbopack 与 webpack。

ComeOnOliver/skillshub

SwiftUI architecture patterns, state management with @Observable, view composition, navigation, performance optimization, and modern iOS/macOS UI best practices.

ComeOnOliver/skillshub

See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- extract frames, build visual/semantic/temporal indexes, and search moments with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio, video), and create real time alerts for events from live streams or desktop capture.

ComeOnOliver/skillshub

AI-assisted video editing workflows for cutting, structuring, and augmenting real footage. Covers the full pipeline from raw capture through FFmpeg, Remotion, ElevenLabs, fal.ai, and final polish in Descript or CapCut. Use when the user wants to edit video, cut footage, create vlogs, or build video content.

ComeOnOliver/skillshub

Next.js 15 애플리케이션을 위한 프론트엔드 개발 가이드라인. React 19, TypeScript, Shadcn/ui, Tailwind CSS를 사용한 모던 패턴. Server Components, Client Components, App Router, 파일 구조, Shadcn/ui 컴포넌트, 성능 최적화, TypeScript 모범 사례 포함. 컴포넌트, 페이지, 기능 생성, 데이터 페칭, 스타일링, 라우팅, 프론트엔드 코드 작업 시 사용.

ComeOnOliver/skillshub

Provides Tamagui patterns for config v4, compiler optimization, styled context, and cross-platform styling. Must use when working with Tamagui projects (tamagui.config.ts, @tamagui imports).

ComeOnOliver/skillshub

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

ComeOnOliver/skillshub

Create high-converting, visually distinctive landing pages. Use when building marketing pages, product launches, SaaS homepages, or any single-page conversion-focused website. Guides section-by-section composition with anti-AI-slop principles.

ComeOnOliver/skillshub

Auto-loaded context for Portfolio Buddy 2 development. Use for ANY task involving: React 19 development, TypeScript, portfolio analysis features, metrics calculations, trading strategy comparison, or working with the Portfolio Buddy 2 codebase. Contains tech stack, known issues, and architectural constraints.

ComeOnOliver/skillshub

Next.js development tooling via MCP. Inspect routes, components, build info, and debug Next.js apps. Use when working on Next.js applications, debugging routing, or inspecting app structure. NOT for general React or non-Next.js projects.

ComeOnOliver/skillshub

Implement UI using Shadcn MCP (atoms/theme) and 21st.dev MCP (complex sections). Use when adding buttons, layouts, or generating landing pages.

ComeOnOliver/skillshub

A conceptual skill for building an API client in Next.js that handles JWT tokens

ComeOnOliver/skillshub

Best practices and patterns for Next.js App Router, Server Actions, and Routing in this project.

ComeOnOliver/skillshub

The Design System, Theme, and UX rules for the Physical AI Hub.

ComeOnOliver/skillshub

Comprehensive frontend development skill for building modern, performant web applications using ReactJS, NextJS, TypeScript, Tailwind CSS. Includes component scaffolding, performance optimization, bundle analysis, and UI best practices. Use when developing frontend features, optimizing performance, implementing UI/UX designs, managing state, or reviewing frontend code.

ComeOnOliver/skillshub

This document captures learnings from fixing keyboard navigation issues when floating components (Select, DropdownMenu, Popover) have CSS open/close animations.

ComeOnOliver/skillshub

Build Next.js 16 applications with correct patterns and distinctive design. Use when creating pages, layouts, dynamic routes, upgrading from Next.js 15, or implementing proxy.ts. Covers breaking changes (async params/searchParams, Turbopack, cacheComponents) and frontend aesthetics. NOT when building non-React or backend-only applications.

ComeOnOliver/skillshub

Comprehensive Framer Motion animation library for React. Covers motion components, variants, gestures, page transitions, and scroll animations. Use when adding animations to React/Next.js applications.

ComeOnOliver/skillshub

Build interfaces that resonate, not just render. This skill enforces bold, intentional

관련 스킬