---
name: software-android-design
description: "Designs and audits native Android interfaces. Use when reviewing Compose layout, typography, color, motion, or adaptive patterns on a verified emulator build."
compatibility: Portable core. Works on Claude Code and Codex.
version: "1.1"
last_validated: 2026-07-11
---

# Native Android Design

Use this skill for visual design decisions and design-focused audits in native Android apps. Prefer it when the user needs Material 3 aligned screen structure, current Android-native visual defaults, or a screenshot-to-fix loop after a fresh verified build/install/launch. If the request is really about greenfield scaffolding, Gradle build loops, module selection, or broader Android implementation workflow, route to `software-mobile` and return here once the question becomes visual structure or design quality.

## Quick Reference

| Design concern | Default | Notes |
|---------------|---------|-------|
| Type | `MaterialTheme.typography` | Display → Headline → Title → Body → Label scale |
| Color | `MaterialTheme.colorScheme` | primary, secondary, tertiary, surface, error, and `on*` variants |
| Shape | `MaterialTheme.shapes` | ExtraSmall→ExtraLarge; `RoundedCornerShape` |
| Dynamic color | `dynamicDarkColorScheme` / `dynamicLightColorScheme` | Android 12+; static seed palette on older APIs |
| Bottom nav | `NavigationBar` 3–5 destinations | `NavigationRail` on medium, `NavigationDrawer` on expanded, or `NavigationSuiteScaffold` for auto |
| Top bar | `TopAppBar` / `MediumTopAppBar` / `LargeTopAppBar` / `CenterAlignedTopAppBar` | Choose by headline presence; collapsing variants for rich headers |
| Cards | `ElevatedCard` hero, `Card` primary, `OutlinedCard` secondary | tonalElevation 3 + shadow for hero |
| Custom data viz | `Canvas` | Radar charts, score rings, gradient bars, gauges — standard components insufficient |
| Adaptive layouts | `ListDetailPaneScaffold`, `SupportingPaneScaffold`, `NavigationSuiteScaffold` | Feed grids for homogeneous content |
| Detail views | `ModalBottomSheet` | Never expand deep detail inline in scroll content |
| Motion | Container transforms, `AnimatedVisibility`, `animateContentSize`, `spring()` | M3 Expressive defaults |
| Edge-to-edge | `enableEdgeToEdge()` + `windowInsetsPadding` | Mandatory, non-optional for targetSdk 36+ (`windowOptOutEdgeToEdgeEnforcement` removed) |
| Predictive back | `PredictiveBackHandler` (Compose) / `OnBackInvokedCallback` | Default system animation on Android 16+ when targeting API 36+; `onBackPressed()`/`KEYCODE_BACK` no longer dispatched at that target |
| Press feedback | `InteractionSource` + `animateFloatAsState(0.94f)`, 100ms spring | `Modifier.clickable` without `Indication` = no tactile response |
| Chip groups | `FlowRow` | Use when spatial context matters; avoid horizontal scroll for finite sets |
| Peer view switch | `SegmentedButton` or `TabRow` | Reduces navigation depth vs. separate screens |
| Immersive viz | `BottomSheetScaffold { background; viz; controls }` | Full-bleed; no card wrappers; no scroll |
| Aspect ratios | Maps `.aspectRatio(1.4f)`, charts `.aspectRatio(1f)` | Size by content type |
| Touch targets | ≥ 48dp on all interactive elements | Platform minimum |
| Token discipline | No magic numbers in screen files | Tokenize spacing, elevation, shape, color |

## Defaults

- Start from Material Design 3 Expressive, not custom chrome.
- Treat Compose Material 3 as the modern native baseline for navigation, surfaces, typography, color, shape, and motion.
- Enable dynamic color on Android 12+ and provide a well-tuned static seed palette as fallback.
- Prefer `MaterialTheme.typography`, `MaterialTheme.colorScheme`, `MaterialTheme.shapes`, and standard containers before custom styling.
- Keep navigation familiar: `NavigationBar` for peer sections, `NavHost` for drill-down, `ModalBottomSheet` for focused tasks.
- Use emulator screenshot-driven verification for design changes only after a fresh build/uninstall/install/launch has been proven.

## Platform Currency (as of 2026-07-11)

- **Android 17 (API 37)** shipped 2026-06-16; Android 16 (API 36) is the prior release. Do not treat Android 15/16 as "current" — verify at [developer.android.com/about/versions](https://developer.android.com/about/versions) before citing a specific version as latest.
- **Google Play target API policy**: new apps and app updates must target API level 36 (Android 16) or higher as of the 2026-08-31 deadline (one-time extension to 2026-11-01 available by request); apps not updated at all must still target at least API 35. This deadline moves roughly once a year — re-verify at [developer.android.com/google/play/requirements/target-sdk](https://developer.android.com/google/play/requirements/target-sdk) rather than hardcoding a number.
- **Material 3 Expressive** (announced May 2025) is the design direction, but its component APIs are still split: stable `androidx.compose.material3:material3:1.4.0` ships the baseline M3 type scale, shapes, and most components; expressive-specific APIs (new shape morph library, expressive motion scheme, some new components) live behind `@ExperimentalMaterial3ExpressiveApi` in the `1.5.0-alpha` line as of mid-2026. Confirm current stable-vs-experimental status at [developer.android.com/jetpack/androidx/releases/compose-material3](https://developer.android.com/jetpack/androidx/releases/compose-material3) before recommending an expressive-only API without an opt-in annotation.
- **Compose BOM**: `2026.06.00` was the latest stable BOM as of this validation. Compose BOM ships roughly monthly — verify the current value at [developer.android.com/develop/ui/compose/bom/bom-mapping](https://developer.android.com/develop/ui/compose/bom/bom-mapping) rather than pinning an exact version in generated code.
- **Predictive back** is mandatory system behavior for apps targeting API 36+ on Android 16+ devices — `onBackPressed()` and `KEYCODE_BACK` are no longer dispatched at that target. Use `PredictiveBackHandler` in Compose or `OnBackInvokedCallback` directly; do not recommend `onBackPressed()` overrides for new targetSdk-36 code.
- **Edge-to-edge** is fully mandatory, not just default-on: `windowOptOutEdgeToEdgeEnforcement` is deprecated and has no effect once targetSdk reaches 36. Any recommendation that relies on opting out of edge-to-edge is stale.

## Runtime Proof Gate

- Do not trust screenshots until a fresh uninstall -> install -> launch loop has been completed for the current build.
- If the on-screen UI appears older than source, suspect stale install first — clear app data or force uninstall before reinstalling.
- If install or launch is failing, stop design iteration and fix runtime truth before continuing.
- Use ADB and Gradle from the command line when Android Studio is not available.

## Core Workflow

1. Define the screen's primary job and the one or two pieces of content that must win first attention.
2. Choose the Material structure first: `NavigationBar`, `NavigationRail`, `Scaffold`, `TopAppBar`, `ModalBottomSheet`, `ListDetailPaneScaffold`, or adaptive scaffold.
3. Apply typography, spacing, and color using Material tokens before inventing a custom scale.
4. Verify adaptive behavior across `WindowSizeClass` breakpoints — compact, medium, expanded.
5. Verify with emulator: fresh build, uninstall, install, launch, capture screenshot, inspect, fix, repeat.

## ASCII Flow

```text
Android design task
  -> Prove current build: fresh install, launch, screenshot
  -> Define primary screen job and attention hierarchy
  -> Choose Material 3 structure and adaptive scaffold
  -> Apply tokens for type, color, shape, spacing, and motion
  -> Verify compact, medium, expanded, theme, and font-scale states
  -> Patch, rebuild, recapture, and compare evidence
```

## Design Craft Checklist

Before writing or reviewing screen code, check these patterns from [references/design-craft-patterns.md](references/design-craft-patterns.md):

1. **Token discipline**: Every spacing, elevation, shape, color, and repeated typography value traces to a named token. No magic numbers in screen files. If a `TextStyle(fontSize = N.sp, fontWeight = W)` pattern appears 3+ times, extract it to a typography token or use the Material type scale.
2. **Data containment**: Values live in Cards, `ListItem` rows, or grid cells with visual boundaries, not floating in unbounded Column space.
3. **Visual anchoring**: Data labels include Material icons (18-20dp). Categorized lists use colored dot indicators (6dp Canvas circles) for instant visual grouping.
4. **Card hierarchy**: Hero card is visually distinct from secondary cards — `ElevatedCard` with level 3 tonalElevation + 28dp shape for hero, `Card` with 16dp shape for primary, `OutlinedCard` for secondary. Mixed content within one card uses `HorizontalDivider`.
5. **Data visualization**: Use `Canvas` for custom charts (radar, rings, gauges), animated score rings with `Animatable`, and gradient score bars. See [references/android-component-patterns.md](references/android-component-patterns.md#canvas-visualizations).
6. **Interactive polish**: Apply `AnimatedVisibility` for entrance reveals, `animateContentSize` for expanding sections, `spring()` for natural motion, container transforms for navigation transitions, and press feedback via `Indication` or `InteractionSource` on all tappable surfaces.
7. **Elevation and tonal surfaces**: Use `tonalElevation` for surface layering rather than drop shadows alone. Material 3 uses tonal color overlays to express elevation — `Surface(tonalElevation = N.dp)` shifts surface color automatically.
8. **Localization readiness**: All user-facing strings go through `strings.xml` — including section headers, CTAs, and short labels that seem "too small to localize" (they grow 30-50% in German/Russian). Verify RTL layout with forced RTL in developer options. Test German, Arabic, and CJK locales for overflow and mirroring.
9. **Competitor awareness**: Check competitor patterns before inventing novel solutions. Borrow containment and anchoring patterns, not brand identities.
10. **Adaptive layout**: Test on compact (phone), medium (foldable inner), and expanded (tablet) `WindowSizeClass`. Use `NavigationSuiteScaffold` or manual breakpoint switching. Verify that content reflows rather than just stretching.
11. **Accessibility**: All touch targets >= 48dp. All decorative images have `contentDescription = null`. All meaningful images and icons have descriptive `contentDescription`. Use `semantics { }` to merge related elements for TalkBack and provide custom actions.
12. **Shape consistency**: Use `MaterialTheme.shapes` scale (ExtraSmall through ExtraLarge) rather than ad-hoc `RoundedCornerShape` values. Keep shape language consistent across Cards, Buttons, Chips, and Sheets.

## Design Review Loop

- Prefer Android Studio Layout Inspector for hierarchy and bounds inspection when a project is runnable.
- If Layout Inspector is unavailable, use ADB screencap + uiautomator dump as fallback for screenshots and hierarchy XML.
- Prefer side-by-side before/after screenshots over verbal "looks better" claims.
- Ask for evidence of font scaling (100%, 130%, 200%), dark/light theme, and `WindowSizeClass` behavior when a change touches layout or hierarchy.

See:
- [references/ai-design-review-android.md](references/ai-design-review-android.md)
- [references/android-studio-design-loop.md](references/android-studio-design-loop.md)
- [scripts/capture-screenshot.sh](scripts/capture-screenshot.sh)
- [scripts/layout-inspector.sh](scripts/layout-inspector.sh)

## Expert Judgment

Decisions a senior Android design reviewer makes that go beyond checklist compliance:

### Compose vs. Views in 2026

Default to Compose for any new screen or greenfield module — it is the modern native baseline and this skill assumes it. Views still legitimately win in narrower cases:

- **Large existing View/XML codebases** where a full rewrite is not funded — interop via `ComposeView`/`AndroidView` at the screen boundary, migrate incrementally, do not force a big-bang rewrite for a design fix.
- **Performance-critical custom rendering** with `SurfaceView`/`TextureView` (camera preview, video, some game-like canvases) — Compose's `AndroidView` interop works but adds indirection; a thin View layer can still be simpler when the surface needs precise frame-timing control.
- **Heavy `RecyclerView` with complex diffing/animations already tuned** — `LazyColumn` is capable, but do not force a rewrite of a well-optimized, stable RecyclerView adapter purely for "modernization" without a design or velocity reason.
- Flag it as a smell, not a rule, when a team defaults to Views for a brand-new screen in 2026 — ask why, since Compose Material 3 is the better-supported path for adaptive layouts, dynamic color, and Material 3 Expressive.

### Design-System Governance

- A token system only pays off if it is enforced, not just documented. If screen files still contain 3+ repeated raw `TextStyle`/`Color(0xFF...)`/`dp` literals, the design system has a governance gap, not a discipline gap — recommend a lint rule (e.g., Compose lint check or custom detekt rule) over a style-guide reminder.
- When a design system diverges from Material 3 defaults (custom shape scale, custom type ramp), require the divergence to be named and centralized in one theme file — never let ad-hoc per-screen overrides recreate "shadow tokens."
- Treat Material 3 Expressive adoption as a system-wide decision, not a per-screen one: mixing baseline M3 shapes/motion with Expressive shapes/motion in the same app reads as visually inconsistent. Pick one posture per app (or per clearly-scoped surface) and document why.

### Platform Convention vs. Brand Identity

- Keep interaction models (navigation placement, back behavior, sheet vs. dialog choice, gesture conventions) aligned with platform convention even when a brand wants to differentiate — users' muscle memory for Android navigation is a usability asset, not a constraint to design around.
- Spend brand differentiation budget on what users actually perceive as "your app": color, shape language, motion character, illustration, voice/tone in copy. These can diverge from stock Material without confusing users.
- When a brand team pushes a fully custom navigation paradigm (e.g., no back button, custom bottom bar behavior) purely for differentiation, push back with the platform-convention cost: broken predictive-back expectations, broken TalkBack navigation order, and accessibility-services friction, all for a gain that is rarely measurable in retention.

### Foldable and Large-Screen Failure Modes

Common mistakes that pass phone-only review but fail on foldables/tablets:

- **Fixed single-pane layout stretched to expanded width** — content readable at 360dp becomes a wall of text at 840dp+. Constrain reading width or switch to a list-detail/two-pane structure at `WindowWidthSizeClass.EXPANDED`.
- **Not handling the fold seam / hinge** — content or interactive elements landing exactly on the hinge on a foldable's tabletop or book posture. Use `WindowInfoTracker`/`FoldingFeature` to detect the hinge and avoid placing critical controls there.
- **NavigationBar left in place on tablets** — Material guidance is explicit that `NavigationBar` should give way to `NavigationRail`/`NavigationDrawer` at medium/expanded width; leaving bottom nav on a tablet is one of the most common large-screen regressions.
- **Orientation/resizability assumptions baked into layout code** — assuming portrait-only or a fixed activity size breaks multi-window and free-form resizing, which recent Android versions increasingly force on large screens regardless of manifest declarations. Verify behavior with the emulator's resizable/foldable device profiles, not just a fixed Pixel phone skin.
- **Testing only at compact and expanded, skipping medium** — the foldable inner-display and small-tablet band (600-839dp) is where two-column layouts most often look cramped or where a rail/nav choice is wrong; do not skip it as "close enough" to either neighbor.

## Route Elsewhere

- Use [../software-mobile/SKILL.md](../software-mobile/SKILL.md) for platform selection, cross-platform decisions, or general Android architecture and implementation strategy.
- Use [../qa-testing-android/SKILL.md](../qa-testing-android/SKILL.md) for Espresso, UI Automator, Compose testing, device matrix planning, or screenshot diff testing.
- Use [../software-ui-ux-design/SKILL.md](../software-ui-ux-design/SKILL.md) for generic product UX patterns that are not Android-specific.
- Use [../software-accessibility/SKILL.md](../software-accessibility/SKILL.md) for broader accessibility remediation beyond Android-native visual design defaults.

## Navigation

### References

- [references/design-craft-patterns.md](references/design-craft-patterns.md) — token discipline, data containment, visual anchoring, dark theme, competitor analysis, and common anti-patterns
- [references/material-layout-spacing.md](references/material-layout-spacing.md) — 8dp grid, edge-to-edge, spacing discipline, adaptive layouts, and dashboard density
- [references/material-typography-color.md](references/material-typography-color.md) — Material type scale, dynamic color, tonal palettes, custom fonts, contrast, and accessibility
- [references/android-component-patterns.md](references/android-component-patterns.md) — NavigationBar/Rail/Drawer, TopAppBar, Scaffold, Cards, Chips, Canvas visualizations, and interactive animations
- [references/android-dashboard-design.md](references/android-dashboard-design.md) — overview-screen hierarchy, data display patterns, card hierarchy, and content-heavy dashboard heuristics
- [references/visual-guidance-patterns-android.md](references/visual-guidance-patterns-android.md) — Canvas terrains, energy rings, opportunity framing, narrative scroll flow, and guidance card patterns
- [references/ai-design-review-android.md](references/ai-design-review-android.md) — screenshot prompts, review checklists (structure, token audit, containment, anchoring), and proof expectations
- [references/android-studio-design-loop.md](references/android-studio-design-loop.md) — current Android Studio and emulator verification flow
- [data/sources.json](data/sources.json) — primary sources and freshness-check targets

### Scripts

These are optional helpers for a proven-build design loop. If the app cannot be built, installed, or launched cleanly, fix the build before staying in this skill.

- [scripts/_android_common.sh](scripts/_android_common.sh) — shared helpers for ADB, emulator, and AVD resolution
- [scripts/bootstrap-emulator.sh](scripts/bootstrap-emulator.sh) — create and boot an AVD for design iteration
- [scripts/build-android.sh](scripts/build-android.sh) — compile-only Gradle build wrapper
- [scripts/run-android.sh](scripts/run-android.sh) — build, uninstall, install, and launch for iterative design work
- [scripts/capture-screenshot.sh](scripts/capture-screenshot.sh) — save an emulator screenshot for review loops
- [scripts/layout-inspector.sh](scripts/layout-inspector.sh) — dump UI hierarchy via uiautomator for structure review

## Anti-Patterns

- Do not audit or redesign from screenshots that have not been tied to a fresh install and launch.
- Do not invent custom chrome before checking whether standard Material 3 structure already solves the hierarchy problem.
- Do not hardcode `Color(0xFF...)` values in Composables — use `MaterialTheme.colorScheme` roles so light, dark, and dynamic color adapt automatically.
- Do not use fixed `sp` sizes outside the Material type scale without justification — prefer `MaterialTheme.typography` roles.
- Do not rely on elevation shadows alone for depth — Material 3 uses `tonalElevation` (tonal color shift) as the primary depth signal; shadows are supplementary.
- Do not wrap `Box(Modifier.clickable { })` without providing a ripple `