software-android-designDesigns and audits native Android interfaces. Use when reviewing Compose layout, typography, color, motion, or adaptive patterns on a verified emulator build.
Independent GitHub snapshot · Automated classification · Original documentation governs
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.
| 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 from medium through extra-large width (the NavigationSuiteScaffold default), expanded rail (not drawer) under M3 Expressive |
| Top bar | TopAppBar / MediumTopAppBar / LargeTopAppBar / CenterAlignedTopAppBar | Choose by headline presence; collapsing variants for rich headers |
| Cards | ElevatedCard hero, Card primary, OutlinedCard secondary | Optional team hierarchy; use theme surface/elevation defaults |
| Adaptive layouts | ListDetailPaneScaffold, SupportingPaneScaffold, NavigationSuiteScaffold | Feed grids for homogeneous content |
| Detail views | Sheet for a focused task; destination or detail pane for deep content | Preserve context and back behavior |
| Motion | Container transforms, AnimatedVisibility, animateContentSize, spring() | M3 Expressive defaults |
| Edge-to-edge | enableEdgeToEdge() + windowInsetsPadding | Mandatory, non-optional for targetSdk 36+ (windowOptOutEdgeToEdgeEnforcement removed) |
| Predictive back | Navigation and Material component defaults | Custom PredictiveBackHandler only for custom gesture-driven behavior |
| Press feedback | Standard clickable Material component or Modifier.clickable | Default indication provides feedback; custom scale motion is optional |
| 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 |
| Touch targets | ≥ 48dp on all interactive elements | Platform minimum |
| Token discipline | No magic numbers in screen files | Tokenize spacing, elevation, shape, color |
MaterialTheme.typography, MaterialTheme.colorScheme, MaterialTheme.shapes, and standard containers before custom styling.Look these up each session; never hard-code them in advice or generated code:
Material3ExpressiveApi does not require opt-in; ExperimentalMaterial3ExpressiveApi does.onBackPressed() and KEYCODE_BACK are no longer dispatched at that target. Prefer supported navigation/component handling; custom interception can disable system animations.windowOptOutEdgeToEdgeEnforcement is deprecated and has no effect once targetSdk reaches 36. Any recommendation that relies on opting out of edge-to-edge is stale.adb install -r so saved state and the exact repro survive. Clear data or uninstall only after capturing the current state and proving stale state, schema incompatibility, or a signing mismatch.NavigationBar, NavigationRail, Scaffold, TopAppBar, ModalBottomSheet, ListDetailPaneScaffold, or adaptive scaffold.currentWindowAdaptiveInfo(supportLargeAndXLargeWidth = true) and isWidthAtLeastBreakpoint(...); verify compact, medium, expanded, and Large/Extra-large for desktop or connected-display targets. Load material-layout-spacing.md for ordered checks, height constraints, and hinge handling.Before accepting a visual change, capture the affected screen in populated, loading, empty, error, and disabled/permission states that the feature can reach. Cross those states with the smallest device/configuration set that can expose the risk: compact + expanded width for adaptive changes, 200% font scale for text/layout changes, light + dark for color/material changes, and TalkBack focus order for semantic changes. A single polished happy-path screenshot is presentation evidence, not state coverage.
Before writing or reviewing screen code, check these patterns from references/design-craft-patterns.md:
TextStyle(fontSize = N.sp, fontWeight = W) pattern appears 3+ times, extract it to a typography token or use the Material type scale.ListItem rows, or grid cells with visual boundaries, not floating in unbounded Column space.ElevatedCard/Card/OutlinedCard is a team default, not a platform-required hierarchy. Keep shape/elevation values in theme tokens.Canvas for custom charts (radar, rings, gauges), animated score rings with Animatable, and gradient score bars. See references/android-component-patterns.md.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.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.strings.xml, including short labels. Test longer translations, Arabic RTL, and CJK locales for overflow and mirroring.contentDescription = null. All meaningful images and icons have descriptive contentDescription. Use semantics { } to merge related elements for TalkBack and provide custom actions.MaterialTheme.shapes scale (ExtraSmall through ExtraLarge) rather than ad-hoc RoundedCornerShape values. Keep shape language consistent across Cards, Buttons, Chips, and Sheets.WindowSizeClass behavior when a change touches layout or hierarchy.See:
Decisions a senior Android design reviewer makes that go beyond checklist compliance:
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:
ComposeView/AndroidView at the screen boundary, migrate incrementally, do not force a big-bang rewrite for a design fix.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.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.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.NavDisplay; preserve a working Navigation Compose NavHost for a scoped visual fix. Navigation 3 uses scene strategies to render one or more entries, so test pane changes during window resizing. Load android-component-patterns.md when choosing scene transitions.Common mistakes that pass phone-only review but fail on foldables/tablets:
isWidthAtLeastBreakpoint(WindowSizeClass.WIDTH_DP_EXPANDED_LOWER_BOUND); make a separate Large/Extra-large choice when extra space supports another pane.WindowInfoTracker/FoldingFeature to detect the hinge and avoid placing critical controls there.NavigationSuiteScaffold uses a bar for compact width, compact height, or tabletop posture; otherwise it uses a rail. A tablet can still need the bar in a constrained window.screenOrientation, resizableActivity, min/maxAspectRatio, and setRequestedOrientation() (games are exempt via appCategory); a temporary opt-out (PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY) stops working at targetSdk 37. Verify behavior with the emulator's resizable/foldable device profiles, not just a fixed Pixel phone skin, and check Play's adaptive app quality tiers — verify current thresholds at developer.android.com/docs/quality-guidelines/adaptive-app-quality.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.
--uninstall-first is an escalation, not the default)python3, using mocked ADB/GradleColor(0xFF...) values in Composables — use MaterialTheme.colorScheme roles so light, dark, and dynamic color adapt automatically.sp sizes outside the Material type scale without justification — prefer MaterialTheme.typography roles.tonalElevation (tonal color shift) as the primary depth signal; shadows are supplementary.Box(Modifier.clickable { }) without providing a ripple Indication — it produces a dead-feeling tap with no visual response.ModalBottomSheet as the sole navigation mechanism — it is for secondary detail, not primary app structure.WindowInsets consumption after calling enableEdgeToEdge() — content will render behind system bars.LazyColumn inside a vertical-scrolling parent; it throws during measurement. Prefer one mixed-item LazyColumn. A bounded-height child or different-axis scroller is valid; see Google's nesting examples.pointerInput with detectTapGestures for simple click handling — use Modifier.clickable which provides accessibility semantics, ripple, and focus handling for free.Color.White or Color.Black for text or surfaces — use MaterialTheme.colorScheme.onSurface, onSurfaceVariant, or outline roles.contentDescription on meaningful icons and images — TalkBack users get no information from undescribed elements.fillMaxWidth() on every element without considering medium and expanded WindowSizeClass — content stretches to unreadable line lengths on tablets.ModalBottomSheet and present a new one in the same frame — set state to hidden first, then present the new sheet after recomposition.animatableProgress at 0f for data-driven views — data may load after composition, leaving the Canvas empty. Start at 1f or trigger animation on data change.LazyVerticalGrid with GridCells.Fixed(3) on compact phones for content that needs readable text — two columns or a single column with weight-based rows works better. Reserve Fixed(3) for icon-sized cells or compact stat grids.Modifier.background() with a rounded shape without also applying .clip() to the same shape — child content will bleed past the rounded corners. Use Surface(shape = ...) instead, which clips automatically.rememberSaveable for large data objects or lists — it serializes to Bundle which has a strict 1MB transaction limit. Use a ViewModel for screen-level data state; use rememberSaveable only for primitive UI state (selected tab index, scroll position, sheet expanded boolean).Before concluding a design recommendation or audit, confirm all of the following:
MaterialTheme.typography roles, not ad-hoc TextStyle(fontSize = N.sp)MaterialTheme.colorScheme roles; contrast verified in both light and dark themes, with dynamic color on and offenableEdgeToEdge() called and all content uses windowInsetsPadding or equivalent — not an opt-out (windowOptOutEdgeToEdgeEnforcement has no effect at targetSdk 36+)Use Platform Currency and data/sources.json for platform/dependency decisions; consult the installed artifact's API reference before changing components.
When prior decisions or pitfalls are relevant, consult learnings.consolidated.md if present; use learnings.md only for needed history or as the available fallback. Otherwise skip both.
After applying it, if you encountered a pattern worth remembering, a mistake worth preventing, or a domain fact that surprised you, append one dated bullet to learnings.md via agents-skills-feedback-loop/scripts/append_learning.py. Do not modify SKILL.md itself.