Android Design Guidelines

# Android Design Skill

Material Design 3 guidelines and Android platform conventions for Jetpack Compose and XML layouts.

## Structure

- `SKILL.md` — Full guideline rules with code examples
- `rules/_sections.md` — Indexed section breakdown for quick lookup
- `metadata.json` — Version and reference metadata

## Usage

Apply these guidelines when:
- Building or reviewing Android UI code
- Implementing Material You / dynamic color
- Designing navigation, layout, or component architecture
- Auditing accessibility or platform compliance

## Priority

Rules marked **CRITICAL** must never be violated. Rules marked **HIGH** should be followed unless there is a documented reason. Rules marked **MEDIUM** are recommended best practices.

## Never Do

- Never hardcode color hex values — always use `MaterialTheme.colorScheme` color roles
- Never use `dp` for text sizes — use `sp` so user font scaling applies
- Never override `onBackPressed()` — use `BackHandler` (Compose) or `OnBackInvokedCallback` (View-based) for predictive back
- Never place touch targets below 48x48dp — accessibility violation
- Never request permissions at app launch — request in context with a rationale
- Never use pure black (#000000) for dark theme backgrounds — use Material surface roles
- Never put icon-only items in the navigation bar — labels are required
- Never use a dialog for non-critical information — prefer Snackbar or Bottom Sheet
- Never use more than one FAB on a screen — one FAB for the single primary action
- Never show full-width content on tablet layouts — use list-detail or max-width containers


---
name: android-design-guidelines
description: Material Design 3 and Android platform guidelines. Use when building Android apps with Jetpack Compose or XML layouts, implementing Material You, navigation, or accessibility. Triggers on tasks involving Android UI, Compose components, dynamic color, or Material Design compliance.
license: MIT
metadata:
  author: platform-design-skills
  version: "1.0.0"
---

# Android Platform Design Guidelines — Material Design 3

## 1. Material You & Theming [CRITICAL]

### 1.1 Dynamic Color

Enable dynamic color derived from the user's wallpaper. Dynamic color is the default on Android 12+ and should be the primary theming strategy.

```kotlin
// Compose: Dynamic color theme
@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()
        else -> lightColorScheme()
    }
    MaterialTheme(
        colorScheme = colorScheme,
        typography = AppTypography,
        content = content
    )
}
```

```xml
<!-- XML: Dynamic color in themes.xml -->
<style name="Theme.App" parent="Theme.Material3.DayNight.NoActionBar">
    <item name="dynamicColorThemeOverlay">@style/ThemeOverlay.Material3.DynamicColors.DayNight</item>
</style>
```

**Rules:**
- R1.1: Always provide a fallback static color scheme for devices below Android 12.
- R1.2: Never hardcode color hex values in components. Always reference color roles from the theme.
- R1.3: Test with at least 3 different wallpapers to verify dynamic color harmony.

### 1.2 Color Roles

Material 3 defines a structured set of color roles. Use them semantically, not aesthetically.

| Role | Usage | On-Role |
|------|-------|---------|
| `primary` | Key actions, active states, FAB | `onPrimary` |
| `primaryContainer` | Less prominent primary elements | `onPrimaryContainer` |
| `secondary` | Supporting UI, filter chips | `onSecondary` |
| `secondaryContainer` | Navigation bar active indicator | `onSecondaryContainer` |
| `tertiary` | Accent, contrast, complementary | `onTertiary` |
| `terti