expo-liquid-glass

Expo Liquid Glass

iOS／Android でネイティブらしい見た目と読みやすさを保ち、安全にフォールバックする Liquid Glass UI を実装します。

実行順序

1. プラットフォーム／ランタイムの制約を確認します。
2. HIG の分類に照らしてデザインの整合性を確認します（デザインを重視するタスクでは推奨）。
3. 主な実装方法を 1 つ選びます（必要な場合に限り、2 つ目の方法を追加します）。
4. コードを書く前に、Apple に準拠したビジュアルルールを適用します。
5. 明示的なフォールバックを備えた、使用条件を確認するガラスコンポーネントを実装します。
6. ライト／ダーク、クリア／色付きの両方の外観で、アクセシビリティとビジュアルの QA を実施します。

1) 事前確認する制約

• Liquid Glass はコントロール／ナビゲーションのクロームにのみ使用し、主要なコンテンツ面には使用しないでください。
• これらの API は変更が速いため、構文を確定する前に Expo SDK の最新ドキュメントを確認してください。
• 高度な iOS ネイティブ機能には、開発ビルドが必要になると想定してください。 iOS の Expo Go では、expo-glass-effect と @expo/ui は安定して動作しません。
• 対象は Expo における Liquid Glass に限定してください。無関係な製品の動作を再設計するのではなく、実装の指針として HIG のルールを使用してください。

2) デザインの整合性（デザインを重視するタスクで推奨）

大幅なビジュアルデザインの判断を伴うタスクでは、以下の HIG 分類に照らして評価してください。

1. 基礎 マテリアル、色、レイアウト、モーション、アクセシビリティへの影響を確認します。
2. パターン ナビゲーション／検索／フローの動作が、システムの想定と一貫しているか確認します。
3. コンポーネント 画面で使用するバー、ボタン、メニュー、フィールド、サイドバー、オーバーレイを確認します。
4. 入力 タッチ、ジェスチャー、キーボード、ポインターの動作について、同等性と見つけやすさを確認します。

実践的なデザインガイダンスは references/apple-liquid-glass-design.md を参照してください。 提案されたスタイルが HIG の意図と矛盾する場合は、HIG に沿った選択肢を優先してください。

3) 主な実装方法を選択する

方法	用途	トレードオフ
expo-glass-effect	ガラスのチップ、フローティングボタン、ツールバー、グループ化されたコントロールが必要な、ほとんどの RN 画面	Expo でのデフォルトとして最適ですが、ランタイムでの利用可否を確認する必要があります
@expo/ui（Host + SwiftUI モディファイア）	ネイティブ SwiftUI の合成、高度なガラスのトランジション、連携する ID／名前空間	iOS 系プラットフォームのみ。開発ビルドのワークフローと SwiftUI のメンタルモデルが必要です
expo-router/unstable-native-tabs	システムネイティブの Liquid Glass タブバーと iOS 26 のナビゲーション動作	不安定な API です。構文は SDK 54 と 55 で異なります
@callstack/liquid-glass	Expo を使わない RN、または Callstack パッケージに統一するチーム	iOS／tvOS が中心ですが、フォールバックとランタイムチェックも必要です

適切な場合は、方法を組み合わせてください。

• ナビゲーションのクロームには、ネイティブタブを使用します。
• 画面内のフローティングコントロールには、expo-glass-effect を使用します。
• SwiftUI 固有の動作が必要な箇所に限り、@expo/ui を使用します。

4) Apple スタイルのデザインルール（重要）

ビジュアルを実装する前に、以下のルールを適用してください。

1. 装飾的なレイヤーではなく、レイアウトと余白で階層を表現します。
2. 関連するコントロールは共通のガラスクラスターにまとめ、無関係なグループは余白で分けます。
3. ガラスが背後のコンテンツを屈折できるよう、コンテンツをコントロールの背後まで画面端に沿って配置します。
4. まずシステムのコントロール／マテリアルを使い、カスタマイズは最小限にします。
5. 強いブランドカラーはナビゲーションバーではなく、コンテンツ／背景に使用します。
6. ライト、ダーク、クリア、色付きの各モードで、アイコン／ラベルのコントラストを高く保ちます。
7. 画面全体を覆うガラスシートは避け、最上位の操作面に限ってガラスを使用します。

5) 実装パターン

パターン A：使用条件を確認する適応型ガラスラッパー

import { Platform, View } from 'react-native';
import { BlurView } from 'expo-blur';
import { GlassView, isGlassEffectAPIAvailable } from 'expo-glass-effect';

export function AdaptiveGlass({ style, children }) {
  if (isGlassEffectAPIAvailable()) {
    return (
      <GlassView style={style} glassEffectStyle="regular" tintColor="#FFFFFF10">
        {children}
      </GlassView>
    );
  }

  if (Platform.OS === 'ios') {
    return (
      <BlurView style={style} intensity={40} tint="dark">
        {children}
      </BlurView>
    );
  }

  return <View style={[style, { backgroundColor: 'rgba(60,60,67,0.30)' }]}>{children}</View>;
}

パターン B：安全な expo-glass-effect の使用方法

• 必要に応じて glassEffectStyle に 'regular' | 'clear' | 'identity' を指定します。
• GlassView またはその親に opacity < 1 を設定しないでください。
• isInteractive はマウント時のみ設定できます。変更する必要がある場合は、key を使用して再マウントしてください。
• GlassView 内にスクロール可能なコンテンツを配置しないでください。
• 描画前に isGlassEffectAPIAvailable() で利用可能か確認してください。

パターン C：ネイティブタブ（SDK 固有の構文）

SDK 55 以降の複合 API：

<NativeTabs.Trigger name="index">
  <NativeTabs.Trigger.TabBarIcon
    ios={{ default: 'house', selected: 'house.fill' }}
    androidIconName="home"
  />
  <NativeTabs.Trigger.TabBarLabel>Home</NativeTabs.Trigger.TabBarLabel>
</NativeTabs.Trigger>

SDK 54 の API：

<NativeTabs.Trigger name="index">
  <NativeTabs.Trigger.Icon sf="house.fill" md="home" />
  <NativeTabs.Trigger.Label>Home</NativeTabs.Trigger.Label>
</NativeTabs.Trigger>

既知の問題：一部のスタックでは、画面をプッシュする際に透明な NativeTabs が白くちらつくことがあります。 ThemeProvider で背景色を設定して軽減してください（native-tabs のリファレンスを参照）。

パターン D：名前空間 ID を使った SwiftUI のガラス表現

連動するガラスのトランジションが必要な場合は、@expo/ui を使用してください。

import { Host, Namespace, Text } from '@expo/ui/swift-ui';
import { glassEffect, glassEffectID, padding } from '@expo/ui/swift-ui/modifiers';

const ns = new Namespace('glass');

<Host style={{ width: 220, height: 56 }}>
  <Text
    modifiers={[
      padding({ all: 16 }),
      glassEffect({ glass: { variant: 'regular' } }),
      glassEffectID({ id: 'primary-chip', in: ns }),
    ]}
  >
    Explore
  </Text>
</Host>;

6）アクセシビリティと品質ゲート

完了前に、次の項目を必ず実施してください。

• AccessibilityInfo.isReduceTransparencyEnabled() を確認し、ガラス表現を使わない代替表示を用意します。
• 明るい背景、暗い背景、高彩度の背景で読みやすさを確認します。
• iOS 26 で、クリアと色付きの両方のシステム表示モードを検証します。
• インタラクティブなアニメーション中も、タップ領域と間隔を一定に保ちます。
• ローエンドのテストデバイスで、ガラス表現の有無によるスクロール性能を測定します。

7）よくある失敗と対処法

• ヘッダーのぼかしが二重になる： ネイティブヘッダーのぼかしとカスタムのガラス表現の子要素が重なり、濁った見た目になります。ヘッダーのアクセサリーには、通常の半透明 View を使用してください。
• ガラス表現が平坦に見える： 単色の背景では屈折の手がかりがなくなります。サーフェスの背後に色調の変化、グラデーション、または画像を加えてください。
• コントロールを過度にカスタマイズする： 強い色合い、枠線、影を重ねると、ネイティブらしさが損なわれます。まずシステムのデフォルト設定を使い、その後、控えめに調整してください。
• 実行時のガードがない： ガラス表現の API をガードなしでレンダリングすると、未対応のビルドでクラッシュしたり、気付かないうちに表示が劣化したりすることがあります。
• バージョンのずれ： NativeTabs と SwiftUI ラッパーは急速に進化するため、コーディング前に SDK 固有のドキュメントを確認してください。

8）リファレンスの読み込み方針

タスクに必要なものだけを読み込んでください。

• references/expo-ui-swiftui.md：SwiftUI コンポーネントの対応関係、Host のレイアウト、モディファイアのパターン。
• references/native-tabs.md：ネイティブタブの動作、移行に関する注意点、既知の問題。
• references/callstack-liquid-glass.md：Callstack のセットアップと互換性のトレードオフ。
• references/apple-liquid-glass-design.md：Apple のガイドラインに沿った構成、階層、動き、アクセシビリティのルール。

API よりもデザインが重視されるリクエストの場合は、まずこのファイルに記載された Apple のビジュアルルールを優先し、 その後、関連するリファレンスから API の構文を確認してください。