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.

// 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
NavigationRail(
    header = {
        FloatingActionButton(
            onClick = { /* primary action */ },
            containerColor = MaterialTheme.colorScheme.tertiaryContainer
        ) {
            Icon(Icons.Default.Add, contentDescription = "Create")
        }
    }
) {
    items.forEachIndexed { index, item ->
        NavigationRailItem(
            icon = { Icon(item.icon, contentDescription = item.label) },
            label = { Text(item.label) },
            selected = selectedItem == index,
            onClick = { selectedItem = index }
        )
    }
}

Rules:

• R2.5: Use Navigation Rail on medium (600-839dp) and expanded (840dp+) window sizes. Pair it with Navigation Bar on compact.
• R2.6: Optionally include a FAB in the rail header for the primary action.
• R2.7: Labels are optional on the rail but recommended for clarity.

2.3 Navigation Drawer

For 5+ destinations or complex navigation hierarchies, typically on expanded screens.

// Compose: Permanent Navigation Drawer for large screens
PermanentNavigationDrawer(
    drawerContent = {
        PermanentDrawerSheet {
            Text("App Name", modifier = Modifier.padding(16.dp),
                 style = MaterialTheme.typography.titleMedium)
            HorizontalDivider()
            items.forEach { item ->
                NavigationDrawerItem(
                    label = { Text(item.label) },
                    selected = item == selectedItem,
                    onClick = { selectedItem = item },
                    icon = { Icon(item.icon, contentDescription = null) }
                )
            }
        }
    }
) {
    Scaffold { /* page content */ }
}

Rules:

• R2.8: Use modal drawer on compact screens, permanent drawer on expanded screens.
• R2.9: Group drawer items into sections with dividers and section headers.

2.4 Predictive Back Gesture

Android 13+ supports predictive back with an animation preview.

// Compose: Predictive back handling
val predictiveBackHandler = remember { PredictiveBackHandler(enabled = true) { progress ->
    // Animate based on progress (0.0 to 1.0)
}}

<!-- AndroidManifest.xml: opt in to predictive back -->
<application android:enableOnBackInvokedCallback="true">

Rules:

• R2.10: Opt in to predictive back in the manifest. Handle OnBackInvokedCallback instead of overriding onBackPressed().
• R2.11: The system back gesture navigates back in the navigation stack. The Up button (toolbar arrow) navigates up in the app hierarchy. These may differ.
• R2.12: Never intercept system back to show “are you sure?” dialogs unless there is unsaved user input.

2.5 Navigation Component Selection

3. Layout & Responsive [HIGH]

3.1 Window Size Classes

Use window size classes for adaptive layouts, not raw pixel breakpoints.

// Compose: Window size classes
val windowSizeClass = calculateWindowSizeClass(this)
when (windowSizeClass.widthSizeClass) {
    WindowWidthSizeClass.Compact -> CompactLayout()
    WindowWidthSizeClass.Medium -> MediumLayout()
    WindowWidthSizeClass.Expanded -> ExpandedLayout()
}

Rules:

• R3.1: Always use WindowSizeClass from material3-window-size-class for responsive layout decisions.
• R3.2: Never use fixed pixel breakpoints. Device categories are fluid.
• R3.3: Support all three width size classes. At minimum, compact and expanded.

3.2 Material Grid

Apply canonical Material grid margins and gutters.

Rules:

• R3.4: Content should not span the full width on expanded screens. Use a max content width of ~840dp or list-detail layout.
• R3.5: Apply consistent horizontal margins matching the grid spec.

3.3 Edge-to-Edge Display

Android 15+ enforces edge-to-edge. All apps should draw behind system bars.

// Compose: Edge-to-edge setup
class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        enableEdgeToEdge()
        super.onCreate(savedInstanceState)
        setContent {
            Scaffold(
                modifier = Modifier.fillMaxSize(),
                // Scaffold handles insets for top/bottom bars automatically
            ) { innerPadding ->
                Content(modifier = Modifier.padding(innerPadding))
            }
        }
    }
}

Rules:

• R3.6: Call enableEdgeToEdge() before setContent. Draw behind both status bar and navigation bar.
• R3.7: Use WindowInsets to pad content away from system bars. Scaffold handles this for top bar and bottom bar content automatically.
• R3.8: Scrollable content should scroll behind transparent system bars with appropriate inset padding at the top and bottom of the list.

3.4 Foldable Device Support

// Compose: Detect fold posture
val foldingFeatures = WindowInfoTracker.getOrCreate(context)
    .windowLayoutInfo(context)
    .collectAsState(initial = WindowLayoutInfo(emptyList()))

Rules:

• R3.9: Detect hinge/fold position and avoid placing critical content across the fold.
• R3.10: Use ListDetailPaneScaffold or SupportingPaneScaffold from Material3 adaptive library for foldable-aware layouts.

4. Typography [HIGH]

4.1 Material Type Scale

// Compose: Custom typography
val AppTypography = Typography(
    displayLarge = TextStyle(
        fontFamily = FontFamily(Font(R.font.brand_regular)),
        fontWeight = FontWeight.Normal,
        fontSize = 57.sp,
        lineHeight = 64.sp,
        letterSpacing = (-0.25).sp
    ),
    bodyLarge = TextStyle(
        fontFamily = FontFamily(Font(R.font.brand_regular)),
        fontWeight = FontWeight.Normal,
        fontSize = 16.sp,
        lineHeight = 24.sp,
        letterSpacing = 0.5.sp
    )
    // ... define all 15 roles
)

Rules:

• R4.1: Always use sp units for text sizes to support user font scaling preferences.
• R4.2: Never set text below 12sp for body content. Labels may go to 11sp minimum.
• R4.3: Reference typography roles from MaterialTheme.typography, not hardcoded sizes.
• R4.4: Support dynamic type scaling. Test at 200% font scale. Ensure no text is clipped or overlapping.
• R4.5: Line height should be approximately 1.2-1.5x the font size for readability.

5. Components [HIGH]

5.1 Floating Action Button (FAB)

The FAB represents the single most important action on a screen.

// Compose: FAB variants
// Standard FAB
FloatingActionButton(onClick = { /* action */ }) {
    Icon(Icons.Default.Add, contentDescription = "Create new item")
}

// Extended FAB (with label - preferred for clarity)
ExtendedFloatingActionButton(
    onClick = { /* action */ },
    icon = { Icon(Icons.Default.Edit, contentDescription = null) },
    text = { Text("Compose") }
)

// Large FAB
LargeFloatingActionButton(onClick = { /* action */ }) {
    Icon(Icons.Default.Add, contentDescription = "Create", modifier = Modifier.size(36.dp))
}

Rules:

• R5.1: Use at most one FAB per screen. It represents the primary action.
• R5.2: Place the FAB at the bottom-end of the screen. On screens with a Navigation Bar, the FAB floats above it.
• R5.3: The FAB should use primaryContainer color by default. Use tertiaryContainer for secondary screens.
• R5.4: Prefer ExtendedFloatingActionButton with a label for clarity. Collapse to icon-only on scroll if needed.

5.2 Top App Bar

// Compose: Top app bar variants
// Small (default)
TopAppBar(
    title = { Text("Page Title") },
    navigationIcon = {
        IconButton(onClick = { /* navigate up */ }) {
            Icon(Icons.AutoMirrored.Filled.ArrowBack, contentDescription = "Back")
        }
    },
    actions = {
        IconButton(onClick = { /* search */ }) {
            Icon(Icons.Default.Search, contentDescription = "Search")
        }
    }
)

// Medium — expands title area
MediumTopAppBar(
    title = { Text("Section Title") },
    scrollBehavior = TopAppBarDefaults.enterAlwaysScrollBehavior()
)

// Large — for prominent titles
LargeTopAppBar(
    title = { Text("Screen Title") },
    scrollBehavior = TopAppBarDefaults.exitUntilCollapsedScrollBehavior()
)

Rules:

• R5.5: Use TopAppBar (small) for most screens. Use MediumTopAppBar or LargeTopAppBar for prominent section or screen titles.
• R5.6: Connect scroll behavior to the app bar so it collapses/expands with content scrolling.
• R5.7: Limit action icons to 2-3. Overflow additional actions into a more menu.

5.3 Bottom Sheets

// Compose: Modal bottom sheet
ModalBottomSheet(
    onDismissRequest = { showSheet = false },
    sheetState = rememberModalBottomSheetState()
) {
    Column(modifier = Modifier.padding(16.dp)) {
        Text("Sheet Title", style = MaterialTheme.typography.titleLarge)
        Spacer(modifier = Modifier.height(16.dp))
        // Sheet content
    }
}

Rules:

• R5.8: Use modal bottom sheets for non-critical supplementary content. Use standard bottom sheets for persistent content.
• R5.9: Bottom sheets must have a visible drag handle for discoverability.
• R5.10: Sheet content must be scrollable if it can exceed the visible area.

5.4 Dialogs

// Compose: Alert dialog
AlertDialog(
    onDismissRequest = { showDialog = false },
    title = { Text("Discard draft?") },
    text = { Text("Your unsaved changes will be lost.") },
    confirmButton = {
        TextButton(onClick = { /* confirm */ }) { Text("Discard") }
    },
    dismissButton = {
        TextButton(onClick = { showDialog = false }) { Text("Cancel") }
    }
)

Rules:

• R5.11: Dialogs interrupt the user. Use them only for critical decisions requiring immediate attention.
• R5.12: Confirm button uses a text button, not a filled button. The dismiss button is always on the left.
• R5.13: Dialog titles should be concise questions or statements. Body text provides context.

5.5 Snackbar

// Compose: Snackbar with action
val snackbarHostState = remember { SnackbarHostState() }
Scaffold(snackbarHost = { SnackbarHost(snackbarHostState) }) {
    // trigger snackbar
    LaunchedEffect(key) {
        val result = snackbarHostState.showSnackbar(
            message = "Item archived",
            actionLabel = "Undo",
            duration = SnackbarDuration.Short
        )
        if (result == SnackbarResult.ActionPerformed) { /* undo */ }
    }
}

Rules:

• R5.14: Use snackbars for brief, non-critical feedback. They auto-dismiss and should not contain critical information.
• R5.15: Snackbars appear at the bottom of the screen, above the Navigation Bar and below the FAB.
• R5.16: Include an action (e.g., “Undo”) when the operation is reversible. Limit to one action.

5.6 Chips

// Filter Chip
FilterChip(
    selected = isSelected,
    onClick = { isSelected = !isSelected },
    label = { Text("Filter") },
    leadingIcon = if (isSelected) {
        { Icon(Icons.Default.Check, contentDescription = null, modifier = Modifier.size(18.dp)) }
    } else null
)

// Assist Chip
AssistChip(
    onClick = { /* action */ },
    label = { Text("Add to calendar") },
    leadingIcon = { Icon(Icons.Default.CalendarToday, contentDescription = null) }
)

Rules:

• R5.17: Use FilterChip for toggling filters, AssistChip for smart suggestions, InputChip for user-entered content (tags), SuggestionChip for dynamically generated suggestions.
• R5.18: Chips should be arranged in a horizontally scrollable row or a flow layout, not stacked vertically.

5.7 Component Selection Guide

6. Accessibility [CRITICAL]

6.1 TalkBack and Content Descriptions

// Compose: Accessible components
Icon(
    Icons.Default.Favorite,
    contentDescription = "Add to favorites" // Descriptive, not "heart icon"
)

// Decorative elements
Icon(
    Icons.Default.Star,
    contentDescription = null // null for purely decorative
)

// Merge semantics for compound elements
Row(modifier = Modifier.semantics(mergeDescendants = true) {}) {
    Icon(Icons.Default.Event, contentDescription = null)
    Text("March 15, 2026")
}

// Custom actions
Box(modifier = Modifier.semantics {
    customActions = listOf(
        CustomAccessibilityAction("Archive") { /* archive */ true },
        CustomAccessibilityAction("Delete") { /* delete */ true }
    )
})

Rules:

• R6.1: Every interactive element must have a contentDescription (or null if purely decorative).
• R6.2: Content descriptions must describe the action or meaning, not the visual appearance. Say “Add to favorites” not “Heart icon.”
• R6.3: Use mergeDescendants = true to group related elements into a single TalkBack focus unit (e.g., a list item with icon + text + subtitle).
• R6.4: Provide customActions for swipe-to-dismiss or long-press actions so TalkBack users can access them.

6.2 Touch Targets

// Compose: Ensure minimum touch target
IconButton(onClick = { /* action */ }) {
    // IconButton already provides 48dp minimum touch target
    Icon(Icons.Default.Close, contentDescription = "Close")
}

// Manual minimum touch target
Box(
    modifier = Modifier
        .sizeIn(minWidth = 48.dp, minHeight = 48.dp)
        .clickable { /* action */ },
    contentAlignment = Alignment.Center
) {
    Icon(Icons.Default.Info, contentDescription = "Info", modifier = Modifier.size(24.dp))
}

Rules:

• R6.5: All interactive elements must have a minimum touch target of 48x48dp. Material 3 components handle this by default.
• R6.6: Do not reduce touch targets to save space. Use padding to increase the touchable area if the visual element is smaller.

6.3 Color Contrast and Visual

Rules:

• R6.7: Text contrast ratio must be at least 4.5:1 for normal text and 3:1 for large text (18sp+ or 14sp+ bold) against its background.
• R6.8: Never use color as the only means of conveying information. Pair with icons, text, or patterns.
• R6.9: Support “bold text” and “high contrast” accessibility settings.

6.4 Focus and Traversal

// Compose: Custom focus order
Column {
    var focusRequester = remember { FocusRequester() }
    TextField(
        modifier = Modifier.focusRequester(focusRequester),
        value = text,
        onValueChange = { text = it }
    )
    LaunchedEffect(Unit) {
        focusRequester.requestFocus() // Auto-focus on screen load
    }
}

Rules:

• R6.10: Focus order must follow a logical reading sequence (top-to-bottom, start-to-end). Avoid custom focusOrder unless the default is incorrect.
• R6.11: After navigation or dialog dismissal, move focus to the most logical target element.
• R6.12: All screens must be fully operable using TalkBack, Switch Access, and external keyboard.

7. Gestures & Input [MEDIUM]

7.1 System Gestures

Rules:

• R7.1: Never place interactive elements within the system gesture inset zones (bottom 20dp, left/right 24dp edges) as they conflict with system navigation gestures.
• R7.2: Use WindowInsets.systemGestures to detect and avoid gesture conflict zones.

7.2 Common Gesture Patterns

// Compose: Pull to refresh
PullToRefreshBox(
    isRefreshing = isRefreshing,
    onRefresh = { viewModel.refresh() }
) {
    LazyColumn { /* content */ }
}

// Compose: Swipe to dismiss
SwipeToDismissBox(
    state = rememberSwipeToDismissBoxState(),
    backgroundContent = {
        Box(
            modifier = Modifier.fillMaxSize().background(MaterialTheme.colorScheme.error),
            contentAlignment = Alignment.CenterEnd
        ) {
            Icon(Icons.Default.Delete, contentDescription = "Delete",
                 tint = MaterialTheme.colorScheme.onError)
        }
    }
) {
    ListItem(headlineContent = { Text("Swipeable item") })
}

Rules:

• R7.3: All swipe-to-dismiss actions must be undoable (show snackbar with undo) or require confirmation.
• R7.4: Provide alternative non-gesture ways to trigger all gesture-based actions (for accessibility).
• R7.5: Apply Material ripple effect on all tappable elements. Compose clickable modifier includes ripple by default.

7.3 Long Press

Rules:

• R7.6: Use long press for contextual menus and multi-select mode. Never use it as the only way to access a feature.
• R7.7: Provide haptic feedback on long press via HapticFeedbackType.LongPress.

8. Notifications [MEDIUM]

8.1 Notification Channels

// Create notification channel (required for Android 8+)
val channel = NotificationChannel(
    "messages",
    "Messages",
    NotificationManager.IMPORTANCE_HIGH
).apply {
    description = "New message notifications"
    enableLights(true)
    lightColor = Color.BLUE
}
notificationManager.createNotificationChannel(channel)

Rules:

• R8.1: Create separate notification channels for each distinct notification type. Users can configure each independently.
• R8.2: Choose importance levels conservatively. Overusing IMPORTANCE_HIGH leads users to disable notifications entirely.
• R8.3: All notifications must have a tap action (PendingIntent) that navigates to relevant content.
• R8.4: Include a contentDescription in notification icons for accessibility.

8.2 Notification Design

Rules:

• R8.5: Use MessagingStyle for conversations. Include sender name and avatar.
• R8.6: Add direct reply actions to messaging notifications.
• R8.7: Provide a “Mark as read” action on message notifications.
• R8.8: Use expandable notifications (BigTextStyle, BigPictureStyle, InboxStyle) for rich content.
• R8.9: Foreground service notifications must accurately describe the ongoing operation and provide a stop action where appropriate.

9. Permissions & Privacy [HIGH]

9.1 Runtime Permissions

// Compose: Permission request
val permissionState = rememberPermissionState(Manifest.permission.CAMERA)

if (permissionState.status.isGranted) {
    CameraPreview()
} else {
    Column {
        Text("Camera access is needed to scan QR codes.")
        Button(onClick = { permissionState.launchPermissionRequest() }) {
            Text("Grant Camera Access")
        }
    }
}

Rules:

• R9.1: Request permissions in context, at the moment they are needed, not at app launch.
• R9.2: Always explain why the permission is needed before requesting it (rationale screen).
• R9.3: Gracefully handle permission denial. Provide degraded functionality rather than blocking the user.
• R9.4: Never request permissions you do not actively use. Google Play will reject apps with unnecessary permissions.

9.2 Privacy-Preserving APIs

// Photo picker: no permission needed
val pickMedia = rememberLauncherForActivityResult(
    ActivityResultContracts.PickVisualMedia()
) { uri ->
    uri?.let { /* handle selected media */ }
}
pickMedia.launch(PickVisualMediaRequest(ActivityResultContracts.PickVisualMedia.ImageOnly))

Rules:

• R9.5: Use the Photo Picker (Android 13+) instead of requesting READ_MEDIA_IMAGES. No permission needed.
• R9.6: Use ACCESS_COARSE_LOCATION (approximate) unless precise location is essential for functionality.
• R9.7: Prefer one-time permissions for camera and microphone in non-recording contexts.
• R9.8: Display a privacy indicator when camera or microphone is actively in use.

10. System Integration [MEDIUM]

10.1 Widgets

// Compose Glance API widget
class TaskWidget : GlanceAppWidget() {
    override suspend fun provideGlance(context: Context, id: GlanceId) {
        provideContent {
            GlanceTheme {
                Column(
                    modifier = GlanceModifier
                        .fillMaxSize()
                        .background(GlanceTheme.colors.widgetBackground)
                        .padding(16.dp)
                ) {
                    Text(
                        text = "Tasks",
                        style = TextStyle(fontWeight = FontWeight.Bold,
                                         color = GlanceTheme.colors.onSurface)
                    )
                    // Widget content
                }
            }
        }
    }
}

Rules:

• R10.1: Use Glance API for new widgets. Support dynamic color via GlanceTheme.
• R10.2: Widgets must have a default configuration and work immediately after placement.
• R10.3: Provide multiple widget sizes (small, medium, large) where practical.
• R10.4: Use rounded corners matching the system widget shape (system_app_widget_background_radius).

10.2 App Shortcuts

<!-- shortcuts.xml -->
<shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
    <shortcut
        android:shortcutId="compose"
        android:enabled="true"
        android:shortcutShortLabel="@string/compose_short"
        android:shortcutLongLabel="@string/compose_long"
        android:icon="@drawable/ic_shortcut_compose">
        <intent
            android:action="android.intent.action.VIEW"
            android:targetPackage="com.example.app"
            android:targetClass="com.example.app.ComposeActivity" />
    </shortcut>
</shortcuts>

Rules:

• R10.5: Provide 2-4 static shortcuts for common actions. Support dynamic shortcuts for recent content.
• R10.6: Shortcut icons should be simple, recognizable silhouettes on a circular background.
• R10.7: Test shortcuts with long-press on the app icon and in the Settings > Apps shortcut list.

10.3 Deep Links and Share

Rules:

• R10.8: Support Android App Links (verified deep links) for all public content URLs.
• R10.9: Implement the share sheet with ShareCompat or Intent.createChooser. Provide rich previews with title, description, and thumbnail.
• R10.10: Handle incoming share intents with appropriate content type filtering.

Design Evaluation Checklist

Use this checklist to evaluate Android UI implementations:

Theme & Color

• Dynamic color enabled with static fallback
• All colors reference Material theme roles (no hardcoded hex)
• Light and dark themes both supported
• On-colors match their background color roles
• Custom colors generated from seed via Material Theme Builder

Navigation

• Correct navigation component for screen size and destination count
• Navigation bar labels always visible
• Predictive back gesture opted in and handled
• Up vs Back behavior correct

Layout

• All three window size classes supported
• Edge-to-edge with proper inset handling
• Content does not span full width on large screens
• Foldable hinge area respected

Typography

• All text uses sp units
• All text references MaterialTheme.typography roles
• Tested at 200% font scale with no clipping
• Minimum 12sp body, 11sp labels

Components

• At most one FAB per screen
• Top app bar connected to scroll behavior
• Snackbars used for non-critical feedback only
• Dialogs reserved for critical interruptions

Accessibility

• All interactive elements have contentDescription
• All touch targets >= 48dp
• Color contrast >= 4.5:1 for text
• No information conveyed by color alone
• Full TalkBack traversal tested
• Switch Access and keyboard navigation work

Gestures

• No interactive elements in system gesture zones
• All gesture actions have non-gesture alternatives
• Swipe-to-dismiss is undoable

Notifications

• Separate channels for each notification type
• Appropriate importance levels
• Tap action navigates to relevant content

Permissions

• Permissions requested in context, not at launch
• Rationale shown before permission request
• Graceful degradation on denial
• Photo Picker used instead of media permission

System Integration

• Widgets use Glance API with dynamic color
• App shortcuts provided for common actions
• Deep links handled for public content

Anti-Patterns