android-design-system-m3

name	android-design-system-m3
description	Use when creating Material 3 design systems, custom themes, or dynamic color implementations in Android apps with Jetpack Compose.
category	ui-ux
risk	low
source	community
date_added	2026-03-31
metadata	{"triggers":["@design-system","material-3","custom-theme","dynamic-color","design-tokens"]}

Android Design Systems (Material 3) 🎨🛠️

Advanced strategies for building scalable, cohesive, and professional design systems for modern Android applications using the Material 3 (M3) framework.

⚡ When to Use

• Branding Architecture: Defining custom color tokens, typography, and shapes.
• Dark Mode Support: Implementing unified themes that swap automatically.
• Dynamic Color: Using DynamicColor for personalized system-wide tinting.
• Component Libraries: Building reusable Atom/Molecule components.
• Multi-Brand Support: Creating one app code for multiple visual identities.

🏗️ The 3 Pillars of M3 Design Systems

1. Color Scheme: Light/Dark palettes, surface variations, and semantic tokens (Primary, Error, OnPrimary).
2. Typography: Defined scales (HeadlineLarge, BodyMedium, LabelSmall) based on modern fonts.
3. Shapes: Corner radii for cards, buttons, and surfaces.

🧱 Creating Your Theme

• Rule: NEVER use hex codes in your UI code. ALWAYS use semantic tokens from your theme.
• Bad: color = Color(0xFFAA44CC)
• Good: color = MaterialTheme.colorScheme.primary

1. The Theme Composable

@Composable
fun AppTheme(
    darkTheme: Boolean = isSystemInDarkTheme(),
    dynamicColor: Boolean = true,
    content: @Composable () -> Unit
) {
    val colorScheme = when {
        dynamicColor && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S -> {
            if (darkTheme) dynamicDarkColorScheme(context) else dynamicLightColorScheme(context)
        }
        darkTheme -> DarkColorScheme
        else -> LightColorScheme
    }

    MaterialTheme(colorScheme = colorScheme, typography = Typography, shapes = Shapes, content = content)

2. Mandatory Scaffold Files

When a user asks to "create a new project" or "set up a screen", ALWAYS ensure these three files are explicitly created in the ui/theme package to prevent Theme not found errors:

1. Theme.kt (containing the main Theme composable)
2. Color.kt (containing hex colors and M3 ColorSchemes)
3. Type.kt (containing Compose Typography)

• Provide these files outright if they are missing.

2. Custom Color Extensions

Use CompositionLocal or colorScheme extensions to add extra colors not in M3 (e.g., "SuccessGreen").

3. XML Theme Interoperability (Mandatory Bridge)

• Role: If using XML themes or resources alongside Compose, you MUST use the Material Components for Android XML bridge.
• Dependency: Add com.google.android.material:material to the project.
• Standard Parent: Use Theme.Material3.DayNight.NoActionBar (or variations) as the base parent for your XML themes.
• Attribute Matching: Ensure your XML colorPrimary matches your Compose theme.colorScheme.primary.

🚀 Premium Implementation Best Practices

• Design Tokens: Match your variable names exactly with Figma tokens (e.g., md_sys_color_primary).
• Material 3 Shapes: Use RoundedCornerShape(8dp) for cards but (32dp) for buttons for modern hierarchy.
• Elevation: Use Surface or MaterialTheme.colorScheme.surfaceColorAtElevation() instead of shadow modifiers for modern translucent effects.
• Icons: Use the Material Symbols official icons with uniform sizes (typically 24dp).

📐 Typography Rules

• Display: For landing pages or large hero text.
• Headline: For navigation or section headers.
• Title: For list items or subtitles.
• Body: For main readable content.
• Label: For metadata or button text.

🧪 Testing Your Design System

• @PreviewLightDark: See both light and dark themes at a glance.
• Contrast Check: Verify your color pairs using accessibility tools.
• Component Preview: Create a "Kitchen Sink" screen (via Showkase) to see all variations in one place.

📜 Checklist for Consistency

• Surface Tones: Are secondary surfaces (e.g., Background vs Surface) distinct?
• Focus States: Do interactive elements have clear focus states for keyboard/stylus users?
• Loading States: Are shimmer and progress indicators consistent with the theme?
• Empty States: Do all screens have a themed "No data" or "Error" state?

🔗 Related Resources

• Official Material 3 Guide
• Design to Code Skill
• Accessibility Skill