Android Ui Guidelines

1. 基本原則

• Jetpack Compose を第一選択にする。 新規画面は Compose、既存 View 資産は段階移行。
• Material Design 3（M3）に準拠する。 独自テーマより MaterialTheme をカスタマイズ。
• Dynamic Color を尊重する。 Android 12+ ではユーザーの壁紙由来のカラーを使用。
• Edge-to-Edge をデフォルト化する。 Android 15（API 35）+ は Edge-to-Edge が強制される。
• すべての画面サイズで動作させる。 Phone / Foldable 折りたたみ・展開 / Tablet / ChromeOS。
• TalkBack で操作可能に。 すべてのインタラクティブ要素にコンテンツ説明を付与。

2. 推奨技術スタック

3. テーマ（Material 3）

基本テーマ

@Composable
fun AppTheme(
    darkTheme: Boolean = isSystemInDarkTheme(),
    dynamicColor: Boolean = true,
    content: @Composable () -> Unit,
) {
    val colorScheme = when {
        dynamicColor && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S -> {
            val context = LocalContext.current
            if (darkTheme) dynamicDarkColorScheme(context) else dynamicLightColorScheme(context)
        }
        darkTheme -> darkColorScheme(/* brand colors */)
        else -> lightColorScheme(/* brand colors */)
    }

    MaterialTheme(
        colorScheme = colorScheme,
        typography = AppTypography,
        shapes = AppShapes,
        content = content,
    )
}

カラーロール（M3）

• ハードコード色（Color(0xFF...)）を避け、MaterialTheme.colorScheme.primary を使う。

4. タイポグラフィ（Type Scale）

Material 3 タイプスケール:

Text(
    text = "タイトル",
    style = MaterialTheme.typography.headlineMedium,
)

• フォントは可変フォント（Roboto Flex / Google Sans）を優先。日本語は Noto Sans CJK JP。
• ユーザーのフォントスケール設定（Settings → 表示 → フォントサイズ）に追従。sp 単位を使い、dp は使わない（テキスト用）。

5. レイアウト・スペーシング

• 8dp グリッド を基本。4, 8, 12, 16, 24, 32, 40, 48 dp を使う。
• スクリーン端マージン: 16dp（Compact）/ 24dp（Medium 以上）。
• トークン化:

object Spacing {
    val xs = 4.dp
    val sm = 8.dp
    val md = 16.dp
    val lg = 24.dp
    val xl = 32.dp
}

• タッチターゲット最小 48×48dp（Material 推奨・WCAG 2.5.5 準拠）。

6. コンポーネント（M3）

主要コンポーネント

ボタン階層

• FAB: 画面内の 1 つの主要アクションのみ。
• Filled Button: 重要だが FAB 化しないアクション。
• Tonal Button: 中程度の強調。
• Outlined Button: 代替・セカンダリ。
• Text Button: 破壊的でない補助アクション。

Button(onClick = { /* ... */ }) { Text("保存") }
OutlinedButton(onClick = { /* ... */ }) { Text("キャンセル") }

7. ナビゲーション

アダプティブナビゲーション

WindowSizeClass に応じてナビゲーションを切り替える:

val windowSizeClass = currentWindowAdaptiveInfo().windowSizeClass

NavigationSuiteScaffold(
    navigationSuiteItems = {
        items.forEach { item ->
            item(
                icon = { Icon(item.icon, null) },
                label = { Text(item.label) },
                selected = item.selected,
                onClick = item.onClick,
            )
        }
    },
) {
    // content
}

• Navigation Compose の Type-safe Navigation（kotlinx-serialization ベース）を使用。

@Serializable data object Home
@Serializable data class Detail(val id: Long)

NavHost(navController, startDestination = Home) {
    composable<Home> { HomeScreen(onOpenDetail = { navController.navigate(Detail(it)) }) }
    composable<Detail> { backStack ->
        val detail: Detail = backStack.toRoute()
        DetailScreen(id = detail.id)
    }
}

Predictive Back

Android 14+ の Predictive Back に対応:

// AndroidManifest
// android:enableOnBackInvokedCallback="true"

PredictiveBackHandler(enabled = hasUnsavedChanges) { progress ->
    try {
        progress.collect { /* アニメーション進捗 */ }
        // ジェスチャー完了 → 戻る処理
    } catch (e: CancellationException) {
        // キャンセル
    }
}

8. Edge-to-Edge / インセット

Android 15（API 35）+ は Edge-to-Edge が デフォルト強制。

// Activity
override fun onCreate(savedInstanceState: Bundle?) {
    enableEdgeToEdge()
    super.onCreate(savedInstanceState)
    setContent { AppTheme { App() } }
}

• WindowInsets を適切に消費:

Scaffold(
    topBar = { TopAppBar(...) }, // インセット自動適用
    contentWindowInsets = WindowInsets.safeDrawing,
) { padding ->
    Column(Modifier.padding(padding)) { ... }
}

// カスタム要素
Box(Modifier.windowInsetsPadding(WindowInsets.systemBars)) { ... }

• ステータスバー・ナビゲーションバー背後にコンテンツを配置し、適切なインセットでコントロールを避ける。

9. Large Screen / Foldable 対応

• WindowSizeClass を使い、アプリ全体で List-Detail / Supporting Pane / Feed パターンを適用。

val navigator = rememberListDetailPaneScaffoldNavigator<Item>()

ListDetailPaneScaffold(
    directive = navigator.scaffoldDirective,
    value = navigator.scaffoldValue,
    listPane = { AnimatedPane { ItemList(onSelect = { navigator.navigateTo(ListDetailPaneScaffoldRole.Detail, it) }) } },
    detailPane = {
        AnimatedPane {
            navigator.currentDestination?.content?.let { DetailScreen(it) }
        }
    },
)

• 折りたたみ・展開に対応するため、WindowInfoTracker でヒンジ・折り目情報を取得可能。
• 横向き・分割画面・マルチウィンドウで崩れないことをテスト。
• ChromeOS / DeX 対応: マウス・キーボード・リサイズ可能ウィンドウを考慮。

10. アニメーション・モーション

• 基本トランジション:
  • AnimatedVisibility — 要素の出入り
  • AnimatedContent — 内容切替
  • Crossfade — シンプルな切替
  • animate*AsState — 値の補間
• Shared Element Transition（Compose 1.7+）でヒーロートランジション。

SharedTransitionLayout {
    AnimatedContent(targetState = state) { target ->
        if (target) {
            Image(
                modifier = Modifier.sharedElement(
                    rememberSharedContentState("image"),
                    animatedVisibilityScope = this@AnimatedContent,
                )
            )
        }
    }
}

• イージングは Material Motion の FastOutSlowInEasing / EmphasizedEasing を使用。
• 持続時間: 100〜400ms。
• Remove Animations 設定（Accessibility）に対応:

val reduceMotion = LocalAccessibilityManager.current?.let { /* check */ } ?: false

11. アクセシビリティ（TalkBack）

• contentDescription を画像・アイコンボタンに設定。装飾画像は null。

Icon(
    imageVector = Icons.Default.Delete,
    contentDescription = "削除",
)

IconButton(onClick = { /* ... */ }) {
    Icon(Icons.Default.Share, contentDescription = "共有")
}

• セマンティクスの明示:

Modifier.semantics {
    contentDescription = "お気に入りに追加"
    role = Role.Button
    stateDescription = if (isFavorite) "追加済み" else "未追加"
}

• コントラスト比 WCAG AA（4.5:1 / 3:1）。
• タッチターゲット 48×48dp（Modifier.minimumInteractiveComponentSize() で保証）。
• フォントスケール 200% で崩れないこと。
• カラーだけで情報を伝えない。
• 詳細は skills/ui-accessibility/SKILL.md 参照。

12. リスト・パフォーマンス

• LazyColumn / LazyRow / LazyVerticalGrid を使用。Column + verticalScroll でリスト描画しない。
• key パラメーターで安定した ID を指定し、不要な再コンポジションを回避。

LazyColumn {
    items(items, key = { it.id }) { item ->
        ItemRow(item)
    }
}

• 画像は Coil で遅延ロード + crossfade。
• 再コンポジション最適化: remember / derivedStateOf を適切に使う。
• @Stable / @Immutable アノテーションで Compose にヒントを与える。

13. 入力・ジェスチャー

• IME（キーボード）対応: Modifier.imePadding() でキーボード回避。WindowInsets.ime を使用。
• テキスト入力: KeyboardOptions（keyboardType / imeAction / autoCorrect）を適切に設定。
• ジェスチャー: Modifier.pointerInput や detectTapGestures / detectDragGestures。
• タッチとマウス（ChromeOS）両方を考慮。Modifier.hoverable でホバー対応。

14. アイコン

• Material Symbols（material-icons-extended）を使用。
• カスタムアイコンは Vector Drawable（SVG 変換）で提供。
• サイズは 20 / 24 / 32 / 40dp を基本。
• アプリアイコンは Adaptive Icon（foreground / background レイヤー）+ Monochrome（Themed Icon 用）を提供。

<!-- res/mipmap-anydpi-v26/ic_launcher.xml -->
<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
    <background android:drawable="@drawable/ic_launcher_background" />
    <foreground android:drawable="@drawable/ic_launcher_foreground" />
    <monochrome android:drawable="@drawable/ic_launcher_monochrome" />
</adaptive-icon>

15. 通知・システム連携

• 通知は Notification Channel に分類（Android 8+ 必須）。
• POST_NOTIFICATIONS 権限（Android 13+）を適切に要求。
• リッチ通知（画像・アクション・返信）・通知トレイでの展開挙動を確認。
• App Shortcuts / Widgets（Glance API）で常用機能を露出。

16. テスト

• Compose UI Test で画面ロジック検証（composeTestRule）。
• Accessibility Scanner で自動アクセシビリティ検査。
• Espresso + UIAutomator で E2E。
• Baseline Profile / Macrobenchmark で起動・スクロールパフォーマンス測定。

17. デザインプレビュー

@Preview でさまざまな設定を網羅:

@Preview(name = "Light", showBackground = true)
@Preview(name = "Dark", uiMode = UI_MODE_NIGHT_YES, showBackground = true)
@Preview(name = "Large Font", fontScale = 2.0f)
@Preview(name = "Tablet", device = "spec:width=1280dp,height=800dp,dpi=240")
@Composable
fun ScreenPreview() {
    AppTheme { HomeScreen() }
}

関連スキル

• アクセシビリティ全般: skills/ui-accessibility/SKILL.md
• UI レビュー: skills/ui-review-checklist/SKILL.md