axiom-liquid-glass

Liquid Glass — Appleの新しいマテリアルデザインシステム

このスキルを使用する場面

次の場合に使用します：

• アプリにLiquid Glassのエフェクトを実装するとき
• 既存のUIでLiquid Glassを採用できる箇所を検討するとき
• Liquid Glassマテリアルの視覚的な不具合をデバッグするとき
• Liquid Glassのパフォーマンスを最適化するとき
• Liquid Glassの実装について専門家のレビューを依頼するとき
• RegularとClearのバリエーションをいつ使うか理解するとき
• 色合い、視認性、または適応動作に関する問題をトラブルシューティングするとき

関連スキル

• アプリ全体での包括的な採用方法（アプリアイコン、コントロール、ナビゲーション、メニュー、ウインドウ、プラットフォームに関する考慮事項）については、axiom-liquid-glass-refを使用します

プロンプトの例

• 「Liquid Glassはぼかし効果とどう違いますか？採用すべきですか？」
• 「レンズ効果が普通のぼかしのように見えます。何が足りないのでしょうか？」
• 「Liquid Glassの見た目がiPhoneとiPadで異なります。どう調整すればよいですか？」
• 「Liquid Glassの上に表示するテキストのコントラストを確保するにはどうすればよいですか？」
• 「Liquid Glassの実装をレビューする際の専門的な評価基準は何ですか？」

---

Liquid Glassとは？

Liquid Glassは、WWDC 2025で発表されたAppleの次世代マテリアルデザインシステムです。従来のマテリアル（Aqua、iOS 7のぼかし、Dynamic Island）から大きく進化し、次のような新しいデジタルのメタマテリアルを実現します。

• 光を散乱させるのではなく、動的に屈折させ、形作る（レンズ効果）
• タッチやアプリの動きに応じて、軽やかな液体のように有機的に動く
• サイズ、環境、コンテンツ、ライトモード／ダークモードに自動的に適応する
• Appleのすべてのプラットフォーム（iOS、iPadOS、macOS、axiom-visionOS）でデザイン言語を統一する

基本理念：Liquid Glassは、角丸で没入感のある画面の進化を補完します。自然なタッチ操作を感じさせる、角の丸い浮遊する形状を実現しながら、コンテンツを際立たせます。

---

視覚的な特性

1. レンズ効果（主な視覚的特徴）

Liquid Glassを特徴づけるのはレンズ効果です。光をゆがめ、屈折させることで、存在感、動き、形状を伝えます。光の屈折を調整することで、要素がフェードするのではなく、現れたり消えたりします。コントロールは、非常に軽やかでありながら、視覚的に識別できます。

2. 動きと流動性

• 操作に応じて、光とともにしなやかに変化します
• ゲルのような柔軟性が、一時的で変化しやすい性質を伝えます
• 操作に応じて、要素がLiquid Glassへと浮かび上がります（コントロール）
• アプリの状態間を、ひとつの浮遊する平面として動的に変化します

3. 適応動作

Liquid Glassは、ライト／ダークの固定的な外観を持たず、継続的に適応します。

• テキストが下をスクロールすると影が強まり、視認性を保つために色合いが変化します
• 小さな要素（ナビゲーションバー）は個別にライト／ダークを切り替えます。大きな要素（メニュー、サイドバー）は切り替わらず、奥行きが変化します
• 周囲の環境が、表面にさりげなく映り込みます

---

実装ガイド

基本的なAPIの使用方法

SwiftUI：glassEffectモディファイア

// Basic usage - applies glass within capsule shape
Text("Hello")
    .glassEffect()

// Custom shape
Text("Hello")
    .glassEffect(in: RoundedRectangle(cornerRadius: 12))

// Interactive elements (iOS - for controls/containers)
Button("Tap Me") {
    // action
}
.glassEffect()
.interactive() // Add for custom controls on iOS

自動的な採用：Xcode 26で再コンパイルするだけで、標準コントロールにLiquid Glassが自動的に適用されます。

バリエーション：RegularとClear

重要な判断事項：同じインターフェースでRegularとClearを混在させないでください。

Regularバリエーション（デフォルト — 95%のケース）

最も汎用性の高いバリエーションです。適応効果がすべて適用され、視認性が自動的に保たれ、あらゆるサイズで、あらゆるコンテンツの上に使用できます。ナビゲーションバー、タブバー、ツールバー、ボタン、メニュー、サイドバーに使用します。

Clearバリエーション（特殊なケースのみ）

常に透明度が高く、適応動作はありません。視認性を保つには減光レイヤーが必要です。

次の3つの条件をすべて満たす場合にのみ使用します：

1. 要素がメディアを多く含むコンテンツの上にある
2. 減光レイヤーによってコンテンツレイヤーに悪影響が生じない
3. ガラスの上にあるコンテンツが太字で明るい

3つの条件をすべて満たさずにClearを使用すると、視認性が低下します。実装例については、axiom-liquid-glass-refを参照してください。

レイヤー構造のアーキテクチャ

Liquid Glass は、連携して機能する次の 4 つのレイヤーで構成されています。

1. ハイライト — 光源がジオメトリに応じて変化するハイライトを生み出します。一部はデバイスの動きにも反応します
2. シャドウ — コンテンツに応じて変化します。テキストの上では強く、明るい背景の上では弱くなります
3. 内部の輝き — インタラクション時にマテリアルが内側から発光し、近くのガラス要素にも広がります
4. アダプティブな色合い — 階層構造を保つために複数のレイヤーが連動して適応します。すべて自動で組み込まれています

---

スクロールエッジエフェクト

スクロールエッジエフェクトは、コンテンツがスクロールすると背景に溶け込ませ、動くコンテンツの上にガラスを浮かび上がらせます。固定されたアクセサリービュー（列ヘッダーなど）がある場合は、視覚的な分離を強めるために .scrollEdgeEffect(.hard) を使用してください。API の詳細は axiom-liquid-glass-ref を参照してください。

---

色合いとカラー

Liquid Glass では アダプティブな色合い が導入されました。カラーを選択すると、下にあるコンテンツの明るさに合わせた色調が生成されます。これは、現実世界の色付きガラスに着想を得ています。ガラスのすべての動作（モーフィング、適応、インタラクション）と互換性があります。

色合いのルール

// ✅ Tint primary actions only
Button("View Bag") { }.tint(.red).glassEffect()

// ❌ Don't tint everything — when everything is tinted, nothing stands out
VStack {
    Button("Action 1").tint(.blue).glassEffect()
    Button("Action 2").tint(.green).glassEffect()  // No hierarchy
}

// ❌ Solid fills break Liquid Glass character
Button("Action") { }.background(.red)  // Opaque, wrong

// ✅ Use .tint() instead of solid fills
Button("Action") { }.tint(.red).glassEffect()  // Grounded in environment

色合いは主要な UI アクションに限定してください。アプリ全体の配色には、コンテンツレイヤーでカラーを使用してください。

---

視認性とコントラスト

SwiftUI はガラスエフェクト内で 鮮やかなテキストカラーと色合い を自動的に使用するため、手動で調整する必要はありません。小さな要素（ナビゲーションバー、タブバー）は、見分けやすくするためにライトとダークが切り替わります。大きな要素（メニュー、サイドバー）は適応しますが、切り替わりません（広い面積では気が散るためです）。シンボルやグリフはガラスの動作に合わせて変化し、コントラストを自動的に最大化します。

明確な機能上の目的がある場合は、カスタムの色合いを選択して使用してください（たとえば、強調するために単一のツールバーボタンに .tint(.orange) を指定します）。

---

アクセシビリティ

Liquid Glass には、その魅力を損なうことなく マテリアルを調整するアクセシビリティ機能がいくつかあります。

透明度を下げる

• Liquid Glass の曇りを強くします
• 背後のコンテンツをより多く覆い隠します
• システム設定が有効な場合に自動で適用されます

コントラストを上げる

• 要素を主に黒または白にします
• コントラストのある境界線でハイライトします
• システム設定が有効な場合に自動で適用されます

モーションを減らす

• エフェクトの強さを抑えます
• 弾性のある動作を無効にします
• システム設定が有効な場合に自動で適用されます

開発者側での対応は不要です。Liquid Glass を使用すると、すべての機能が自動的に利用できます。

---

パフォーマンスに関する考慮事項

ビューヒエラルキーへの影響

懸念事項：複雑なビューヒエラルキーにおける Liquid Glass のレンダリングコスト

指針：

• 通常のバリアントはパフォーマンス向けに最適化されています
• 大きな要素（メニュー、サイドバー）はより顕著なエフェクトを使用しますが、システムが管理します
• ガラス要素を過度に入れ子にしないでください

最適化：

// ❌ Avoid deep nesting
ZStack {
    GlassContainer1()
        .glassEffect()
    ZStack {
        GlassContainer2()
            .glassEffect()
        // More nesting...
    }
}

// ✅ Flatten hierarchy
VStack {
    GlassContainer1()
        .glassEffect()

    GlassContainer2()
        .glassEffect()
}

レンダリングコスト

アダプティブな動作には計算コストがかかります：

• ライト／ダークの切り替え
• シャドウの調整
• 色合いの計算
• レンズ効果

システムが最適化を処理しますが、次の点に注意してください。

• Liquid Glass 要素を不必要にアニメーションさせないでください
• Clear バリアントは控えめに使用してください（減光レイヤーの計算が必要です）
• パフォーマンスの問題が発生した場合は、Instruments でプロファイルしてください

---

Liquid Glass のテスト

次の構成でテストしてください。

• ライト／ダークモード
• 透明度を下げる機能を有効化
• コントラストを上げる機能を有効化
• モーションを減らす機能を有効化
• ダイナミックタイプ（大きな文字サイズ）
• コンテンツのスクロール（スクロールエッジエフェクトを確認）
• 右から左に記述する言語

視覚的なリグレッションテストやアクセシビリティテストなど、包括的な UI テストパターンについては axiom-ui-testing を参照してください。

---

デザインレビューのプレッシャー：実装を守る

問題点

デザインレビューでプレッシャーを受けると、次のような要望を受けることがあります。

• 「Clear バリアントをどこでも使ってください。Regular は不透明すぎます」
• 「見た目に統一感を出すため、すべてのコントロールにガラスを使ってください」
• 「コンテンツを透けさせるため、透明度をもっと上げてください」

もっともらしく聞こえます。しかし、これらはフレームワークに反しています。 あなたの役割は、意見ではなく根拠を示して実装を守ることです。

危険信号 — スキルのガイドラインに違反するデザイナーからの依頼

次のいずれかを聞いたら、作業を止めて、スキルを参照してください。

• ❌ 「どこでもClearを使う」 — Clearには、デザイン上の好みではなく、満たすべき具体的な条件が3つあります
• ❌ 「塗りつぶしよりGlassのほうが見栄えがよい」 — 見た目よりも、適切なレイヤー（ナビゲーションとコンテンツ）が優先されます
• ❌ 「ユーザーは違いに気づかない」 — コントラストが低い状況では、Clearバリアントは可読性テストに合格しません
• ❌ 「一貫性のため、GlassをGlassの上に重ねる」 — 明確に禁止されています。代わりに塗りつぶしを使用してください
• ❌ 「洗練された印象にするため、リストにGlassを適用する」 — リストはコンテンツレイヤーに属するため、視覚的な混乱を招きます

専門家として異議を伝える方法

ステップ1：フレームワークを示す

"I want to make this change, but let me show you Apple's guidance on Clear variant.
It requires THREE conditions:

1. Media-rich content background
2. Dimming layer for legibility
3. Bold, bright controls on top

Let me show which screens meet all three..."

ステップ2：リスクを実証する

デバイスでアプリを開き、次の内容を示します。

• コントラストが低い状況でのClearバリアント（判読不能）
• 同じ状況でのRegularバリアント（判読可能）

ステップ3：妥協案を提示する

"Clear can work beautifully in these 6 hero sections where all three conditions apply.
Regular handles everything else with automatic legibility. Best of both worlds."

ステップ4：決定を記録する

覆された場合（デザイナーがどこでもClearを使うよう主張した場合）：

Slack message to PM + designer:

"Design review decided to use Clear variant across all controls.
Important: Clear variant requires legibility testing in low-contrast scenarios
(bright sunlight, dark content). If we see accessibility issues after launch,
we'll need an expedited follow-up. I'm flagging this proactively."

この方法が有効な理由

• 相手の好みを否定しているのではありません（あなたもClearを気に入っています）
• アクセシビリティと可読性のリスクを指摘しています
• ヒーローセクションでは相手のビジョンを維持できる解決策を提案しています
• 決定を記録しています（ローンチ後にあなたを守ります）

実例：App Store公開を阻む問題（期限まで36時間）

状況

• 公開まで36時間
• チーフデザイナーが「どこでもClearバリアント」と指示
• クライアントがレビュー会議に同席
• スキルに従って、すでにRegularを実装済み

対応方法

// In the meeting, demo side-by-side:

// Regular variant (current implementation)
NavigationBar()
    .glassEffect() // Automatic legibility

// Clear variant (requested)
NavigationBar()
    .glassEffect(.clear) // Requires dimming layer below

// Show the three-condition checklist
// Demonstrate which screens pass/fail
// Offer: Clear in hero sections, Regular elsewhere

結果

• 30分の妥協案デモ
• 変更の実装に90分
• 最適な可読性を確保して予定どおりに公開
• 公開後にアクセシビリティに関する苦情なし

設計上の決定を受け入れるべき場合（たとえ意見が違っても）

デザイナーがスキルの適用を覆すことに妥当な理由がある場合もあります。次の条件を満たす場合は受け入れてください。

• 3つの条件から成るフレームワークを理解している
• 可読性のリスクを受け入れる意思がある
• 決定を書面で記録する
• 公開後のフィードバックを監視することに合意している

Slackに記録する

"Design review decided to use Clear variant [in these locations].
We understand this requires:
- All three conditions met: [list them]
- Potential legibility issues in low-contrast scenarios
- Accessibility testing across brightness levels

Monitoring plan:
- Gather user feedback first 48 hours
- Run accessibility audit
- Have fallback to Regular variant ready for push if needed"

これにより、双方が守られ、あなたが妨げているのではなく、リスクを軽減していることが示されます。

---

エキスパート向けレビューのチェックリスト

Liquid Glassの実装（自分または他者のコード）をレビューするときは、次の点を確認します。

1. マテリアルの適切性

• Liquid Glassはナビゲーションレイヤーでのみ使用されていますか（コンテンツではなく）？
• 標準コントロールは、Xcode 26で再コンパイルすると自動的にGlassになりますか？
• GlassがGlassに重なる状況を避けていますか？

2. バリアントの選択

• ほとんどの場合、Regularバリアントを使用していますか？
• Clearバリアントを使用する場合、3つの条件すべてに該当しますか？
  • メディアが豊富なコンテンツの上ですか？
  • ディミングレイヤーを許容できますか？
  • その上のコンテンツは太字で明るいですか？
• 同じインターフェースでRegularとClearを混在させていませんか？

3. 可読性とコントラスト

• 主要なアクションにのみ選択的に色を付けていますか（すべてではなく）？
• アプリ全体の配色には、コンテンツレイヤーで色を使用していますか？
• Glass要素にベタ塗りを使用していませんか？
• さまざまな背景上で、要素の可読性を保てていますか？

4. レイヤリングと階層

• 安定状態でコンテンツとの交差を避けていますか？
• Glassの上に配置する要素には、Glassではなく塗りつぶしや透明度を使用していますか？
• 視覚的な階層（ナビゲーションレイヤーとコンテンツレイヤー）が明確ですか？

5. スクロールエッジエフェクト

• Liquid Glassがスクロールするコンテンツと接する箇所に、スクロールエッジエフェクトを適用していますか？
• 固定されたアクセサリビューにハードスタイルを使用していますか？

6. アクセシビリティ

• 実装は「透明度を下げる」設定でも動作しますか？
• 実装は「コントラストを上げる」設定でも動作しますか？
• 実装は「視差効果を減らす」設定でも動作しますか？
• すべての設定で、インタラクティブ要素をタップできますか？

7. パフォーマンス

• ビューヒエラルキーは適切にフラット化されていますか？
• Glass要素は必要な場合にのみアニメーションしますか？
• Clearバリアントを控えめに使用していますか？

---

よくある間違いと解決策

Glassの配置ミス

// ❌ Glass on content layer — competes with navigation
List(landmarks) { landmark in
    LandmarkRow(landmark).glassEffect()
}

// ✅ Glass on navigation layer only
.toolbar {
    ToolbarItem { Button("Add") { }.glassEffect() }
}

// ❌ Clear without dimming — poor legibility
ZStack {
    VideoPlayer(player: player)
    PlayButton().glassEffect(.clear)
}

// ✅ Clear with dimming layer
ZStack {
    VideoPlayer(player: player)
        .overlay(.black.opacity(0.4))
    PlayButton().glassEffect(.clear)
}

色合いの付けすぎ

色合いを付けるのは主要なアクションだけにしてください。すべてに色合いを付けると、目立つものがなくなります。

静的なマテリアルの想定

影や不透明度を固定値でハードコードしないでください。適応的な動作を活用し、ライトモード／ダークモードや背景を変えてテストしてください。

---

トラブルシューティング

視覚的な問題

問題：ガラスが透けすぎる、または見えない

確認事項：

1. Clear バリアントを使用していますか？（適切でない場合は Regular に切り替えてください）
2. 背景のコンテンツが極端に明るい、または暗いですか？（ガラスは適応します。これが正しい動作である可能性があります）
3. 透明度を下げる設定が有効になっていますか？（アクセシビリティ設定を確認してください）

問題：ガラスが不透明に見える、または境界が鋭すぎる

確認事項：

1. ガラスに単色の塗りつぶしを使用していますか？（削除して、色合いを付けてください）
2. コントラストを上げる設定が有効になっていますか？（想定される動作です）
3. カスタムシェイプが複雑すぎませんか？（形状を単純化してください）

ダークモードの問題

問題：暗い背景でもガラスがダークスタイルに切り替わらない

確認事項：

1. 要素が大きい（メニュー、サイドバーなど）ですか？（大きな要素は設計上、切り替わりません）
2. 背景は実際に暗いですか？（カラー選択ツールで確認してください）
3. 外観を上書きしていますか？（意図しない場合は .preferredColorScheme() を削除してください）

問題：ダークモードでガラス上のコンテンツが読みにくい

修正方法：

// Let SwiftUI handle contrast automatically
Text("Label")
    .foregroundStyle(.primary) // ✅ Adapts automatically

// Don't hardcode colors
Text("Label")
    .foregroundColor(.black) // ❌ Won't adapt to dark mode

パフォーマンスの問題

問題：Liquid Glass を使うとスクロールがぎこちない

デバッグ方法：

1. Instruments でプロファイルします（axiom-swiftui-performance スキルを参照）
2. ビューの body が過剰に更新されていないか確認します
3. ガラスの下のビュー階層を単純化します
4. コンテンツレイヤーにガラスを適用していないことを確認します（パフォーマンスに大きな影響があります）

問題：アニメーションがカクつく

確認事項：

1. ガラスの形状変化をアニメーション化していますか？（負荷が高くなります）
2. SwiftUI Instrument で長時間かかるビュー更新をプロファイルします
3. クリティカルパスであれば、ガラスの使用を減らすことを検討してください

---

以前のマテリアルからの移行

UIBlurEffect / NSVisualEffectView からの移行

移行前（UIKit）：

let blurEffect = UIBlurEffect(style: .systemMaterial)
let blurView = UIVisualEffectView(effect: blurEffect)
view.addSubview(blurView)

移行後（Liquid Glass を使った SwiftUI）：

ZStack {
    // Content
}
.glassEffect()

メリット：自動的な適応（スタイルの手動切り替えが不要）、組み込みの操作フィードバック、プラットフォームに適した外観、アクセシビリティ機能を搭載しています。

カスタムマテリアルからの移行

1. まず Liquid Glass を試してください — 求める効果が自動的に得られる場合があります
2. Regular と Clear を評価してください — Clear はカスタムの透明度の要件に合う場合があります
3. さまざまな構成でテストしてください — Liquid Glass は自動的に適応します

カスタムマテリアルを維持する場合：Liquid Glass では実現できない特定の芸術的効果が必要な場合、iOS < 26 との後方互換性が必要な場合、または Liquid Glass の原則と互換性のない非標準の UI パラダイムを使用している場合です。

UIKit と SwiftUI の相互運用

段階的に移行する場合、ガラス効果はフレームワークごとに適用されます：

• SwiftUI のビューには .glassEffect() / .glassBackgroundEffect() を適用します
• UIKit のビューには UIKit の Liquid Glass API を使用します（移行対応表は axiom-liquid-glass-ref を参照）
• UIHostingController 内にホストされた SwiftUI のビューには、独立してガラス効果が適用されます

UIBlurEffect の完全な移行対応表は axiom-liquid-glass-ref を参照してください。

---

後方互換性

UIDesignRequiresCompatibility キー（iOS 26）

最新の SDK でビルドしながら、以前の外観を維持するには：

<key>UIDesignRequiresCompatibility</key>
<true/>

効果：iOS 26 SDK でビルドされたアプリの外観が iOS 18 以前と一致し、Liquid Glass 効果が無効になり、以前のぼかし／マテリアルのスタイルが使用されます。

使用する場合：インターフェイスの変更を監査する時間が必要な場合、段階的な導入戦略を取る場合、または一時的に外観を正確に維持する場合です。

移行戦略：

1. UIDesignRequiresCompatibility を有効にしてリリースします
2. 別のビルドでインターフェイスの変更を監査します
3. インターフェイスを段階的に更新します
4. Liquid Glass に移行する準備ができたら、このキーを削除します

---

API リファレンス

glassEffect()、glassBackgroundEffect()、ツールバーのモディファイア、スクロールエッジ効果、ナビゲーション／検索 API、コントロール／レイアウト、GlassEffectContainer、glassEffectID、型、後方互換性を含む完全な API リファレンスは axiom-liquid-glass-ref を参照してください。

---

リソース

WWDC：2025-219、2025-256、2025-323（新しいデザインで SwiftUI アプリを構築する）

ドキュメント：/technologyoverviews/adopting-liquid-glass、/swiftui/landmarks-building-an-app-with-liquid-glass、/swiftui/applying-liquid-glass-to-custom-views

スキル：axiom-liquid-glass-ref

---

プラットフォーム： iOS 26+、iPadOS 26+、macOS Tahoe、axiom-visionOS 3 Xcode： 26+ 履歴： 変更内容については git log を参照してください