Android Compose Design

Android Compose Design

This skill imposes intentional design and engineering choices on Android Compose work. The goal isn't to reject Material - it's to make sure design and architecture decisions are chosen, not defaulted into.

Core philosophy

1. Choose the style before writing code. When the user asks for "an Android app," declare a style choice and the reasoning in one sentence. Don't just start typing Card and Button with no plan.
2. M3 Expressive is a real option, not the enemy. Material 3 Expressive (the 2025-2026 evolution of M3) was promoted to stable in 2025 and includes customizable tokens, spring-based motion, variable fonts, and 35 morphing shapes. A well-customized M3 Expressive app is a legitimate design choice. The enemy is unstyled M3 defaults - purple Roboto on gray with no thought - not M3 itself.
3. Style first, components second. The visual style depends on what the app is. Don't apply Phantom-style glassmorphism to a finance tracker. Don't apply Duolingo-style playfulness to a security tool. Match style to purpose.
4. Compose-native, not web-ported. Use Compose idioms (Modifier, MaterialTheme, remember, LaunchedEffect, AnimatedVisibility). Don't generate code that reads like a translated React component.
5. Concrete tokens, not vague descriptions. Every style reference gives hex codes, exact dp/sp values, named font choices, and named Compose functions. "Use nice spacing" isn't a design decision; "16dp between cards" is.
6. Build for foldables and large screens. Foldables are still a small slice of total Android shipments but grew ~50% in 2026, and the same adaptive patterns also serve tablets and split-screen on regular phones. Use WindowSizeClass and NavigationSuiteScaffold for nav that adapts to compact/medium/expanded form factors. Don't ship phone-only.
7. Engineering decisions happen in parallel with style decisions. Where state lives, how insets are handled, what back gestures do, how permissions are asked - these aren't afterthoughts. See the Engineering track.

How to use this skill

When triggered, before generating any UI code:

1. Identify what the app is. Productivity, wellness, finance, gaming, community, mission-critical, consumer-personalized? Category determines style.
2. Pick one style from the five references below. State the choice and reasoning.
3. Read that style's reference file in full before writing code.
4. Apply universal rules (below) on top of style-specific tokens.
5. Don't mix styles in v1 apps. One app, one style. Style-mixing comes later, when the patterns are working.
6. Read the Engineering track in parallel - references/07-architecture.md for state and ViewModel patterns, references/09-platform-integration.md for edge-to-edge / splash / predictive back / permissions, references/10-accessibility.md for semantics and TalkBack. These apply regardless of style.
7. Run the 5-question checklist below before writing any MainActivity or screen composable.

Style selection guide

Five styles, picked deliberately to cover the bulk of real Android apps:

• references/00-m3-expressive-default.md - Modern M3 Expressive done well, with dynamic color, spring motion, custom tokens. The "right way" to use Material instead of fighting it. Default starting point if no specific style is named.
• references/01-dark-product-minimal.md - Linear, Phantom, Vercel, Raycast. Productivity, dev tools, dashboards, professional apps. Restrained, dark, precise.
• references/02-playful-warm.md - Duolingo, Headspace, Khan Academy Kids. Wellness, learning, community, kids, anything emotional. Warm, generous, illustrated.
• references/03-data-dense.md - Strava, Robinhood, Apple Health. Charts, metrics, finance, fitness. Numbers as the product.
• references/04-trust-signaling.md - VA.gov, USAA, Plaid, Stripe Checkout. Government-adjacent, healthcare, sensitive financial, mission-critical. Calm authority, generous spacing, conservative color.

If the app doesn't fit any of the five, ask the user to describe the vibe and build from scratch using the universal rules below as a base. Don't force-fit a style.

Engineering track (new in v3)

These apply regardless of which style was selected. Read in parallel with the style file. Each is short.

• references/07-architecture.md - Single-Activity + ViewModel + UDF, StateFlow, collectAsStateWithLifecycle, DI (Hilt or Koin - both valid 2026 defaults). The 2026 architectural default.
• references/08-state-and-effects.md - remember vs rememberSaveable, LaunchedEffect keys, DisposableEffect for resources, lifecycle-aware effects.
• references/09-platform-integration.md - Edge-to-edge insets (mandatory at targetSdk 35+), splash screen API, predictive back (mandatory at targetSdk 36, August 2026 Play deadline), runtime permissions, audio attributes for TTS/MediaPlayer. If a product spec from android-product-planning exists, treat its platform checklist (notifications, permissions, deep links, widgets, offline) as the source of truth and build against it instead of re-deriving these decisions.
• references/10-accessibility.md - Semantics, TalkBack, dynamic font scale (test at 200%), color contrast verification.
• references/11-performance.md - Strong skipping mode (default in Compose Compiler 2.0+), lazy-list keys, baseline profiles.
• references/12-build-and-deps.md - Version catalog, project hygiene, opinionated library defaults with alternatives named. No pinned version numbers - principles only.
• references/13-compose-and-build-gotchas.md - build-time traps that bite late: environment/build-target sanity (the phantom "wrong project" bug), material-icons core vs extended, ASCII-only source literals, and template dependency versions vs installed AGP. Read before the MCP starts writing code.

"Before you write code" checklist (5 questions)

Before generating any MainActivity.kt or screen composable, answer all five out loud - and explicitly say "N/A" with one-line reasoning if a question doesn't apply. Don't skip silently.

1. Style? (00/01/02/03/04, with one-sentence justification - why this style for this app.)
2. Where does state live? (Should be a ViewModel, exposed as StateFlow, consumed with collectAsStateWithLifecycle(). If you put mutableStateOf in a composable, justify why this state shouldn't survive rotation.)
3. What does the back gesture do? (Default NavController is fine for most flows. Custom flows need BackHandler or PredictiveBackHandler - see 09. At targetSdk 36, onBackPressed is no longer called.)
4. How are insets handled? (Scaffold covers most cases. If not using Scaffold, name the windowInsetsPadding you applied. Edge-to-edge is mandatory at targetSdk 35+.)
5. What are the loading, error, and empty states? (Not "I'll add them later" - name all three before writing the happy path.)

The deeper questions - permissions, semantics, splash, performance, build setup - live in the engineering reference files (07-12). Read those when their topic applies; don't try to answer them all in the checklist.

Design is unproven until it renders. Everything here is text - a palette and prose, not a picture. Treat the tokens as a hypothesis. Once the MCP builds the primary screen, render it (screenshot it on an emulator/device), look at it next to the named exemplar, and run the contrast numbers on the actual pixels. Adjust from what you see; do not call the design good on the strength of the spec alone.

Universal rules across all styles

These apply regardless of style choice.

Spacing

• 8dp grid: 4, 8, 12, 16, 24, 32, 48, 64. Don't invent values between these.
• Default screen padding: 16dp horizontal, 24dp top.
• Default vertical rhythm between sections: 24dp.
• Touch targets: 48dp minimum (Google accessibility floor). 56dp for primary CTAs.

Typography hierarchy

• Body text: 16sp default. Don't go below 14sp for anything users actually read.
• Headlines: 24-32sp depending on style.
• Labels/captions: 12-13sp.
• Line height: 1.4x for body, 1.2x for headlines.
• Maximum three type sizes per screen.

Color discipline

• Pick one accent color per app (or two harmonizing colors for warmer styles). Use it for primary actions and brand moments only.
• 60/30/10 rule: 60% background, 30% surface/secondary, 10% accent.
• Always provide a dark mode variant. Whether dark or light is the primary mode is a style choice (see each reference).
• Compute contrast, do not assert it. For every text/background and text/accent pair you specify, calculate the actual WCAG contrast ratio and show the number (e.g. #F7F8F8 on #08090A = 17.4:1, AAA). Never write "clears AA" without the figure. Any pair below 4.5:1 (3:1 for large/bold text) may carry only non-essential text. Re-check against the rendered colors once a screen exists, not just the spec.

Motion (updated for 2026)

• Default to spring-based animation, not tween/duration. Use spring() with Spring.StiffnessMedium and Spring.DampingRatioLowBouncy as starting points. Springs are interruptible and feel natural under user input.
• Reserve tween(durationMillis = X) for cases where exact timing matters (synced animations, scripted sequences).
• Use animate*AsState, AnimatedVisibility, Crossfade, AnimatedContent - Compose's animation APIs are mature; don't hand-roll timing.
• Never animate everything. Pick 2-3 moments per screen where motion adds meaning.

Adaptive layouts (new in v2, extended in v3)

• Use currentWindowAdaptiveInfo().windowSizeClass to detect compact/medium/expanded width.
• For app-level navigation, use NavigationSuiteScaffold - it switches automatically between NavigationBar (compact), NavigationRail (medium), and PermanentNavigationDrawer (expanded).
• For detail/list patterns, use ListDetailPaneScaffold for two-pane on larger screens.
• Test on a folded phone, an unfolded foldable, and a tablet emulator before declaring a screen "done."
• Adaptive layout has to coexist with edge-to-edge enforcement at targetSdk 35+ (Android 15) and the mandatory predictive back gesture at targetSdk 36 (Android 16, Google Play deadline August 2026). See references/09-platform-integration.md.

Surface elevation (updated for 2026)

• 2026 trend: subtle layered surfaces using tonal elevation, not flat-only and not heavy drop shadows.
• Compose: Surface(tonalElevation = X.dp) produces tonal elevation; the surface color shifts subtly to imply depth without shadow.
• Default tonal elevation hierarchy: 0dp (background), 1dp (cards), 3dp (sheets/dialogs), 6dp (modals).
• Hard drop shadows are a style choice (style 02 uses them deliberately) - not a default.

What to avoid across all styles (the AI cliches)

• Unstyled Material 3 (purple primary, Roboto everywhere, no token customization)
• Generic decorative purple gradients (0xFF6200EE and its cousins)
• Inter, Roboto, or Space Grotesk as the default - they're correct in specific styles but overused as a fallback
• Glassmorphism applied everywhere (it's a style choice, see notes in 00 and 01)
• Centered single-column everything with no hierarchy
• RoundedCornerShape(8.dp) on everything - radius is a style choice, not a habit
• Spinners for loads under 2 seconds (use skeleton screens)
• "You did it!" celebration animations on non-celebratory actions
• Hardcoded strings in composables (always strings.xml - translation and accessibility both depend on it)
• collectAsState() instead of collectAsStateWithLifecycle() - the former keeps collecting while the screen is backgrounded; the latter is the canonical 2026 API
• Putting state and side effects in MainActivity with no ViewModel (single-Activity + ViewModel is the 2026 default; see references/07-architecture.md)
• Forgetting enableEdgeToEdge() or forgetting to handle WindowInsets after enabling it - both produce broken UIs at targetSdk 35+

Components reference

For specific component patterns (forms, lists, navigation, empty states, onboarding, search), read:

• references/05-component-patterns.md

Compose code snippets

Paste-ready Compose code matching token systems:

• references/06-compose-snippets.md

Optional: personal asset folder

If $CLAUDE_ASSETS/android/ exists, read $CLAUDE_ASSETS/android/index.md before falling back to this skill's defaults. The personal folder can hold:

• Project-specific brand overrides (per-app palettes, custom fonts, brand microcopy)
• New styles being developed before they're skill-worthy
• Screenshots and exemplar references
• Per-app design system overrides

This keeps the public skill portable while letting personal taste layers and per-project brand systems override the defaults.

Lessons learned

v2 -> v3 lessons (May 2026)

What v2 got wrong, surfaced by validating against current sources and against real-world coding use:

• M3 Expressive is now stable. v2 said it was experimental. The opt-in annotation is no longer required at the theme level. Updated 00 and 06.
• Edge-to-edge is mandatory at targetSdk 35+. v2 didn't mention it. New 09-platform-integration covers it.
• Predictive back is mandatory at targetSdk 36. v2 didn't mention it. New 09 covers it, including the distinction between BackHandler (intercept) and PredictiveBackHandler (animated progress).
• Downloadable Google Fonts does not support variable fonts. v2's Roboto Flex snippet in 00 silently fell back to static cuts. Fixed to bundle the .ttf locally with FontVariation.
• collectAsStateWithLifecycle is the canonical flow-collection API. v2 never named it. New 07-architecture covers it; SKILL.md checklist requires it.
• The skill was design-only. Real Android apps need architecture, state/effects, platform integration, accessibility, performance, and build/deps. New Engineering track (07-12) covers these. Style choice and engineering choice happen in parallel, not sequentially.
• Foldable market sizing was overclaimed. v2 said 10-12% of shipments; current 2026 data puts foldables at a few percent of total Android, with the category growing ~50% YoY. Softened the claim in SKILL.md.
• NavigationSuiteScaffold should be the bottom-nav default, not NavigationBar directly. v2's universal rules said this, but 05 and 06 snippets used NavigationBar directly. Reconciled to NavigationSuiteScaffold.

v1 -> v2 lessons (preserved from v2)

• M3 Expressive is not the enemy. v1 framed all of Material as the cliche. v2 added M3 Expressive as style 00 and the default starting point.
• Motion guidance was 2023. v1 said "200ms for state changes." Real 2026 Compose uses spring-based physics.
• VA.gov font was wrong. v1 said IBM Plex Sans. VA actually uses Source Sans (now Source Sans 3) + Bitter.
• Linear tokens were 2023 Linear. Updated to current neutral / desaturated direction.
• "Flat surfaces only" was wrong direction. v2 introduced tonal layering for depth without shadow.
• No foldable/adaptive coverage in v1. Added to universal rules.
• App-specific defaults leaked into style 04. v2 generalized to trust-signaling broadly.

Sources used to validate v3

• developer.android.com/jetpack/androidx/releases/compose-material3 (M3 Expressive stable)
• developer.android.com/guide/navigation/custom-back/predictive-back-gesture (Predictive back)
• developer.android.com/codelabs/edge-to-edge (Edge-to-edge enforcement at API 35+)
• developer.android.com/develop/ui/compose/state (collectAsStateWithLifecycle)
• developer.android.com/develop/ui/compose/performance/stability/strongskipping (Strong skipping mode)
• design.va.gov/foundation/typography (Source Sans 3 + Bitter confirmation)
• linear.app/brand (Current Linear direction)
• developer.android.com/develop/ui/compose/accessibility/semantics (Compose accessibility)
• developer.android.com/topic/architecture (UDF, ViewModel, state holders)

v3 -> v4 candidates

• Add a "consumer-personalized" style for apps that lean hard into Material You dynamic color.
• Add wearable considerations (TransformingLazyColumn, edge-hugging buttons for Wear OS) if any project needs them.
• Add glassmorphism as a component pattern in 05 (the resurgence is real per current sources, including Linear).
• Validate token values empirically by building a screen in each style and checking how close it looks to the named exemplar.
• Consider adding a "screenshots and visual references" reference file that lists URLs for Claude to web_fetch when relevant.
• Explicitly out of scope: Compose Multiplatform. CMP for iOS is stable as of 1.8.0 (May 2025) and the temptation is to add iOS guidance here. Resist. This skill stays Android-focused. A peer skill (android-compose-design-cmp or similar) can import tokens from this one and add the iOS overlay. Letting this skill grow into a multi-platform thing is how it stops being useful for the Android-only case it was built for.

How to update this section

After each significant use of the skill, add a one-line entry under v3 -> v4 candidates. Once 5-10 entries accumulate, do a v4 pass. Don't iterate after every single use - wait for the pattern.