android-design

android-design — pick the track first

Android has multiple stacks with different visual ceilings. Ask the user which one before any code.

What This Skill Can Do

• Choose the right Android track: strict Compose/Material, branded Compose, React Native, Flutter, or Compose Multiplatform.
• Design mobile task flows, onboarding, forms, settings, dashboards, media/product surfaces, foldables, tablets, and adaptive layouts.
• Preserve UX briefs, state coverage, navigation hierarchy, gesture/back behavior, loading/error/permission states, and accessibility.
• Apply Material 3 Expressive, dynamic color, edge-to-edge, predictive back, motion schemes, shape, typography, and responsive window-size classes.
• Add branded originality through content surfaces, composition, typography, and state treatment without breaking Android idioms.

Step 0 (MANDATORY) — Ask the user which track

Which track for this app?

1. System-like native (Jetpack Compose + Material 3 Expressive strict) — feels like Pixel Launcher, Google Calendar, Settings. Best for: utilities, system tools, productivity. Spring physics, shape morphing, wavy progress, dynamic color (Material You). Examples: Read You, Androidify sample, Files by Google.

2. Branded native (Compose + custom Material theme) — native chrome (M3E motion, predictive back, edge-to-edge) but bespoke content surface (custom typography, hero atmospheres, magazine layouts). Visual ceiling: high. Examples: Fitbit redesign, Google Calendar's editorial moments, Niantic apps.

3. React Native (New Architecture + Fabric + Hermes) — real Android views, decent native feel, JavaScript codebase, cross-platform with iOS. Material themable but won't get spring physics or shape morphing without manual work. Examples: Discord mobile, Coinbase, Microsoft Office.

4. Flutter — Skia-painted custom rendering. Cross-platform single codebase. Lags Material updates (no M3 Expressive parity, no real dynamic color). Visual ceiling: high if you ship your own design language; weak if mimicking Material. Examples: Google Pay, BMW My BMW, Toyota.

5. Compose Multiplatform (1.8+) — same Compose code, runs Android + iOS + Desktop + Web (Wasm experimental). Native on Android, Material-look on iOS (you must Cupertino-skin or accept). Best for: Kotlin shop wanting cross-platform from one codebase.

Which? Or describe priorities (Play Store launch, cross-platform reach, brand vs Material fit) and I'll pick.

If brief gives strong signal (e.g. "Pixel-style camera" → 1; "cross-platform with React team" → 3; "Kotlin shop, ship to all platforms" → 5), state your pick + reasoning in one sentence. If ambiguous, ask.

Step 0b — Once picked, route

Track	Reference docs	Default stack
1. System-like Compose	../../references/material3-expressive.md	Compose BOM 2026.06.00 + Material3 1.4 + adaptive layouts strict
2. Branded Compose	Same as 1	Same as 1 + custom display font + hero atmospheres + bespoke surfaces
3. React Native	../../references/web-fonts.md + cross-platform docs	RN 0.86 New Architecture + Expo Router
4. Flutter	None for native fidelity	Flutter 3+ stable
5. Compose Multiplatform	../../references/material3-expressive.md	Current stable CMP + shared Compose

For tracks 3 and 4: web/cross-platform anti-slop rules apply. Read web references.

State the chosen aesthetic direction and track in one sentence at top of response.

Step 0c — UI decision brief

Before code, read:

• ../../references/ui-patterns/surface-taxonomy.md
• ../../references/ui-patterns/ui-decision-brief.md
• ../../references/ui-patterns/visual-hierarchy.md
• ../../references/ui-patterns/motion-budget.md

Write the UI decision brief and adapt it to the chosen Android track. Compact screens need thumb-reachable primary actions, sheets, edge-to-edge, and adaptive navigation; tablets/foldables need list-detail or supporting panes; operational tools should stay dense and scannable while preserving Material 3 Expressive motion, dynamic color, and predictive back.

Step 1 — Material 3 Expressive default (only if track 1 or 2)

Launched at I/O 2025. Default for Pixel 10 / Android 16 QPR1. Generated UI must adopt:

• Spring physics on every motion — MotionScheme.expressive(). Never FastOutSlowIn on M3E surfaces.
• Shape morphing — 35 new shapes (squircle, pill, cookie, clover). Use MaterialShapes.Cookie4Sided, Pill, etc. Buttons/chips/loaders morph between states.
• Emphasized typography — bigger, heavier headlines. Use MaterialTheme.typography.displayLarge with intent.
• New components:
  • FloatingToolbar (pill-shaped, drifts with content)
  • ButtonGroup / SplitButton
  • FloatingActionButtonMenu
  • ContainedLoadingIndicator (cycles through M3E shapes)
  • Wavy progress — LinearWavyProgressIndicator, CircularWavyProgressIndicator with variable amplitude
  • Large/Small/XL button sizes
• Tonal elevation — surface tone shifts, never Modifier.shadow() for elevation
• Dynamic color (Material You) — dynamicColorScheme() from wallpaper on Android 12+

Read ../../references/material3-expressive.md for the M3E adoption checklist.

Step 2 — Compose currency (BOM 2026.04.01)

implementation(platform("androidx.compose:compose-bom:2026.04.01"))
implementation("androidx.compose.material3:material3:1.4.0")
// or for shape-morphing chips:
implementation("androidx.compose.material3:material3:1.5.0-alpha18")

Use:

• currentWindowAdaptiveInfo() + NavigationSuiteScaffold (auto-swaps Bar/Rail/Drawer by WindowSizeClass)
• ListDetailPaneScaffold, SupportingPaneScaffold, NavigableListDetailPaneScaffold
• SharedTransitionLayout { ... } for shared element transitions (stable)
• PredictiveBackHandler / BackHandler — mandatory on Android 16, default ON Android 15+
• LookaheadAnimationVisualDebugging for inspecting bounds during dev

Step 3 — Edge-to-edge is mandatory

Android 16 (API 36) deprecated windowOptOutEdgeToEdgeEnforcement. Every screen:

• Wraps in Scaffold with content padding from insets
• Uses WindowInsets.systemBars, .statusBars, .navigationBars
• Predictive back must be wired
• Status bar color cannot be set opaque — banned on Android 16

Step 4 — Adaptive layouts

• Compact (phone portrait) → NavigationBar (3–5 items)
• Medium (foldable inner / tablet portrait) → NavigationRail
• Expanded (tablet landscape / desktop) → NavigationDrawer (modal or permanent) + ListDetailPaneScaffold
• Foldables: handle tabletop / book postures via WindowInfoTracker

Step 5 — Typography & icons

• Default body: Roboto Flex (variable). Headlines: per-app brand expression — but stay within M3E weight/size scale.
• Material Symbols (variable axes: weight, fill, grade, optical size) — never FontAwesome/Lucide.
• Get Material Symbols from https://fonts.google.com/icons

Step 6 — Anti-slop ban list (Android-specific)

• iOS-style top nav bars / chevron-back headers
• Hamburger drawer when NavigationBar (3–5 items) or NavigationRail fits
• Hard Modifier.shadow(elevation = 8.dp) — use tonalElevation on Surface instead
• Custom back stacks ignoring system back / predictive animation
• Opaque colored status bars — banned on Android 16
• Bottom sheets without drag handle / non-draggable
• Static easing curves on M3E surfaces — MotionScheme.expressive() only
• SF Symbols / Material Symbols-Outlined-only (use variable axes)
• Inter / SF Pro on Android — Roboto Flex / Google Sans / Material default
• Centered FAB layouts where docked FAB pattern is canonical
• Standard Material 3 baseline 2023 — must be M3 Expressive
• Web-style desktop dashboards squeezed into mobile Compose
• Decorative motion that hides progress, state, or navigation changes

Step 7 — Reference apps that nail M3 Expressive

• Pixel Launcher / Android 16 System UI — shape morph + springs
• Google Calendar — floating toolbar + tonal surfaces
• Fitbit (2025 redesign) — ContainedLoadingIndicator cycling shapes; floating toolbar
• Pixel Camera 10.1 — wavy progress in capture
• Google Docs/Sheets/Slides homepages — M3E typography
• Chrome (M3E redesign) — adaptive nav
• Read You (community RSS, OSS) — canonical M3 + dynamic color
• Androidify sample app — official Compose M3E reference

Step 8 — Architecture defaults

• MVVM with ViewModel + StateFlow + collectAsStateWithLifecycle()
• Hilt for DI
• Navigation Compose 3 with type-safe routes
• Coil 3 for image loading (replaces Glide for Compose-first apps)
• Ktor or Retrofit + KotlinX Serialization for networking
• Room for local persistence

Step 9 — Tokens & assets

• M3 token spec: https://m3.material.io/foundations/design-tokens/how-to-use-tokens
• Theme Builder (web): https://m3.material.io/theme-builder
• Theme Builder Figma plugin: https://www.figma.com/community/plugin/1034969338659738588
• M3 Figma kit: https://www.figma.com/community/file/1035203688168086460
• Material Symbols: https://fonts.google.com/icons
• M3E component catalog: https://github.com/meticha/material-3-expressive-catalog

Token JSON: see ../../assets/tokens/material3-expressive.json