Jetpack Compose Semantics 設計でAIエージェントにUIを理解させる

はじめに

Jetpack Compose には内部的に Semantics Tree という仕組みがあります。これはアクセシビリティ・UIテスト・自動操作AIなどが参照する「UIの意味構造」です。

Semantics をしっかり設計することで、AIエージェントは画面上の要素を「色・位置・サイズ」ではなく「何のボタンか・押すと何が起きるか・今どんな状態か」として理解できるようになります。

主要な Semantics 属性

contentDescription

アイコンだけのボタンなど、見た目だけでは意味がわからないUI要素に必須です。

IconButton(
    onClick = onDelete,
    modifier = Modifier.semantics {
        contentDescription = "削除"
    }
) {
    Icon(Icons.Default.Delete, contentDescription = null)
}

AI・アクセシビリティ側には「削除ボタン（クリック可能）」として認識されます。

role

カスタムUIに role を付けると、AI が UI 種別を明確に理解できます。

Modifier.semantics {
    role = Role.Button
}

Box(clickable) のみだと「クリック可能な何か」ですが、role を付与すれば Button / Switch / Checkbox / Tab など具体的な種別として伝わります。

stateDescription

現在の状態をAIに伝えるための属性です。

Modifier.semantics {
    stateDescription =
        if (subscribed) "購読中"
        else "未購読"
}

TalkBack だけでなく、AIエージェントが「今は停止中だから再生ボタンを押そう」のような状態ベースの判断を行う際に活用されます。

testTag

AI自動操作・UI テストにおいて最も重要な属性のひとつです。

Modifier.testTag("login_button")

一意の識別子を付与することで、Compose UI Test・Appium・UIAutomator 連携・MCP ベースのエージェントから安定して要素を取得できます。

UIAutomator 連携に必要な設定

Compose は View 階層を直接生成しないため、デフォルトでは UIAutomator から testTag が参照できない場合があります。ルートに以下を設定することで解決します。

Scaffold(
    modifier = Modifier.semantics {
        testTagsAsResourceId = true
    }
)

これにより testTag が resource-id として UIAutomator から参照可能になります。

実践：AIに最も理解されやすい設計

Button(
    onClick = login,
    modifier = Modifier
        .testTag("login_button")
        .semantics {
            contentDescription = "ログイン"
            role = Role.Button
        }
) {
    Text("ログイン")
}

複雑なUIをひとつの意味にまとめる

アイコン・テキスト・Badge など複数要素で構成されるUIは clearAndSetSemantics でひとつの意味として提示できます。

Modifier.clearAndSetSemantics {
    contentDescription = "商品をカートに追加"
    role = Role.Button
}

AIは見た目の複雑さやネスト構造を無視し、論理的な意味だけを受け取ることができます。

Semantics 設計で得られる効果

1. 自動操作が UI 変更に強くなる

testTag による識別は、座標・OCR・テキストの変更に依存しません。ボタンの位置や見た目が変わっても、タグが同じなら自動操作は壊れません。

2. MCP で画面意味解析が可能になる

Semantics Tree を取得することで、画面情報を以下のような軽量な構造化データとして扱えます。

[
  {"role": "Button", "label": "ログイン", "enabled": true, "tag": "login_button"},
  {"role": "TextField", "label": "メールアドレス"}
]

3. スクリーンショット依存を減らしトークンを削減

画像解析は大量のトークンを消費します。Semantics Tree を使えば同じ情報を超軽量なテキストデータとしてAIに渡せます。長時間の自動操作や全画面巡回など、コンテキスト消費を抑えたいシナリオで特に効果的です。

4. AIが状態機械として画面を理解できる

stateDescription の情報から、AIは現在の状態を把握し「今は停止中だから再生ボタンを押す」といった文脈ベースの判断ができます。

5. AIによるテストケース自動生成

Semantics から「ログインボタンが存在する → 押す → ホーム画面が表示される」のような遷移情報を取得し、テストケースの自動生成にも応用できます。

Web の ARIA に相当する役割

Web 開発における HTML / ARIA / DOM に相当するものが、Android における Compose Semantics Tree です。AIエージェントは「見た目のUI」ではなく「意味のDOM」を通じてアプリを理解します。

Compose は「見た目」と「意味」を分離して設計できる点が強みです。これが Semantics 設計の本質であり、AIとの連携基盤になります。

まとめ

MCP・UIAutomator・AIエージェントを活用するなら、各コンポーネントへの testTag と semantics の標準付与が、安定した自動化の土台になります。