widgets

正しい設定、タイムラインポリシー、表示面を選び、すべてのモードでウィジェットが正しく描画され、割り当てられた予算内で更新され、拡張機能とアプリのプロセス境界をまたいでも正しく動作するように、SwiftUI WidgetKit のコードを作成し、レビューします。

レビューの手順：

1. references/fundamentals.md を使って、ウィジェットの実行モデル（拡張機能のプロセス、アプリグループ、タイムラインのライフサイクル、再読み込み予算）を確認します。
2. references/timeline-provider.md を使って、タイムラインプロバイダー（placeholder／snapshot／timeline、再読み込みポリシー、WidgetCenter による再読み込み、エントリーの関連性）を検証します。
3. references/configuration-and-intents.md を使って、設定とユーザーが変更できるパラメーター（StaticConfiguration、AppIntentConfiguration、WidgetConfigurationIntent）を検証します。
4. references/migration-and-deprecations.md を使って、従来の API が使われていないか確認し、最新の同等機能に切り替えます（SiriKit の .intentdefinition → App Intents、ClockKit → WidgetKit、PreviewProvider → #Preview）。
5. references/data-and-networking.md を使って、プロバイダーとインテントでのデータ読み込み（ネットワーク通信、永続化、画像、位置情報）を検証します。
6. references/families-and-layout.md を使って、ファミリーへの対応とファミリーごとのレイアウト（WidgetFamily、サイズ調整、コンテンツマージン、ViewThatFits）を検証します。
7. references/lock-screen-and-watch.md を使って、ロック画面／アクセサリーウィジェットと Apple Watch のコンプリケーション（widgetLabel、AccessoryWidgetBackground、透明コンテナーの手法、ClockKit からの移行）を検証します。
8. references/rendering-modes-and-tinting.md を使って、フルカラー、アクセント付き、ティント、ビビッドの各モードでの描画（widgetRenderingMode、widgetAccentable、widgetAccentedRenderingMode、輝度からアルファへの変換手法）を検証します。
9. references/interactive-widgets.md を使って、インタラクティブ機能（Button(intent:)、Toggle(intent:)、アプリプロセスとの境界、reloadTimelines、invalidatableContent）を検証します。
10. references/deep-linking-and-navigation.md を使って、アプリへのディープリンクとナビゲーション（widgetURL、Link、onOpenURL、OpenIntent）を検証します。
11. references/animations-and-transitions.md を使って、アニメーションとエントリーのトランジション（contentTransition、.transition と ID、アニメーションされないもの）を検証します。
12. references/controls.md を使って、コントロールセンターのコントロール（ControlWidget、トグルとボタンの使い分け、SetValueIntent、値プロバイダー、ControlCenter による再読み込み）を検証します。
13. references/live-activities.md を使って、ライブアクティビティと Dynamic Island（ActivityAttributes、ActivityConfiguration、DynamicIsland、リクエスト／更新／終了、プッシュ通知、supplementalActivityFamilies）を検証します。
14. references/relevance-and-smart-stacks.md を使って、Smart Stack での関連性（TimelineEntryRelevance、relevance()／WidgetRelevance、RelevanceConfiguration、プッシュ通知による関連性）を検証します。
15. references/design-and-gallery.md を使って、デザインとギャラリーでの表示（ひと目で分かること、サイズ、避けるべきこと、configurationDisplayName／description、プレースホルダー）を確認します。
16. references/previews-and-testing.md を使って、プレビューとテスト／デバッグのワークフロー（#Preview(as:)、WidgetKit デベロッパーモード、再読み込み予算）を検証します。
17. references/platforms.md を使って、プラットフォーム固有の表示面（visionOS の空間ウィジェット、CarPlay、macOS のメニューバー、対応状況一覧）を検証します。
18. references/anti-patterns.md を使って、よくある間違いを見つけます。

作業の一部のみを行う場合は、関連するリファレンスファイルだけを読み込みます。

タスク別の参照先

ユーザーの目的に合わせて、読み込む順序を決めます。必要なものだけを読み込んでください。

「最初のウィジェットを作成する」／「完全なウィジェットを見せて」

1. references/fundamentals.md - 拡張機能、ウィジェットバンドル、タイムラインのライフサイクル
2. references/worked-example.md - エントリーからプロバイダー、レイアウト、リンク、ティント、アニメーション、プレビューまで、一つのウィジェットを最初から最後まで作成する例
3. references/timeline-provider.md - TimelineProvider、エントリー、再読み込みポリシー
4. references/families-and-layout.md - ファミリーの選択、ファミリーごとのレイアウト
5. references/previews-and-testing.md - #Preview(as:) を使った反復作業

「ユーザーがウィジェットを設定できるようにする」

1. references/configuration-and-intents.md - AppIntentConfiguration と WidgetConfigurationIntent、動的なオプション、デフォルト値
2. references/timeline-provider.md - AppIntentTimelineProvider（インテントが最初の引数です）

「ロック画面ウィジェット／ウォッチのコンプリケーションを追加する」

1. references/lock-screen-and-watch.md - アクセサリファミリー、widgetLabel、AccessoryWidgetBackground、ゲージ、ClockKit からの移行
2. references/rendering-modes-and-tinting.md - アクセサリウィジェットは常にティントモードで描画されます

「ウィジェットがティント／ダーク／アクセントモードで正しく表示されない」

1. references/rendering-modes-and-tinting.md - widgetRenderingMode、widgetAccentable、widgetAccentedRenderingMode、輝度からアルファへの変換テクニック、アクセントグループ向けの設計
2. references/lock-screen-and-watch.md - アクセサリウィジェット向けの透明な containerBackground

「ウィジェット内にボタン／トグルを追加する」

1. references/interactive-widgets.md - Button(intent:)／Toggle(intent:)、アプリプロセスの境界、App Group ストア、reloadTimelines、invalidatableContent
2. references/configuration-and-intents.md - ヘルパーインテントの isDiscoverable = false

「コントロールセンターのコントロール／アクションボタン／ロック画面のコントロールを追加する」

1. references/controls.md - ControlWidget、ControlWidgetToggle（SetValueIntent）と ControlWidgetButton（AppIntent）の違い、値プロバイダー、ControlCenter.shared.reloadControls
2. references/interactive-widgets.md - 同じアプリプロセス／共有ストアのルールが適用されます

「ライブアクティビティ／Dynamic Island を作成する」

1. references/live-activities.md - ActivityAttributes／ContentState、ActivityConfiguration、DynamicIsland の領域、リクエスト／更新／終了、古さの判定、プッシュ通知、supplementalActivityFamilies、iOS 27 の横向き Dynamic Island
2. references/interactive-widgets.md - LiveActivityIntent ボタン

「サーバーからウィジェットの内容を最新の状態に保つ」

1. references/timeline-provider.md - 再読み込みポリシー、再読み込みの予算、アプリがバックグラウンドに移行したときの再読み込み
2. references/relevance-and-smart-stacks.md - プッシュで更新されるウィジェット（WidgetPushHandler、iOS 26）、および代わりにライブアクティビティを使うべき状況

「適切なタイミングでウィジェットをスマートスタックに表示する」

1. references/relevance-and-smart-stacks.md - TimelineEntryRelevance、relevance() と WidgetRelevance、RelevanceConfiguration（watchOS 26）、RelevantContext

「ウィジェットでデータを取得する／画像を読み込む／データベースや位置情報を使う」

1. references/data-and-networking.md - App Group のスナップショット、プロバイダーでの async データ取得、画像のダウンサンプリング、SwiftData／Core Data、NSWidgetUsesLocation
2. references/timeline-provider.md - ライフサイクルと予算におけるデータ取得の位置づけ

「ディープリンクを設定する／ウィジェットからアプリを開く」

1. references/deep-linking-and-navigation.md - widgetURL と Link の違い、ファミリーごとのルール、onOpenURL、OpenIntent

「ウィジェットをアニメーションさせる／値をスクロールまたは遷移させる」

1. references/animations-and-transitions.md - エントリーの差分検出、contentTransition(.numericText)、.transition と .id、invalidatableContent、アニメーションしないもの

「古いウィジェットを最新化する／IntentConfiguration、ClockKit、PreviewProvider が表示される」

1. references/migration-and-deprecations.md - 古い方式から新しい方式への対応表、CustomIntentMigratedAppIntent、ClockKit の移行ツール、二重パスの #available

「ウィジェットのデザインを整える／ギャラリーに掲載できる状態にする」

1. references/design-and-gallery.md - 一目でわかること／パーソナルであること／関連性、サイズとタップのスタイル、避けるべきこと、スナップショット、プレースホルダー

「visionOS／CarPlay／macOS／Apple Watch に対応する」

1. references/platforms.md - 空間ウィジェット（supportedMountingStyles、widgetTexture、levelOfDetail）、CarPlay、macOS のメニューバー、利用可否マップ

「ウィジェットが更新されない／古いデータが表示される／まったく表示されない」

1. references/previews-and-testing.md - リロードの予算、WidgetKit の開発者モード、デバッグ
2. references/anti-patterns.md - よくある原因

「ビルドエラーやレンダリングの不具合が発生している」

1. references/anti-patterns.md - 修正前／修正後の例で解説

意思決定ツリー

タスクはわかっているものの、適切な API がわからない場合のクイックガイドです。

ウィジェットにはどの構成を使うべきですか？

No user configuration, fixed behavior?
  -> StaticConfiguration(kind:provider:)

User picks parameters (account, city, repo)?
  -> AppIntentConfiguration(kind:intent:provider:) + WidgetConfigurationIntent   (iOS 17+)

Migrating an existing iOS 14-16 configurable widget?
  -> WidgetConfigurationIntent + CustomIntentMigratedAppIntent (keep intentClassName)
  -> or keep IntentConfiguration(kind:intent:provider:) with the legacy INIntent

Appears in the Smart Stack only when relevant (watchOS)?
  -> RelevanceConfiguration(kind:provider:)   (watchOS 26+)

どのタイムラインプロバイダーを使うべきですか？

StaticConfiguration?
  -> TimelineProvider           (placeholder / getSnapshot / getTimeline, completion-based)

AppIntentConfiguration?
  -> AppIntentTimelineProvider  (placeholder / snapshot(for:in:) / timeline(for:in:), async, intent FIRST)

RelevanceConfiguration (watchOS)?
  -> RelevanceEntriesProvider   (placeholder / relevance() / entry(configuration:context:), one entry per config)

どのリロードポリシーを使うべきですか？

Next update time is known (countdown ends, event starts)?
  -> .after(date)

Entries cover a window and the next batch can be computed at the end?
  -> .atEnd

Content only changes from interaction / push, never on a schedule?
  -> .never   (then reload via WidgetCenter from an intent, app, or push)

どのインタラクティブ要素を使うべきですか？

Inside a widget or Live Activity, runs an action?
  -> Button(intent:) with an AppIntent          (iOS 17+)

Inside a widget, binary on/off?
  -> Toggle(isOn:intent:) with an AppIntent      (iOS 17+)

Inside a Control Center control, binary on/off?
  -> ControlWidgetToggle(action:) with a SetValueIntent

Inside a Control Center control, runs an action / opens the app?
  -> ControlWidgetButton(action:) with an AppIntent (or OpenIntent to launch)

ウィジェット、ライブアクティビティ、コントロールのどれを使うべきですか？

Glanceable data on a schedule, lives on Home/Lock Screen?
  -> Widget (timeline)

Ongoing, time-bound event the user wants to watch live (delivery, game, workout)?
  -> Live Activity (ActivityKit) - NOT a fast-reloading widget

A quick action or state toggle from Control Center / Lock Screen / Action button?
  -> Control (ControlWidget)

コアインストラクション

• ウィジェットはアプリではなく、別の拡張プロセスで動作します。UIKit アプリ内でも、必ず SwiftUI を使用します。システムはビューをアーカイブして後でレンダリングするため、ウィジェットが画面に表示されている間、コードは実行されません。アプリとのデータ共有には App Group コンテナ（共有の UserDefaults(suiteName:)、共有ファイル、共有の ModelContainer／Core Data ストア）のみを使用してください。UserDefaults.standard やメモリー内のシングルトンは使用しないでください。
• クロージャーや onTapGesture でウィジェットを操作可能にすることは、絶対に避けてください。 操作方法は、AppIntent（iOS 17 以降）を使う Button(intent:)／Toggle(intent:) と、ディープリンク用の Link／widgetURL のみです。それ以外は何も起こりません。
• ウィジェットの背景には必ず .containerBackground(for: .widget) { ... }（iOS 17 以降）を指定してください。指定しないと、ギャラリーでウィジェットが空白になり、適切に削除・配置変更できず、ロック画面／スタンバイ／色合い付きのコンテキストでシステムがマテリアル背景に置き換えることもできません。コンテナ型は ContainerBackgroundPlacement（値は .widget）です。WidgetBackgroundPlacement はありません。
• placeholder(in:) ではブロッキング処理や非同期処理を絶対に行わないでください。プレースホルダーは代替データを使って同期的に返す必要があります。実際のデータ取得は getSnapshot／getTimeline（または非同期の snapshot／timeline）で行ってください。初回表示用の代替データには .redacted(reason: .placeholder) を使用してください。
• ウィジェットギャラリーに表示されるのは getSnapshot（および snapshot(for:in:)）です。まだユーザーのデータがない場合でも、現実的で内容のあるサンプルデータを返してください。空の状態や読み込み中の状態は返さないでください。
• タイムラインの再読み込みは、タイマーではなく、予算があり、状況に応じて行われるリソースとして扱ってください。システムはウィジェットごとにおよそ 1 日あたり 40～70 回の再読み込みを提供し、閲覧習慣を学習します。.after(date) が正確な時刻に実行されることを前提にしないでください。一定期間をカバーする複数のエントリーを用意し、データに合ったポリシー（.atEnd／.after／.never）を選び、データが変更された場合はアプリがバックグラウンドに移行するときに最後の WidgetCenter.shared.reloadAllTimelines() を呼び出してください。
• TimelineReloadPolicy は構造体です。.after(_:) が受け取るのは TimeInterval ではなく Date です。WidgetCenter.shared.reloadTimelines(ofKind:) が受け取るのはウィジェットの kind 文字列です。アプリと拡張機能で値が食い違わないよう、kind の値は共有定数として保持してください。
• 設定可能なウィジェットには、AppIntentConfiguration と WidgetConfigurationIntent（iOS 17 以降）、および snapshot／timeline の最初の引数にインテントを取る AppIntentTimelineProvider を使用してください。WidgetConfigurationIntent は AppIntents モジュールにあり、perform() は不要です。適切な @Parameter のデフォルト値を指定し、ウィジェットを表示する前にユーザーに設定を強制しないでください。
• SiriKit のレガシー方式、つまり IntentConfiguration、.intentdefinition ファイルの INIntent、IntentTimelineProvider を使って、新しい設定可能なウィジェットを作成することは絶対に避けてください。iOS 17 以降の最新方式は App Intents（AppIntentConfiguration + WidgetConfigurationIntent + AppIntentTimelineProvider）です。iOS 17 未満をデプロイ対象にする場合に限り、レガシー型を #available の背後に残してください。既存のウィジェットを移行するときは、新しいインテントを元の intentClassName を指定した CustomIntentMigratedAppIntent に準拠させ、保存済みの設定を維持してください。同様に、watch のコンプリケーションは ClockKit ではなく WidgetKit（および CLKComplicationWidgetMigrator）で作成し、プレビューには PreviewProvider ではなく #Preview(as:) を使用してください。references/migration-and-deprecations.md を参照してください。
• ウィジェットのビュー内でデータを取得しないでください（AsyncImage の使用や、レンダリング時のネットワークアクセスは不可）。ビューはアーカイブされたスナップショットを後でレンダリングするためです。タイムライン生成時にデータを解決し、画像をダウンサンプリングしてエントリーに格納してください。できれば、アプリが書き込んだ App Group のスナップショットを読み込み、プロバイダーは必ず完了させてください（エラー時は最後に正常取得できたデータにフォールバックします）。references/data-and-networking.md を参照してください。
• @Environment(\.widgetFamily) に基づいて切り替え、サポートする各ファミリーを意図的に設計してください。実際にレイアウトを用意したファミリーだけを supportedFamilies に列挙してください。設計していないファミリーを配信すると、見た目が壊れてしまいます。Accessory ファミリー（accessoryCircular／accessoryRectangular／accessoryInline）は iOS 16 以降、accessoryCorner は watchOS のみです。
• フルカラーだけでなく、あらゆるレンダリングモードに対応するよう設計してください。@Environment(\.widgetRenderingMode)（.fullColor／.accented／.vibrant）を読み取ります。WidgetRenderingMode と WidgetAccentedRenderingMode はどちらも、列挙型ではなく、型プロパティを持つ構造体です。.accented モードでは、システムがアルファ値に基づいてビューを 2 つの色合いグループに平坦化します。.widgetAccentable() を使って前景コンテンツをアクセントグループに配置し、.widgetAccentedRenderingMode(.desaturated / .accented / .accentedDesaturated / .fullColor) で画像の平坦化方法を制御してください（画像用のこのモディファイアは iOS 18 以降です）。
• アクセントグループによって単色のシルエットに潰れてしまうマルチカラー画像やアイコンには、iOS 18 以降では .widgetAccentedRenderingMode(.desaturated) を使用してください（システムが輝度をアルファ値に変換し、色を再設定します）。iOS 17 以前にはこのモディファイアがないため、手動で .luminanceToAlpha() フィルターを適用してください（明るいピクセルは不透明、暗いピクセルは透明になり、形状の細部を鮮明なモノクロのグリフとして保てます）。この方法は、細かく制御したい場合には iOS 18 以降でも引き続き有効です。柔らかなグラデーション背景と .widgetAccentable() を組み合わせてください。（references/rendering-modes-and-tinting.md を参照してください。）
• 文字盤や壁紙が透けて見えるようにしたい Accessory／ロック画面ウィジェットや watch のコンプリケーションには、空の .containerBackground(for: .widget) { } を指定してください。containerBackground 自体を省略すると、透明ではなく不透明なデフォルトのマテリアル背景がシステムによって追加されます。
• 操作可能な AppIntent はウィジェット拡張ではなく、アプリのプロセス内で実行されます（必要に応じてアプリがバックグラウンドで起動します）。そのため、実際のデータストアに書き込めます。ウィジェットが表示するデータを変更した後は、WidgetCenter.shared.reloadTimelines(ofKind:)（または reloadAllTimelines()）を呼び出してください。Control の場合は ControlCenter.shared.reloadControls(ofKind:) を呼び出します。ウィジェット／Control のボタンを支えるだけのヘルパーインテントには static let isDiscoverable = false を指定し、ショートカットに表示されないようにしてください。
• 27 リリース（iOS 27）では、ウィジェットボタンの書き込みインテントは .main で実行する必要があります（ウィジェット拡張には共有ストアへの読み取り専用アクセスしかありません）。static var allowedExecutionTargets: ExecutionTargets { .main } を指定し、表示専用インテントには .widgetKitExtension を指定してください。
• Control（ControlWidget、iOS 18、macOS／watchOS 26）は、SetValueIntent（その value: Bool はシステムが設定します）を使う ControlWidgetToggle、または通常の AppIntent／OpenIntent を使う ControlWidgetButton を使用します。ステータス用モディファイアは controlWidgetStatus(_:) です。controlWidgetStatusText はありません。値プロバイダーには previewValue と非同期の currentValue を用意してください。
• 継続中で時間制限のあるイベントには、数秒ごとに再読み込みするウィジェットではなく、Live Activity が適しています。変更されないデータは ActivityAttributes に分け、更新可能なデータのみをネストされた ContentState: Codable, Hashable に入れてください（4 KB 未満にしてください）。ActivityConfiguration と DynamicIsland は WidgetKit に、Activity.request/update/end とトークンは ActivityKit にあります。staleDate／relevanceScore は設定ではなく ActivityContent.init で設定します。
• Live Activities を使用するには、アプリの Info.plist で NSSupportsLiveActivities = YES が必要です。高頻度のプッシュ更新には NSSupportsLiveActivitiesFrequentUpdates も必要です。プッシュ開始には Activity.pushToStartToken（iOS 17.2 以降）を使用します。これは PushType のケースではありません。大規模な対象へのプッシュにはブロードキャストの channel を使用し、それ以外ではアクティビティごとのプッシュトークンを使用してください。
• Live Activity やウィジェットに symbolEffect アニメーションを絶対に追加しないでください。サポートされておらず、何も起こりません。ウィジェット／Live Activity のビューは静的なスナップショットです。アニメーションするのは Text(_:style:) のタイマー／日付と、タイムラインエントリー間のシステム遷移のみです。
• widgetAccentedRenderingMode は iOS 18 以降、Control は iOS 18 以降（macOS／watchOS は 26 以降）、プッシュ更新ウィジェット（WidgetPushHandler）と RelevanceConfiguration は iOS 26／watchOS 26、空間ウィジェット用モディファイア（supportedMountingStyles、widgetTexture、levelOfDetail）は iOS／visionOS 26、systemExtraLargePortrait、Dynamic Island の横向き表示（isDynamicIslandLimitedInWidth）、allowedExecutionTargets は 27 リリースで導入されています。それぞれ正しい可用性条件を付け、WWDC 2026 の世代は「iOS 19」ではなく **「27 リリース」**と呼んでください。
• #Preview(as:) マクロ（iOS 17 以降）を使用すると、ホストアプリを実行せずに、さまざまなファミリー、カラースキーム、レンダリングモードでウィジェットを試作できます。試作中は WidgetKit の開発者モード（「設定」▸「デベロッパ」）を有効にして、再読み込みの予算を増やしてください。ウィジェットが「更新を停止する」最も一般的な原因はコードのバグではなく、再読み込み予算を使い切ることです。

出力形式

ユーザーがレビューを依頼した場合は、ファイルごとに指摘事項をまとめます。各指摘事項について：

1. ファイル名と該当する行番号を示します。
2. 置き換えるべきアンチパターンを記載します。
3. 簡潔な修正前／修正後のコードを示します。

問題のないファイルは省略します。最後に、最も影響の大きい変更から優先順位を付けてまとめます。

ユーザーがウィジェットのコードの作成または修正を依頼した場合は、指摘事項のレポートを返すのではなく、コードを直接変更します。

出力例：

CaffeineWidget.swift

14行目：placeholder(in:) が同期的にディスクからデータを取得しています。プレースホルダーは即座に返す必要があります。

// Before
func placeholder(in context: Context) -> Entry {
    Entry(date: .now, drinks: Store.shared.loadAllDrinks())   // blocks the render
}

// After
func placeholder(in context: Context) -> Entry {
    Entry(date: .now, drinks: .sample)   // synchronous stand-in; real data in getTimeline
}

41行目：ウィジェット内のインタラクティブな onTapGesture は機能しません。App Intent を使用してください。

// Before
Image(systemName: "plus.circle").onTapGesture { addDrink() }

// After
Button(intent: AddDrinkIntent()) { Image(systemName: "plus.circle") }
// AddDrinkIntent.perform() writes to the App Group store, then:
// WidgetCenter.shared.reloadTimelines(ofKind: "CaffeineWidget")

まとめ

1. プレースホルダー（優先度：高）： 同期的に返す必要があります。データ取得はタイムラインに移してください。
2. インタラクティブ性（優先度：高）： ウィジェットではジェスチャーが機能しません。タップ操作に AppIntent を割り当ててください。

出力例終わり。

参考資料

• references/fundamentals.md - ウィジェットの実行モデル：拡張機能プロセス、アプリグループ、WidgetBundle、Widget プロトコル、タイムラインのライフサイクル、containerBackground、コンテンツの余白、ディープリンク、kind、および「どのサーフェスか」の対応表。
• references/timeline-provider.md - TimelineProvider と AppIntentTimelineProvider の違い、TimelineEntry、Timeline、再読み込みポリシー、再読み込みの上限、WidgetCenter による再読み込み、バックグラウンド移行時の再読み込み、TimelineEntryRelevance。
• references/configuration-and-intents.md - StaticConfiguration、AppIntentConfiguration、WidgetConfigurationIntent、動的なオプション／エンティティパラメーター、recommendations()、デフォルト値。
• references/migration-and-deprecations.md - 旧方式から新方式への対応表：SiriKit .intentdefinition／IntentConfiguration → App Intents、IntentTimelineProvider → AppIntentTimelineProvider、ClockKit → WidgetKit、PreviewProvider → #Preview、非推奨とレガシーだがサポート対象の違い、CustomIntentMigratedAppIntent。
• references/data-and-networking.md - タイムライン用のデータ読み込み：App Group のスナップショット、async／バックグラウンドの URLSession フェッチ、画像のダウンサンプリング、ウィジェット内での SwiftData／Core Data、位置情報、ロック画面のプライバシー。
• references/families-and-layout.md - WidgetFamily のケース、サイズ設定、supportedFamilies、コンテンツの余白、ファミリーごとの切り替え、ViewThatFits、ContainerRelativeShape。
• references/lock-screen-and-watch.md - アクセサリファミリー、ウォッチのコンプリケーション、widgetLabel、AccessoryWidgetBackground、ゲージ、透明な containerBackground のテクニック、ClockKit から WidgetKit への移行。
• references/rendering-modes-and-tinting.md - widgetRenderingMode（.fullColor／.accented／.vibrant）、widgetAccentable、widgetAccentedRenderingMode、輝度からアルファ値への変換テクニック、色付き／透明なホーム画面とアクセントグループを想定したデザイン。
• references/interactive-widgets.md - Button(intent:)／Toggle(intent:)、アプリプロセスの境界、@Parameter の永続化、App Group ストア、reloadTimelines、楽観的な ToggleStyle、invalidatableContent、isDiscoverable、allowedExecutionTargets（27 リリース）。
• references/deep-linking-and-navigation.md - widgetURL と Link の違い、ファミリーごとのタップルール、URL スキームの設計、アプリ側での処理（onOpenURL／シーンデリゲート）、Live Activity の widgetURL／keylineTint、コントロールの OpenIntent。
• references/animations-and-transitions.md - エントリー差分によるアニメーションモデル、contentTransition(.numericText)、.transition と .id による識別、楽観的な Toggle、invalidatableContent、Live Activity のトランジション、アニメーションされないもの（symbolEffect、ループ、動画）。
• references/controls.md - ControlWidget、StaticControlConfiguration／AppIntentControlConfiguration、ControlWidgetToggle（SetValueIntent）と ControlWidgetButton（AppIntent／OpenIntent）の違い、値プロバイダー、ControlCenter による再読み込み、ステータス／アクションヒントのモディファイア、プラットフォーム。
• references/live-activities.md - ActivityAttributes／ContentState、ActivityConfiguration、DynamicIsland、Activity.request/update/end、ActivityContent の陳腐化、プッシュ（トークン／チャンネル／プッシュ開始）、supplementalActivityFamilies／activityFamily、横向きの Dynamic Island、StandBy、LiveActivityIntent、エンタイトルメント。
• references/relevance-and-smart-stacks.md - TimelineEntryRelevance、relevance() と WidgetRelevance／WidgetRelevanceAttribute／RelevantContext、RelevanceConfiguration と RelevanceEntriesProvider（watchOS 26）、プッシュで更新されるウィジェット（WidgetPushHandler、iOS 26）、Smart Stack の動作。
• references/design-and-gallery.md - デザインのルール（一目でわかる、関連性がある、パーソナルであること。ミニアプリにしないこと）、サイズとタップのスタイル、レイアウトの余白と文字、明示的な禁止事項、ギャラリー（configurationDisplayName／description／スナップショット）、プレースホルダー、パーソナライズ、Smart Stack のエチケット。
• references/previews-and-testing.md - #Preview(as:) マクロのバリエーション、WidgetPreviewContext、レンダリングモード／ファミリーのテスト、WidgetKit の開発者モード、再読み込みの上限、「更新されない」問題のデバッグ。
• references/platforms.md - visionOS の空間ウィジェット（supportedMountingStyles、widgetTexture、levelOfDetail、systemExtraLargePortrait）、CarPlay のウィジェットと Live Activities、macOS のメニューバー、watchOS、クロスプラットフォームの対応状況一覧。
• references/worked-example.md - ウィジェットを最初から最後まで構築する例（systemMedium のクイックアクションウィジェット）：エントリーとプロバイダー、複数の Link を使ったレイアウト、フルカラーと色付き表示の処理、エントリー駆動の MeshGradient アニメーション、contentMarginsDisabled、プレビュー。各手順に対応する詳細なリファレンスへの案内も含みます。
• references/anti-patterns.md - よくある問題と修正方法をまとめたチェックリスト。LLM が混同しやすい API 名（レンダリングモードの構造体と列挙型、ContainerBackgroundPlacement、pushToStartToken、controlWidgetStatus）も含みます。