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.android.com / m3.material.io" in the output; never invent a number. This
  applies especially to the gaps flagged in Steps 2–4, 8, 9 above (full 45-role color
  system, 32/48dp/Full shapes, FAB tier dp sizes, motion spring parameters) — the
  reference files for these are not yet expanded/created; do not backfill invented
  numbers to close that gap silently.

### Output
- Device-framed HTML mockup at the target window size class.
- `handoff.md` (or equivalent) with Compose theme mappings, spacing, sizing, states,
  tonal elevation (level 0–5) — ready for an Android developer.

### Next → `design-review` (mockup-scoped: screenshot the mockup, verify contrast, no
full site audit loop).

### References
| File | Purpose |
|------|---------|
| `references/type-scale.md` | **Canonical Material 3 baseline type scale — verified material-components-android** (Expressive Emphasized set: see Step 1 above, not yet a separate file) |
| `references/shape-scale.md` | **Canonical shape/corner-radius scale — verified m3.material.io** (stops at 28dp — 32/48/Full gap, see Step 3) |
| `references/color-roles.md` | **Canonical Material 3 core color-role families — verified m3.material.io** (45-role/surface-container/dynamic-color gap, see Step 2) |
| `references/window-size-classes.md` | **Canonical window size classes — verified developer.android.com** |
| `references/touch-targets.md` | 48×48dp target + 8dp spacing — verified |
| `references/handoff-compose.md` | Compose-ready handoff spec format |

**Gaps (grounded facts, no reference file yet — inlined in Steps above, flagged for future
`references/elevation.md`, `references/motion.md`, FAB-tier detail; out of this pass's
exclusive scope to create)**: elevation tokens 0–5, FAB tiers, spring motion.