liquid-glass-motion

Liquid Glass — モーション、アニメーション、シェーダー

liquid-glass スキル（~/.claude/skills/liquid-glass/）の補足資料です。同じタグシステムを使用します： [verified] / [apple] / [multi] / [single] / [version-pinned] — 詳細は同スキルの SKILL.md を参照してください。2026-08 に作成し、Apple のドキュメントと SDK インターフェースに照らして検証済みです。

運用ルール

1. コードを生成する前に、必ず付属の liquid-glass スキル（このスキルと一緒にインストールされています）にある可用性のファイアウォールを確認してください： references/availability-and-sdk27.md。モーションのコードでも同じ SDK-27 の問題（.if の禁止、 @ContentBuilder、名前変更）が発生します。
2. ルーターを使って、必要なときに参照資料を読み込んでください。1 つのトピックにつき、1 つのファイルを読み込みます。
3. モーションのモデル：Liquid Glass とそのモーションは一体として設計されています。Glass はフェードせず、レンズ効果を調整して現れます。Glass が大きくなると、素材も厚くなります（影が深くなり、レンズ効果が強くなります）。サイズの変化は素材の変化であるため、モーフには必ずシステムアニメーションを使い、手作業で再現してはいけません。
4. モーションに関する説明を繰り返す前に、references/ で検証してください。広まっている解説には誤りがいくつかあります。訂正された情報はこれらのファイルに記載されています。
5. 推論よりプロファイリングの証拠を優先してください。最適化の前に xctrace で Instruments のトレースを記録し、SwiftUI インストゥルメントでは iOS Simulator を決して信用しないでください。詳しくは references/performance-and-instrumentation.md を参照してください。

厳守事項（要点）

1. Glass のアニメーションに .opacity やフェードを使ってはいけません。glassEffectTransition を使ってください（認められているフェード風の選択肢は .materialize です）。[multi]
2. モーフは次の 4 つの条件がすべて満たされないと、何も起こらずに失敗します。同じ GlassEffectContainer を使うこと、 1 つの共有 @Namespace 内で各要素に glassEffectID を付与すること、ビューの挿入／削除による変化であること （値の変更ではないこと）、状態の変更が withAnimation 内にあることです。 さらにジオメトリの条件として、コンテナ内で最も近い辺同士の距離が spacing 以内である必要があります。[multi]
3. インタラクティブな「スクイッシュ」はブール値 1 つ、つまり .interactive() で指定します。公開された spring／damping／ stiffness の調整パラメーターはありません。調整可能なゼリー効果を約束してはいけません。[multi]
4. Glass のアニメーションはすべて accessibilityReduceMotion で制御してください。デフォルトのモーフは運動効果であり、視覚効果を減らすユーザーにはちらつきとして感じられた事例があります。システムが withAnimation を 自動的に制御してくれるわけではありません。[multi]
5. プロパティごとにアニメーションのソースは 1 つにしてください。同じプロパティに暗黙的な .animation、withAnimation、 スクロール駆動の更新を混在させてはいけません。ビュー階層の後方にある暗黙的なアニメーションが、明示的なアニメーションよりも優先され、何も通知されません。[multi]
6. アニメーションのコンテキストは条件分岐の外側に置いてください。if の内部にある .animation() はビューとともに破棄されるため、削除時にアニメーションしません。[multi]
7. スクロールに連動するモーションでは、オブザーバブルなスクロールオフセットの受け渡しより、レンダラー側のモーションである scrollTransition／visualEffect(in:) を優先してください。[apple]
8. まず変換（スケール／オフセット／回転）をアニメーションさせ、次にフレーム、最後にアイデンティティの変化をアニメーションさせてください。 [multi]

トピックルーター

トピック	参照資料
スプリング、カーブ、優先順位、Transaction、@Animatable、CA ブリッジ	references/animation-fundamentals.md
Glass のモーフ、glassEffectID、ユニオン、glassEffectTransition	references/morphing.md
ナビゲーションズーム、カスタム Transition、シート、タッチ操作とトラックパッド操作の違い	references/transitions-and-navigation.md
スクロール駆動のモーション、scrollTransition、visualEffect、クロームとの連携	references/scroll-driven.md
PhaseAnimator、KeyframeAnimator、シンボルエフェクト	references/phase-and-keyframe.md
Reduce Motion の制御、置換表	references/reduce-motion.md
Glass と組み合わせる／Glass の下に配置する／Glass の代わりに使う Metal シェーダー	references/metal-and-glass.md
パフォーマンスモデル、xctrace によるプロファイリング	references/performance-and-instrumentation.md
静的な Glass、可用性、ツールバー、プラットフォーム API、素材のアクセシビリティ	liquid-glass スキル
スプリング／damping／duration の具体的な値の選択	apple-motion-feel スキル

スクリプト

scripts/record_trace.py と scripts/analyze_trace.py（および instruments_parser/）は、Antoine van der Lee の SwiftUI-Agent-Skill（MIT）からベンダー提供されたものです。ライセンスは scripts/LICENSE-AvdLee-SwiftUI-Agent-Skill として同梱されています。Instruments のトレース（Time Profiler、Hangs、Animation Hitches、SwiftUI レーン）を記録し、JSON／Markdown に解析します。使い方と解釈については、references/performance-and-instrumentation.md を参照してください。