/design-android

name: design-android
description: "Use when designing an Android screen or flow — deliverable is a device-framed HTML mockup and developer handoff spec, never Compose code."
when-to-use: "Designing an Android screen or flow — the deliverable is a device-framed HTML mockup and a handoff spec for an Android developer to implement, not working Compose."
keywords: android, material3, expressive, compose, handoff, mockup, window-size-classes, elevation, fab, motion
priority: critical
related: design-method, design-system, design-review

<objective> Produces Android mockups and developer handoff specs: mapping design tokens to the Material 3 Expressive type scale (baseline plus the parallel Emphasized set), the full color-role system (45 roles, including the surface-container ramp and dynamic color), elevation tokens, the shape scale, window size classes, and FAB tiers.

The deliverable is a device-framed HTML mockup at the target window size class plus a Compose-ready handoff spec (colors, typography, shapes, spacing, states, tonal elevation). This skill never writes Jetpack Compose code — implementation is left to an Android developer. </objective>

Design Android — Mockup and Handoff, Not Code

When

After `design-system` tokens exist. This skill never writes Jetpack Compose — it produces a static HTML mockup at exact device dimensions plus a spec an Android developer implements.

Input

• `design-system.md` — OKLCH palette, typography direction, motion personality.
• The screen/flow to mock up and the target window size class.

Steps

1. **Map tokens to Material 3 type roles.** `references/type-scale.md` gives the 15-role baseline scale (displayLarge 57/64sp … labelSmall 11/16sp, Roboto). Material 3 Expressive adds a parallel **15-role Emphasized set** on top (30 roles total) for stronger visual rhythm — use baseline by default, reach for Emphasized when the tone from `design-method` calls for it. Source: m3.material.io/styles/typography/type-scale-tokens. 2. **Map tokens to Material 3 color roles.** `references/color-roles.md` documents the core role families (primary/secondary/tertiary + surface/onSurface) derived from a seed color. Material 3's full role system is larger — **45 color roles**, including a **surface-container ramp** (lowest → highest: `surfaceContainerLowest`, `surfaceContainerLow`, `surfaceContainer`, `surfaceContainerHigh`, `surfaceContainerHighest` — 5 levels for layering surfaces without shadow), `error`/ `onError`/`errorContainer` (kept **static**, never derived from the dynamic seed, so error states stay legible regardless of theme), and **dynamic color**: on Android 12+ all roles can be generated tonally from a user's wallpaper/seed, not just the design seed. Source: m3.material.io/styles/color/roles, m3.material.io/styles/color/system/how-the-system-works. **Gap**: `color-roles.md` documents the core families, not the full 45-role/surface-container enumeration — use the fact above until that reference is expanded (out of this pass's exclusive scope). 3. **Map tokens to shapes.** `references/shape-scale.md` (never an arbitrary border-radius). Material 3's full shape scale extends to **32dp, 48dp, and Full** (pill) beyond what's currently listed — Expressive defaults buttons to **pill (Full)** shape unless a product reason calls for a smaller radius. Source: m3.material.io/styles/shape/shape-scale-tokens. **Gap**: `shape-scale.md` stops at 28dp (Extra Large); reconfirm 32/48/Full on the m3.material.io page above until expanded. 4. **Apply elevation as tokens, not ad-hoc shadow.** 6 levels, **0 → 5**, mapping to **0 / 1 / 3 / 6 / 8 / 12dp**. Elevation is expressed via **shadow** at each level — the older `surfaceTint`-only approach is **deprecated**; don't rely on tint alone to convey elevation. Source: m3.material.io/styles/elevation/overview. **Gap**: no `references/elevation.md` exists yet — these token values are grounded but inlined here pending a dedicated reference file (out of this pass's exclusive scope). 5. **Pick the window size class** from `references/window-size-classes.md` — mock up at the dp width that matches the target device class (phone/foldable/tablet/desktop). 6. **Build the HTML mockup**: a device-frame `<div>` sized in dp-equivalent px, following the 4dp base / 8dp grid throughout. 7. **Verify touch targets and spacing**: 48×48dp minimum touch target, ≥ 8dp spacing between adjacent targets — see `references/touch-targets.md`. 8. **FAB: pick one of 3 tiers**, sized to the screen's primary-action weight — small FAB is **deprecated** in Material 3 Expressive, don't use it. Source: m3.material.io/components/floating-action-button/overview. **Gap**: no dedicated FAB reference file yet; the 3 surviving tiers and their exact dp sizes should be reconfirmed on the page above before finalizing a mockup. 9. **Motion**: Material 3 Expressive uses **spring-physics-based motion** (not fixed duration/easing curves) for its signature feel; the legacy duration/easing-curve tokens still apply where spring motion isn't specified. Source: m3.material.io/styles/motion/overview. **Gap**: no `references/motion.md` exists yet — note spring vs legacy-easing choice explicitly in the handoff spec until one exists. 10. **Write the handoff spec** per `references/handoff-compose.md`: colors → `MaterialTheme.colorScheme.*`, typography → `MaterialTheme.typography.*`, shapes → `MaterialTheme.shapes.*`, custom spacing scale in dp, explicit sizing, states + tonal elevation (name the elevation *level*, 0–5, not just "raised"/"flat"), and **start/end** (never left/right) for RTL correctness.

Failure Handling

• Screenshot/preview tooling unavailable → describe the mockup in the handoff spec with

exact dp values instead of blocking on a visual.

• A fact needed isn't in the references below → mark it "to reconfirm on

developer.a