material-design

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

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