/android

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.

// 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: 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` | | `tertiaryContainer` | Input fields, less prominent accents | `onTertiaryContainer` | | `surface` | Backgrounds, cards, sheets | `onSurface` | | `surfaceVariant` | Decorative elements, dividers | `onSurfaceVariant` | | `error` | Error states, destructive actions | `onError` | | `errorContainer` | Error backgrounds | `onErrorContainer` | | `outline` | Borders, dividers | — | | `outlineVariant` | Subtle borders | — | | `inverseSurface` | Snackbar background | `inverseOnSurface` |

// Correct: semantic color roles
Text(
    text = "Error message",
    color = MaterialTheme.colorScheme.error
)
Surface(color = MaterialTheme.colorScheme.errorContainer) {
    Text(text = "Error detail", color = MaterialTheme.colorScheme.onErrorContainer)
}

// WRONG: hardcoded colors
Text(text = "Error", color = Color(0xFFB00020)) // Anti-pattern

**Rules:**

• R1.4: Every foreground element must use the matching `on` color role for its background (e.g., `onPrimary` text on `primary` background).
• R1.5: Use `surface` and its variants for backgrounds. Never use `primary` or `secondary` as large background areas.
• R1.6: Use `tertiary` sparingly for accent and complementary contrast only.

1.3 Light and Dark Themes

Support both light and dark themes. Respect the system setting by default.

// Compose: Detect system theme
val darkTheme = isSystemInDarkTheme()

**Rules:**

• R1.7: Always support both light and dark themes. Never ship light-only.
• R1.8: Dark theme surfaces use elevation-based tonal mapping, not pure black (#000000). Use `surface` color roles which handle this automatically.
• R1.9: Provide a manual theme override in app settings (System / Light / Dark).

1.4 Custom Color Seeds

When branding requires custom colors, provide a seed color and generate tonal palettes using Material Theme Builder.

// Custom color scheme with brand seed
private val BrandLightColorScheme = lightColorScheme(
    primary = Color(0xFF1B6D2F),
    onPrimary = Color(0xFFFFFFFF),
    primaryContainer = Color(0xFFA4F6A8),
    onPrimaryContainer = Color(0xFF002107),
    // ... generate full palette from seed
)

**Rules:**

• R1.10: Generate tonal palettes from seed colors using Material Theme Builder. Never manually pick individual tones.
• R1.11: When using custom colors, still support dynamic color as the default and use custom colors as fallback.

---

2. Navigation [CRITICAL]

2.1 Navigation Bar (Bottom)

The primary navigation pattern for phones with 3-5 top-level destinations.

// Compose: Navigation Bar
NavigationBar {
    items.forEachIndexed { index, item ->
        NavigationBarItem(
            icon = {
                Icon(
                    imageVector = if (selectedItem == index) item.filledIcon else item.outlinedIcon,
                    contentDescription = item.label
                )
            },
            label = { Text(item.label) },
            selected = selectedItem == index,
            onClick = { selectedItem = index }
        )
    }
}

**Rules:**

• R2.1: Use Navigation Bar for 3-5 top-level destinations on compact screens. Never use for fewer than 3 or more than 5.
• R2.2: Always show labels on navigation bar items. Icon-only navigation bars are not permitted.
• R2.3: Use filled icons for the selected state and outlined icons for unselected states.
• R2.4: The active indicator uses `secondaryContainer` color. Do not override this.

2.2 Navigation Rail

For medium and expanded screens (tablets, foldables, desktop).

// Compose: Navigation Rail for larger screens
NavigationRa