🌤 Build Your Own Weather Widget
Challenge

⭐ Difficulty: ⭐⭐⭐ ⏱️ Est. Time: 2-3h 📂 App Frameworks

Following Apple HIG Widget Design Guidelines, we'll build a working interactive weather widget with SwiftUI.

📅 2025.02 ⏱ Estimated 2 Hours 📱 iOS 17+ / Xcode 15+ 🎯 초급 → 중급

🔄 성장고리 커리큘럼

Follow the 5-stage growth path to master the complete widget development process.

📖

Ring 1 · 이해하기

HIG 위젯 guidelines 학습

Glanceable, Relevant, Personalized — The 3 Principles of Widgets

🏗️

Ring 2 · 뼈대 잡기

Widget Extension Basic Structure

Core architecture: TimelineProvider, Entry, and View

🎨

Ring 3 · 꾸미기

HIG 준수 UI 디자인

크기별 레이아웃, 다크모드, 틴트 대응

⚡

Ring 4 · 연결하기

데이터 & 인터랙션

날씨 API 연동, 인터랙티브 버튼, 딥링크

🚀

Ring 5 · 완성하기

설정 & 퍼스널라이즈

App Intent 설정, 잠금 화면 위젯

📖 Ring 1 — HIG Widget Guidelines

Apple은 위젯을 "미니 앱"이 아니라 앱의 핵심 정보를 홈 화면에 투영하는 것. Users check their home screen over 90 times a day on average, but only stay for a few seconds.

🍎 HIG Core Principles 3가지

1. Glanceable (한눈에 파악)
Users should be able to grasp key information within seconds.

2. Relevant (시의적절)
Show information relevant to the time, place, and user context.

3. Personalized (개인화)
Let users customize through widget configuration.

✅ Do

콘텐츠가 주인공 — 큰 숫자, 명확한 아이콘
크기별로 other 레이아웃 제공
다크모드/틴트 자동 대응
containerBackground로 배경 처리

❌ Don't

작은 크기에 너무 많은 정보
로딩 스피너 표시
앱 아이콘/이름 반복
실시간 초 단위 업데이트

🏗️ Ring 2 — Widget Extension Basic Structure

WidgetKit operates on a 3-layer architecture: TimelineProvider → TimelineEntry → View.

Step 2-1: 날씨 데이터 모델

WeatherData.swift Swift

import Foundation

struct WeatherData {
    let cityName: String
    let temperature: Int
    let highTemperature: Int
    let lowTemperature: Int
    let condition: WeatherCondition
    let humidity: Int
    let windSpeed: Double
    let hourlyForecast: [HourlyWeather]
}

enum WeatherCondition: String, CaseIterable {
    case sunny = "맑음"
    case cloudy = "흐림"
    case rainy = "비"
    case snowy = "눈"
    case stormy = "뇌우"
    
    var symbol: String {
        switch self {
        case .sunny:  "sun.max.fill"
        case .cloudy: "cloud.fill"
        case .rainy:  "cloud.rain.fill"
        case .snowy:  "cloud.snow.fill"
        case .stormy: "cloud.bolt.rain.fill"
        }
    }
}

struct HourlyWeather: Identifiable {
    let id = UUID()
    let hour: String
    let temperature: Int
    let condition: WeatherCondition
}

Step 2-2: Implement AppIntentTimelineProvider (iOS 17+)

iOS 17부터 AppIntentTimelineProvider integrates with App Intents, letting users customize widgets.

WeatherProvider.swift Swift

import WidgetKit
import SwiftUI
import AppIntents

struct WeatherEntry: TimelineEntry {
    let date: Date
    let weather: WeatherData
    let configuration: SelectCityIntent
}

// iOS 17+ AppIntentTimelineProvider (async/await 기반)
struct WeatherProvider: AppIntentTimelineProvider {
    
    // 위젯 갤러리 미리보기용
    func placeholder(in context: Context) -> WeatherEntry {
        WeatherEntry(date: .now, weather: .preview, configuration: SelectCityIntent())
    }
    
    // 위젯 추가 시 스냅샷 (async)
    func snapshot(for configuration: SelectCityIntent, in context: Context) async -> WeatherEntry {
        let weather = await WeatherService.shared.fetchWeather(for: configuration.city)
        return WeatherEntry(date: .now, weather: weather, configuration: configuration)
    }
    
    // 실제 타임라인 생성 (async)
    func timeline(for configuration: SelectCityIntent, in context: Context) async -> Timeline<WeatherEntry> {
        let weather = await WeatherService.shared.fetchWeather(for: configuration.city)
        let entry = WeatherEntry(date: .now, weather: weather, configuration: configuration)
        
        // 15분 후 다음 갱신
        let nextUpdate = Calendar.current.date(byAdding: .minute, value: 15, to: .now)!
        
        return Timeline(entries: [entry], policy: .after(nextUpdate))
    }
}

✅

Ring 2 체크포인트

The TimelineProvider fetches weather data, creates entries, and sets a 15-minute refresh policy.

🎨 Ring 3 — HIG-Compliant UI Design

Implement size-optimized layouts and gradient backgrounds based on weather conditions.

Step 3-1: Small 위젯 뷰

SmallWeatherView.swift Swift

struct SmallWeatherView: View {
    let weather: WeatherData
    
    var body: some View {
        VStack(alignment: .leading, spacing: 4) {
            // HIG: 콘텐츠가 주인공
            Image(systemName: weather.condition.symbol)
                .font(.title2)
                .symbolRenderingMode(.multicolor)
            
            Spacer()
            
            // HIG: 한눈에 파악 — 큰 기온 숫자
            Text("\(weather.temperature)°")
                .font(.system(size: 36, weight: .light))
                .contentTransition(.numericText())
            
            VStack(alignment: .leading, spacing: 0) {
                Text(weather.cityName)
                    .font(.caption)
                    .fontWeight(.semibold)
                
                Text("H:\(weather.highTemperature)° L:\(weather.lowTemperature)°")
                    .font(.caption2)
                    .foregroundStyle(.secondary)
            }
        }
        .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .leading)
    }
}

Step 3-2: Medium 위젯 — 시간별 예보

MediumWeatherView.swift Swift

struct MediumWeatherView: View {
    let weather: WeatherData
    
    var body: some View {
        HStack(spacing: 16) {
            // 왼쪽: 현재 날씨
            VStack(alignment: .leading, spacing: 4) {
                Text(weather.cityName)
                    .font(.subheadline)
                    .fontWeight(.semibold)
                
                Text("\(weather.temperature)°")
                    .font(.system(size: 44, weight: .light))
                
                Text(weather.condition.rawValue)
                    .font(.caption)
                    .foregroundStyle(.secondary)
            }
            
            Divider()
            
            // 오른쪽: 시간별 예보
            HStack(spacing: 12) {
                ForEach(weather.hourlyForecast.prefix(5)) { hourly in
                    VStack(spacing: 6) {
                        Text(hourly.hour)
                            .font(.caption2)
                        Image(systemName: hourly.condition.symbol)
                            .symbolRenderingMode(.multicolor)
                        Text("\(hourly.temperature)°")
                            .font(.caption)
                    }
                }
            }
        }
    }
}

Step 3-3: 날씨 기반 그래디언트 배경

WeatherGradient.swift Swift

extension WeatherCondition {
    var gradient: LinearGradient {
        switch self {
        case .sunny:
            LinearGradient(
                colors: [.orange, .yellow],
                startPoint: .topLeading,
                endPoint: .bottomTrailing
            )
        case .cloudy:
            LinearGradient(
                colors: [Color("CloudTop"), Color("CloudBottom")],
                startPoint: .top,
                endPoint: .bottom
            )
        case .rainy:
            LinearGradient(
                colors: [.gray, .blue.opacity(0.6)],
                startPoint: .topLeading,
                endPoint: .bottomTrailing
            )
        case .snowy:
            LinearGradient(
                colors: [.white, Color("IceBlue")],
                startPoint: .top,
                endPoint: .bottom
            )
        case .stormy:
            LinearGradient(
                colors: [Color("StormDark"), Color("StormPurple")],
                startPoint: .topLeading,
                endPoint: .bottomTrailing
            )
        }
    }
}

✅

Ring 3 체크포인트

Completed optimal layouts for Small/Medium sizes and gradient backgrounds by weather condition.

⚡ Ring 4 — Data & Interaction

From iOS 17, you can add Button and Toggle to widgets for interactivity.

Step 4-1: 인터랙티브 새로고침 버튼

RefreshWeatherIntent.swift Swift

import AppIntents
import WidgetKit

struct RefreshWeatherIntent: AppIntent {
    static var title: LocalizedStringResource = "날씨 새로고침"
    
    func perform() async throws -> some IntentResult {
        WidgetCenter.shared.reloadAllTimelines()
        return .result()
    }
}

// 위젯 뷰에서 사용:
Button(intent: RefreshWeatherIntent()) {
    Image(systemName: "arrow.clockwise")
        .font(.caption)
}
.buttonStyle(.plain)

✅

Ring 4 체크포인트

인터랙티브 새로고침 버튼까지 구현했습니다!

🚀 Ring 5 — Settings & Personalization

With App Intent Configuration, let users choose a city and support Lock Screen widgets.

Step 5-1: City Selection Configuration

SelectCityIntent.swift Swift

import AppIntents
import WidgetKit

struct SelectCityIntent: WidgetConfigurationIntent {
    static var title: LocalizedStringResource = "도시 선택"
    static var description: IntentDescription = "날씨를 확인할 도시Selectdo it."
    
    @Parameter(title: "도시", default: .seoul)
    var city: CityOption
}

enum CityOption: String, AppEnum {
    case seoul   = "서울"
    case busan   = "부산"
    case jeju    = "제주"
    case daejeon = "대전"
    case gwangju = "광주"
    
    static var typeDisplayRepresentation = TypeDisplayRepresentation(name: "도시")
    static var caseDisplayRepresentations: [CityOption: DisplayRepresentation] = [
        .seoul:   "서울",
        .busan:   "부산",
        .jeju:    "제주",
        .daejeon: "대전",
        .gwangju: "광주",
    ]
}

Step 5-2: 최종 위젯 구성

WeatherWidget.swift Swift

import WidgetKit
import SwiftUI

struct WeatherWidget: Widget {
    let kind = "WeatherWidget"
    
    var body: some WidgetConfiguration {
        AppIntentConfiguration(
            kind: kind,
            intent: SelectCityIntent.self,
            provider: WeatherProvider()
        ) { entry in
            WeatherWidgetEntryView(entry: entry)
                .containerBackground(
                    entry.weather.condition.gradient,
                    for: .widget
                )
        }
        .configurationDisplayName("날씨")
        .description("현재 날씨와 예보를 확인do it.")
        .supportedFamilies([
            .systemSmall, .systemMedium, .systemLarge,
            .accessoryCircular, .accessoryRectangular, .accessoryInline
        ])
    }
}

struct WeatherWidgetEntryView: View {
    @Environment(\.widgetFamily) var family
    let entry: WeatherEntry
    
    var body: some View {
        switch family {
        case .systemSmall:
            SmallWeatherView(weather: entry.weather)
        case .systemMedium:
            MediumWeatherView(weather: entry.weather)
        case .systemLarge:
            LargeWeatherView(weather: entry.weather)
        case .accessoryCircular:
            CircularWeatherView(weather: entry.weather)
        case .accessoryRectangular:
            RectangularWeatherView(weather: entry.weather)
        case .accessoryInline:
            Text("\(entry.weather.condition.rawValue) \(entry.weather.temperature)°")
        default:
            SmallWeatherView(weather: entry.weather)
        }
    }
}