material-design

Material Design 3 (Material You) UI guidelines. Load for Android or cross-platform design.

SKILL.md

GitHub

Detection Signals

Load this skill when any of the following are present:

Signal Location
Android target in cross-platform project react-native, Flutter, or pubspec.yaml with Android support
Native Android project build.gradle, build.gradle.kts, AndroidManifest.xml
Material components dependency com.google.android.material in build.gradle, material3 in pubspec.yaml, @react-native-material/core in package.json
Design task for Android or cross-platform app User mentions "Android design", "Material", or "Material You"

Core Principle — Material You

Material Design 3 is dynamic and personalized: colors adapt to the user's wallpaper, shapes express brand personality, and components communicate state through motion. Design decisions must always consider adaptability, not fixed aesthetics.


Color System

Color Roles (Semantic Tokens)

Never use raw hex values — always use semantic color roles so the system adapts to dynamic color and dark mode automatically.

Role Usage
primary Key actions, selected states, active indicators
onPrimary Content (text/icons) placed on top of primary
primaryContainer Less prominent filled surfaces related to primary
onPrimaryContainer Content on primaryContainer
secondary Supporting actions, less prominent components
tertiary Contrasting accents to complement primary and secondary
surface Backgrounds for cards, sheets, menus
surfaceVariant Alternate container surfaces (chips, input fields)
onSurface Body text and icons on surfaces
onSurfaceVariant Subdued text and icons on surfaces
outline Borders and dividers
outlineVariant Subtle decorative dividers
error Error states and destructive actions only
onError Content on error containers
inverseSurface High-emphasis surfaces in snackbars and tooltips

Dynamic Color (Android 12+)

  • Generate your palette with the Material Theme Builder — do not hand-pick colors without tonal palette generation
  • Always provide a fallback palette for devices running Android < 12 (no dynamic color support)
  • Test both a light wallpaper and a dark wallpaper to verify legibility across dynamic palettes

Contrast Requirements

  • Body text on surfaces: minimum 4.5:1 contrast ratio (WCAG AA)
  • Large text (≥ 18sp regular / ≥ 14sp bold) and UI components: minimum 3:1
  • Never rely on color alone to convey meaning — always pair with a shape, icon, or label

Dark Mode

  • Dark surfaces use tonal elevation instead of shadow: as elevation increases, the surface tint (using primary) increases
  • surface dark: #121212 base; elevated surfaces use surfaceColorAtElevation(dp)
  • Never invert the light-mode palette manually — use the generated dark tonal palette

Typography

Material Design 3 defines five type scales. Use them semantically — do not invent custom size names.

Scale Size (sp) Weight Usage
displayLarge 57 Regular Hero numbers, very large short text
displayMedium 45 Regular Key metrics, prominent numbers
displaySmall 36 Regular Large callouts
headlineLarge 32 Regular Page titles
headlineMedium 28 Regular Section headings
headlineSmall 24 Regular Card titles, dialog headings
titleLarge 22 Regular App bar titles
titleMedium 16 Medium List item primaries, emphasized labels
titleSmall 14 Medium Sub-labels
bodyLarge 16 Regular Primary body copy
bodyMedium 14 Regular Secondary body copy, descriptions
bodySmall 12 Regular Captions, helper text
labelLarge 14 Medium Button labels, tab labels
labelMedium 12 Medium Chip labels, badge labels
labelSmall 11 Medium Overlines, smallest labels

Rules:

  • Use sp units (not dp or px) — they scale with the user's font size preference
  • Do not mix more than 3–4 type scales in a single screen
  • Brand font can replace the defaults but must cover the same size/weight range
  • Minimum body text: bodyMedium (14sp) — never use sizes below labelSmall (11sp)

Components

Navigation

Pattern When to use
Navigation Bar (bottom) 3–5 primary destinations; always visible
Navigation Rail (side) Tablets and foldables in landscape; medium window
Navigation Drawer (side panel) 5+ destinations; large screens (expanded window)
  • Never mix Navigation Bar and Navigation Drawer on the same screen size
  • Active destination: filled icon + label; inactive: outlined icon + label (no color change alone)
  • Navigation Bar height: 80dp; do not place content behind it without WindowInsets padding

Floating Action Button (FAB)

  • One FAB per screen — represents the single most important action
  • Sizes: FAB (56dp), SmallFAB (40dp), LargeFAB (96dp), ExtendedFAB (label + icon)
  • Use ExtendedFAB as the default for new screens — it is more accessible and communicative
  • Position: bottom-end of the screen, above the Navigation Bar with 16dp margin
  • Do not use FAB for destructive or infrequent actions

Cards

Type Surface Usage
Elevated surface + shadow Default; separates content from background
Filled surfaceVariant Groups related content without strong separation
Outlined surface + outline border When separation is needed without elevation
  • Cards are not buttons — if the entire card is tappable, wrap it in an Card with onClick; ensure the ripple covers the full surface
  • Do not put more than one primary action inside a card — secondary actions go in a trailing icon button or menu

Dialogs

  • Alert dialog: two actions maximum (confirm + cancel); title is optional; never use for multi-step flows
  • Full-screen dialog: for complex inputs that need dedicated space (forms, pickers)
  • Confirm button uses TextButton or FilledButton; Dismiss uses TextButton
  • Never use dialogs for non-critical information — use Snackbar instead

Bottom Sheet

  • Modal: overlays content; user must dismiss before continuing; use for contextual actions
  • Standard: co-exists with main content on large screens; use for supplemental content
  • Minimum peek height: 56dp (enough for a drag handle + one action)
  • Always include a visible drag handle (width: 32dp, height: 4dp, color: onSurfaceVariant)

Chips

Type Usage
Assist Smart suggestions for actions (e.g., "Add to calendar")
Filter Toggle a filter on/off in a list
Input Represent user-entered values (e.g., tags, recipients)
Suggestion Pre-populated options in a text field
  • Chip height: 32dp; min width: 56dp; horizontal padding: 16dp (8dp if leading icon)
  • Do not use chips as navigation — that is Navigation Bar / Drawer territory

Snackbar

  • Duration: 4 seconds (default); extend to 10 seconds only when an action requires user attention
  • One action maximum (UNDO, RETRY) — label ≤ 2 words
  • Position: bottom of screen, above Navigation Bar + FAB
  • Never stack snackbars — show one at a time; queue if multiple are triggered

Text Fields

  • Use Filled text field as default (higher visual weight, easier to scan)
  • Use Outlined when the field needs to stand out against a filled surface
  • Always show a helperText for format constraints (e.g., "MM/DD/YYYY")
  • Error state: error color + error icon + errorText below the field; never only color

Motion

Material motion is meaningful and purposeful — it reinforces hierarchy and guides attention.

Easing Curves

Curve Token Usage
Emphasized FastOutSlowIn Elements entering or exiting the screen
Emphasized decelerate custom Element entering from off-screen
Emphasized accelerate custom Element exiting to off-screen
Standard FastOutSlowIn Elements that stay on screen
Linear — Continuous animations (loaders, progress)

Duration

Category Range Usage
Short 50–200ms Small utility transitions (icon change, color shift)
Medium 200–500ms Standard component transitions (dialog open, expansion)
Long 500ms–1s Large surface transitions (navigation, full-screen)
Extra long > 1s Complex emphasized transitions (rare)

Rules:

  • Never animate color alone — pair with scale, position, or opacity
  • Respect Reduce Motion (Android Accessibility setting) — replace motion with instant state changes
  • Shared element transitions must preserve the visual identity of the element across routes

Adaptive Layout (Window Size Classes)

Material Design 3 defines three breakpoints — design for all three from the start.

Class Width Typical device
Compact < 600dp Phones (portrait)
Medium 600–840dp Tablets (portrait), large phones (landscape), foldables (unfolded)
Expanded ≥ 840dp Tablets (landscape), desktops
UI Element Compact Medium Expanded
Navigation Navigation Bar Navigation Rail Navigation Drawer
FAB FAB / Extended FAB FAB (centered) FAB (top of rail)
Content Single column Two columns Two or three columns
Dialogs Full-screen Alert dialog Alert dialog
  • Never hard-code screen widths — use WindowSizeClass (Jetpack Compose) or equivalent
  • Test all three breakpoints before declaring UI work done

Accessibility

  • Touch targets: minimum 48×48dp for all interactive elements, even when the visual element is smaller (use padding)
  • Content descriptions: every ImageButton, Icon, and decorative image must have a content description or be marked as decorative
  • Focus order: logical left-to-right, top-to-bottom in LTR; verify with TalkBack
  • State communication: selected/checked/disabled states must be communicated via contentDescription or stateDescription, not only color
  • Text resizing: test the UI at 200% font scale — no content must be clipped or overlapping
  • Color independence: never convey meaning with color alone — always pair with icon, label, or pattern