display-glasses-with-jetpack-compose-glimmer

用語集

用語	定義
インテリジェントアイウェア	情報にアクセスできる、終日装着可能なハンズフリーデバイスです。スピーカー、カメラ、マイクを搭載しています。音声のみのもの（オーディオグラス）と、ディスプレイも搭載したもの（ディスプレイグラス）があります。
ディスプレイグラス	オーディオグラスに、音声出力と調和する、一目で確認できるビジュアルを表示するレンズ内のプライベートディスプレイを追加したものです。
Jetpack Compose Glimmer	拡張 Android XR エクスペリエンスの構築に使用する Compose UI ツールキットで、ディスプレイグラス向けに最適化されています。透明ディスプレイ向けのコンポーネント、テーマ、動作を提供します。
Projected Activity（Glasses Activity）	ホストデバイス（スマートフォン）上で実行される Android の Activity ですが、UI とインタラクションは、接続されたインテリジェントアイウェアデバイス（オーディオグラスまたはディスプレイグラス）に投影されます。
Projected Device	Android 搭載デバイス（ホスト）に接続された XR デバイスです。ホストはアプリケーションのコンテンツを Projected Device に投影し、ユーザーが操作できるようにします。
GlimmerTheme	GlimmerColors、GlimmerTypography、GlimmerShapes などのスタイルトークンを提供するルートプロバイダーです。
加算型ディスプレイ	黒（#000000）が 100% 透明として描画されるディスプレイ技術です。環境に光を加えることで UI を構築します。ディスプレイグラスには加算型ディスプレイが搭載されています。
拡張エクスペリエンス	現実世界でのユーザーの集中と存在感を高める Android XR エクスペリエンスです。軽量で、環境に要素を追加する形で、外出中のユーザーをサポートします。
視角	XR で知覚されるサイズを測る単位です。読み取り可能なテキストの最小サイズは 0.6 度（1 m で約 18sp）です。

前提条件

• モバイルプロジェクトの compileSdk は 37 以上を対象にする必要があります。compileSdk が 37 未満の場合は、37 に引き上げてください。
• インテリジェントアイウェア向けの最初のアクティビティを作成するの最新のライブラリ依存関係を使用していることを確認してください。

主な制約

• 禁止: MaterialTheme や Material Components は使用しないでください。
• 推奨: GlimmerTheme と Jetpack Compose Glimmer コンポーネントを使用してください。
• 推奨: コンポーネント全体で一貫したタイポグラフィを適用するため、GlimmerTheme の Typography 値には androidx.xr.glimmer:glimmer-google-fonts の createGoogleSansFlexTypography() を使用してください。

制限事項

• 特定のハードウェアデバイスのモデルや固有の機能については詳述していません。
• Elevation: 標準の Material 3 のシャドウまたは elevation 修飾子はサポートされていません。Jetpack Compose Glimmer の ShadowScope または Depth トークンを使用する必要があります。
• 最小サイズ: 読み取り可能な絶対最小サイズは 18sp（0.6°）です。これより小さいサイズは可読性チェックに合格しません。
• テキストの太さ: 「Thin」や「Hairline」のウェイトは避けてください。加算型 AR レンズでちらつきやエイリアシングが発生します。

1. 依存関係のセットアップ

• Projected Activity のセットアップ： まず、アプリ用に新しい Projected Activity を作成する必要があります。プロジェクトにまだない場合は、インテリジェントアイウェア向けの最初のアクティビティを作成するをご覧ください。references/projectedcontext-source.mdを使用して、Projected Device で Glasses Projected Activity を起動します。システムにこれが Projected Activity であることを伝えるため、アプリのマニフェストで android:requiredDisplayCategory 属性に android.hardware.display.category.XR_PROJECTED を指定してください。
• モバイルアプリとの統合： プロジェクトに既存のモバイルアプリがある場合は、Glimmer UI の描画専用の新しい Glasses Activity を作成する必要があります。詳しい設定については、インテリジェントアイウェア向けの最初のアクティビティを作成するを参照してください。Glasses Activity を起動する方法がまだない場合は、既存のモバイルアプリの UI に「Launch on Glasses」というラベルのボタンを追加し、ProjectedContext を使用してメガネ上で Glasses Activity を起動します。ユーザーが投影機能に気づきやすいよう、「Launch on Glasses」ボタンは画面レベルの FloatingActionButton、TopAppBar、またはトップナビゲーションバーに配置してください。メガネが接続されていない場合は、ボタンを無効にします。Glasses Activity はスマートフォンではなく、ディスプレイ付きメガネでのみ起動してください。明示的な起動ボタンなしで Glasses Activity を自動的に起動するのが適切な場合は、そのようにしてください。
• UI ライブラリ： プロジェクトに androidx.xr.glimmer:glimmer ライブラリがあるか確認してください。ない場合は、プロジェクトに追加する必要があります。最新の依存関係のバージョンを取得するには、Jetpack Compose Glimmer の依存関係の宣言をご覧ください。
• テーマ設定： すべての Glimmer コンポーネントは、トークンが正しく解決されるよう、GlimmerTheme コンポーザブルでラップする必要があります。
• 必須の黒い背景： ディスプレイ付きメガネは加算型ディスプレイを使用します。背景に黒以外の色があると、現実世界が遮られます。Projected Activity のルートコンテナには、必ず純粋な黒の背景（Modifier.background(Color.Black)）を設定してください。
• フォント： デフォルトのフォントは Google Sans Flex です。特に指定がない限り、デフォルトのテキストスタイルを使用するために androidx.xr.glimmer.googlefonts ライブラリを使用してください。createGoogleSansFlexTypography を使用して、Google Sans Flex の設定を適用した Typography インスタンスを作成します。この Typography インスタンスは、通常どおり GlimmerTheme に渡してください。設定については、references/glimmersansflextypography-source.mdをご覧ください。
• ハードウェア機能： インテリジェントアイウェアデバイスの種類によって、利用できる機能は異なります。実行時に機能を確認する方法については、インテリジェントアイウェアのデバイス機能を実行時に確認するをご覧ください。
• ハードウェアの権限： マイクやカメラなどのハードウェア権限をリクエストする方法については、インテリジェントアイウェアのハードウェア権限をリクエストするをご覧ください。
• ハードウェアへのアクセス： メガネのカメラやセンサーを使用する方法、またはスマートフォンのハードウェアにアクセスする方法については、Projected Context を使用してインテリジェントアイウェアのハードウェアにアクセスするをご覧ください。

2. UI を最小限にして翻訳する

• ディスプレイグラス向けの UI は、Jetpack Compose Glimmer フレームワークのコンポーネントを使用して構築します。
• 奥行きを使って、要素の優先度と階層を伝えます。
• UI が現実世界を覆う範囲をできる限り小さくするため、下から設計します。UI は常にグラスのディスプレイの下端に配置してください。
• 一度に一つの情報のみ： ユーザーが現実世界に意識を向けられるよう優先します。ユーザーの視野を遮る範囲を最小限にするため、一度に表示する主要な情報は一つだけにします（たとえば、Stack を使用します）。複数のカードを同時に表示しないでください。
• 色のコントラスト： HCT 色空間を使用して、前景と背景の色調の差が少なくとも 70% になるようにします。計算方法については、references/material-hct-source.md を参照してください。

3. 入力コントロールを割り当てる

• タップやスワイプなどのアプリの操作を、タッチパッドなど、グラスで利用できるハードウェアコントロールに割り当てます。
• 入力は一次元です。ユーザーが一度に操作できるコントロールは一つだけです。
• スクロール可能なコントロールを入れ子にしないでください。
• Jetpack Compose Glimmer のコンポーネントは、グラスのタッチパッドでのタップやスワイプなど、標準的な入力方法に対応するよう設計されています。
• 一時的な状態や詳細ビューを閉じるには、システムの戻る操作を使用します。
• Glasses UI に入力、フォーカス、タップ、スワイプを追加するには、Focus in Jetpack Compose Glimmer に従ってください。
  • ハードウェア入力の詳細については、Hardware Controls for display glasses を参照してください。

4. Jetpack Compose Glimmer で構築する

Jetpack Compose Glimmer は、ディスプレイグラス向けの拡張体験を構築するための UI ツールキットです。

主な機能

• Glimmer のテーマ設定： 視認性を最適化する、グラス専用のシンプルなテーマです。
• 入力に標準対応： タップとスワイプにデフォルトで対応しています。
• 事前構築済みのコンポーネント： Card、ListItem、Button など、最適化されたコンポーザブルを提供します。

Glimmer でのフォーカス管理

• Jetpack Compose Glimmer は一次元のフォーカス検索を使用します。
• スクロール可能なコンテナではフォーカスが連続的に移動し、ボタンが横に並んだ列などの要素では離散的に移動します。
• システムが初期フォーカスを自動的に設定できるようにするには、アクティビティの onCreate メソッドで isInitialFocusOnFocusableAvailable フラグを true に設定する必要があります。実装方法については、Focus in Jetpack Compose Glimmer を参照してください。

Glimmer スタイルの実装

Glimmer スタイルには GlimmerTheme オブジェクトからアクセスできます。リファレンスとして references/glimmertheme-source.md を使用してください。

カテゴリ	トークン	値／役割
色	primary	#9BBFFF（フォーカルカラー）
色	secondary	#4C88E9（フォーカルカラー）
色	surface	#262626（透明なベース。透明として描画されます）
色	outline	#606460（3.dp の境界線の色）
形状	標準	RoundedCornerShape(36.dp)
形状	小	RoundedCornerShape(12.dp)

タイポグラフィスケール（Google Sans Flex）

厳守事項： Glimmer UI を作成する際は、カスタムブランド書体が明示的に指定されていない限り、Google Sans Flex を使用する必要があります。 可変フォントの設定： Google Sans Flex は可変フォントのため、以下の軸を設定する必要があります。

• 丸み（ROND）： 特徴的な丸みのある外観にするため、常に 100f に設定します。
• 幅（wdth）： 100f に設定します。
• オプティカルサイズ（opsz）： 9f に設定します。
• ウェイト（wght）： 役割に応じて以下の値を使用します（タイトル：725f、本文：520f、キャプション：650f）。

スタイル名	サイズ / 行の高さ	ウェイト軸	幅	丸み	オプティカルサイズ
大見出し	30.sp / 36.sp	725	100	100	9
中見出し	24.sp / 32.sp	725	100	100	9
小見出し	20.sp / 28.sp	725	100	100	9
大本文	30.sp / 36.sp	520	100	100	9
中本文	24.sp / 32.sp	520	100	100	9
小本文	20.sp / 28.sp	520	100	100	9
キャプション	18.sp / 28.sp	650	100	100	9

深度レベル

ディスプレイグラス上では、影を使って深度を表現し、強調の度合いを変えることで階層感を生み出します。Jetpack Compose Glimmer のコントロールでは、5 つのプリセット DepthEffectLevels を持つ DepthEffect を使用します。参考資料として、references/deptheffect-source.md と references/deptheffectlevels-source.md を参照してください。

例：

レベル	用途
level1	カードや常時表示される背景 UI の標準的な通常状態。
level2	ボタンや操作可能なカードの標準的なフォーカス時／押下時の状態。
ExtraSmall	4.dp

Jetpack Compose Glimmer コンポーネントの実装

カード

カードは Glimmer で使用される基本的なサーフェスベースのコンテナーです。テキスト、画像、アイコン、アクションなどの関連コンテンツをまとめ、1 つの注目ポイントにします。Glasses 環境で明確な深度面（Z 軸）を作り、テキスト、画像、アイコンの安定した背景を提供します。リストアイテムの中にカードを埋め込まないでください。

実装の基本ロジック

• サーフェス階層： カードはベースサーフェス上、またはリスト内に配置するよう設計されています。onClick ラムダを指定すると、フォーカス時に視覚的なフィードバックが自動的に表示されます。
• インタラクティブ性：
  • IF カード全体を単一のトリガー（メディアアイテムや設定など）として使う場合：THEN フォーカス効果を有効にするため、onClick ラムダを指定します。
  • ELSE： カード内に個別のボタンやスイッチなど複数のインタラクティブ要素がある場合は、フォーカスの競合を避けるため、onClick を null のままにします。

技術ドキュメントへのリンク

Glimmer のカードコンポーネントを作成する場合は、以下を参照してください。

• 開発者向けガイダンス： Jetpack Compose Glimmer: Cards
• API ソースコード： references/card-source.md を使用してください。
• 実装サンプル： references/card-samples-source.md を使用してください。（基本的なカードとインタラクティブなカードの使用方法）

ボタン

ボタンは、Glimmer で個別のアクションを実行するための主なトリガーです。ディスプレイグラスのフォーカスモデル向けに最適化されており、タッチパッドなどを使ってボタンにフォーカスを移動すると、フォーカスハイライトが表示されます。

実装の基本ロジック

• Glimmer では、次の 2 種類のボタンから選択できます。
  • 標準ボタン（必須のテキストラベルと、任意の先頭または末尾のアイコン）。UI に十分なスペースがある場合や、テキストがないとボタンの意味が分かりにくい場合に使用します。
  • アイコンボタン（アイコンのみ）。アイコンボタンは、アイコンの意味が明確に伝わる場合にのみ使用します。
• アイコンボタンと標準ボタンのどちらにも、デフォルトとトグルのバリエーションがあります。
  • デフォルト（「購入」や「移動」などの単一アクションに使用）
  • トグル（ミュートボタンなど、選択状態を持つものに使用）

技術ドキュメントへのリンク

Glimmer Button コンポーネントを作成する場合は、以下をお読みください。

• 開発者向けガイダンス： Jetpack Compose Glimmer: Buttons
• API ソースコード： references/button-source.md を使用してください。
• 実装サンプル： references/button-samples-source.md を使用してください。

タイトルチップ

チップは、Card またはコンテンツのグループの上に配置してタイトルを示す、ピル型の専用ラベルコンポーネントです。タイトルチップは、短いタイトル、名前、ステータスなどの簡潔な情報を表示するために使用します。

ガイドラインと使用方法

• 空間的な間隔：コンテンツの前に単独の TitleChip を配置する場合は、視覚的な階層を保つために TitleChipDefaults.AssociatedContentSpacing（8.dp）を使用する必要があります。
• インタラクティブ性： タイトルチップは情報表示のみを目的としており、ナビゲーションの対象にしたり、アクティブにしたりすることはできません。
• レイアウト： タイトルチップ内のテキストは常に中央揃えにしてください。タイトルチップを2行にせず、余分な単語は省略してください。ラベルは3語以内にしてください。

技術ドキュメントへのリンク

Glimmer Title Chip コンポーネントを作成する場合は、以下をお読みください。

• 開発者向けガイダンス： Jetpack Compose Glimmer: Title Chips
• API ソースコード： references/titlechip-source.md を使用してください。
• 実装サンプル： references/titlechip-samples-source.md を使用してください。（グループコンテンツの上に配置するタイトルチップ）

アイコン

アイコンは、概念、アクション、ステータスを簡潔に表す視覚的な記号です。Glimmer では、XR 環境に適したアイコンとアイコンボタンを提供し、加算型ディスプレイでの明瞭な表示と、インタラクティブな要素に対する視線連動フィードバックを実現します。

ガイドラインと使用方法

• サイズ： 定義済みの IconSizes（Standard、Large など）を使用し、XR 環境でアイコンの視認性を保ち、最小タッチターゲットの要件を満たしてください。
• インタラクティブ性：
  • アイコンがトリガーとして機能する場合： 自動的な視覚フィードバックと必要なタップターゲットのパディングを提供するため、IconButton を使用する必要があります。
  • それ以外の場合： インタラクティブでないインジケーターやステータス記号には、単独の Icon を使用してください。
• コントラスト： アイコンの色合いに純粋な黒（#000000）を絶対に使用しないでください。暗い背景や実環境の背景でもアイコンが見えるよう、テーマカラーまたは標準の Glimmer コンテンツカラーを常に使用してください。
• アイコンライブラリ： 特に指定がない限り、デフォルトのアイコンライブラリは、ウェイト600、Rounded、Unfilled の Material Symbols です。

技術ドキュメントへのリンク

Glimmer Icon コンポーネントを作成する場合は、以下をお読みください。

• 開発者向けガイダンス： Jetpack Compose Glimmer: Icons
• API ソースコード（Icon）： references/icon-source.md を使用してください。
• API ソースコード（IconButton）： references/iconbutton-source.md を使用してください。
• API ソースコード（IconSizes）： references/iconsizes-source.md を使用してください。

リスト

リストは、メガネ上で複数の項目を移動して確認できるコンテナーです。一度にリスト内の1項目だけを表示するユースケースには、Glimmer Stack を使用してください。リスト内の項目の種類が似ている場合は、タイトルチップと組み合わせてリストを使用してください。項目の種類が異なる場合も、Glimmer Stack を使用してください。

ガイドラインと使い方

• ListItem のスロット： 行には ListItem コンポーザブルを使用します。あらかじめ定義されたスロットが用意されています。参考資料として references/listitem-source.md を使用してください。
• 視覚的な一貫性： 類似する項目のリストを作成する場合は、すべての項目で背景色（通常は GlimmerTheme.colors.surface）と角の半径（標準は 36.dp）を統一してください。異なる種類のコンテンツを視覚的にグループ化する場合を除き、これらを変更しないでください。
• 統合タイトルチップ： Glimmer List は統合タイトルチップに対応しています。リスト内にセクション見出しが必要な場合は、空間的な一貫性を保つため、独立した TitleChip を追加するのではなく、統合タイトルチップを有効にしてください。
• 垂直方向の配置： メガネ型ディスプレイ上で項目間に視覚的な間隔を確保するため、GlimmerLazyColumn では必ず verticalArrangement = Arrangement.spacedBy(20.dp) を使用してください。
• 特に指定がない限り、リスト項目間の既定の間隔である 20 dp を必ず使用してください。

技術ドキュメントへのリンク

Glimmer List コンポーネントを作成する場合は、以下をお読みください。

• API ソースコード（List）： references/list-source.md を参照してください。
• API ソースコード（ListItem）： references/listitem-source.md を参照してください。
• API ソースコード（GlimmerLazyListState）： references/liststate-source.md を参照してください。

スタック

スタックは、一度に 1 つのコンテンツだけを表示する、カードのように重ねて表示される折りたたまれたリストです。一度に複数の項目を表示する場合は、Glimmer List コントロールを使用してください。スタックではタイトルチップを使用しないでください。項目の種類が異なる場合は、スタックを使用して表示してください。項目の種類が同じ場合は、リストを使用してください。

ガイドラインと使い方

レイアウトのヒント

• スタックでは高さの異なる項目を使用できます。
• スタックコントロールをディスプレイの下端に揃えてください。
• スタックコントロールは、最も高さのある項目より 66 dp 高くする必要があります。これにより、スクラム用のスペースを確保し、項目間の移動時の動きを最小限に抑えられます。
• クリッピングとレイヤー： 最上部の項目の背後にある項目を正しくクリッピングして非表示にするには、すべての item ブロック内の Card（または関連するコンテナ）に .itemDecoration(CardDefaults.shape) 修飾子を適用する必要があります。
• 奥行きのシャドウ： 空間的な分離と要素の優先順位を維持するには、Glimmer の ShadowScope、DepthEffect、または規定の DepthEffectLevels を使用して、奥行きの平面スケーリングを行ってください。

技術ドキュメントへのリンク

Glimmer Stack コンポーネントを作成する場合は、以下をお読みください。

• API ソースコード（Stack）： references/stack-source.md を参照してください。
• API ソースコード（StackState）： references/stackstate-source.md を参照してください。
• API ソースコード（StackItemScope）： references/stackitemscope-source.md を参照してください。

テキスト

Jetpack Compose Glimmer の Text コンポーネントは、Compose のテキストコンポーネントを基にしており、さまざまなテキストプロパティを設定できます。テキストには GlimmerTheme のスタイルを選択してください。独自のタイポグラフィを使用する場合は、アプリケーションのテーマを変更してください。

重要な制約：Glimmer Text と Material Text

透明ディスプレイグラス（加算型ディスプレイ）では、標準の Material Text は暗い前景色トークンに解決され、透明として描画されて見えなくなります。 Glimmer Text はテーマの色のマッチングを適切に処理します。手動で色を上書きしない場合、Glimmer Text は最も近い Glimmer サーフェスから提供されるコンテンツカラーを自動的に既定値として使用します。

• 使用しないでください： Material Text
• 使用してください： Glimmer Text

サーフェス

Surfaceは、Glimmerの基本的な構成要素です。リファレンスとして references/surface-source.mdを参照してください。

サーフェスは、ボタンやカードなどのコンポーネントの、独立した視覚領域または「物理的な」境界を表します。カスタムコンポーネントを作成する必要がある場合に使用してください。

5. システム UI と統合する

• インテリジェントアイウェアの通知について詳しくは、インテリジェントアイウェアの通知動作についてを参照し、通知からディスプレイ付きメガネでアクティビティを開始する方法をご確認ください。