Material3 Design System

Material Design 3 — KMP / Compose Multiplatform Skill

This skill guides implementation of Google's Material Design 3 (MD3 / Material You) using Jetpack Compose and Compose Multiplatform for KMP projects (Android + Desktop).

Attribution: This skill is adapted from and gives credit to hamen/material-3-skill by Hamen. The original skill covers web and Flutter targets. This KMP edition strips all web/CSS/Flutter patterns and replaces them with pure Compose Multiplatform APIs, adds the audit report system, and extends the reference set for adaptive layout, navigation, and versioning.

Scope: Compose-only. All examples use androidx.compose.material3 APIs — the same API surface is available in KMP commonMain via org.jetbrains.compose.material3:material3 (declared explicitly in libs.versions.toml). No web CSS, no @material/web elements, no Flutter.

MD3 Philosophy

Google I/O 2026 Key Updates

• Compose-first on Android: For all new Android work, use androidx.compose.material3.
• Expressive layout scaffold: Design screens to adapt across mobile, desktop, foldables. Use Material3Adaptive scaffold APIs.
• 8dp spacing system: Define spacing as tokens — never scatter raw Dp literals.
• New expressive components: Lists, menus, search, and search app bars have refreshed expressive guidance; check your Material3 BOM for expressive variants.

Design Token System

All MD3 values come through MaterialTheme. Never hardcode raw values inline.

Decision Tree

What are you building?

Full app scaffold        → AppTheme setup + references/theming-and-dynamic-color.md
Single component         → references/component-catalog.md
Custom color theme       → references/color-system.md
Typography / fonts       → references/typography-and-shape.md
Navigation structure     → references/navigation-patterns.md
Adaptive layout          → references/layout-and-responsive.md

Color Token Summary

Full details in references/color-system.md.

Key Roles (Compose token → usage)

Typography Token Summary

Full details in references/typography-and-shape.md.

// ✅ Always via MaterialTheme
Text("Title", style = MaterialTheme.typography.titleLarge)
Text("Body", style = MaterialTheme.typography.bodyMedium)

// ❌ Never inline
Text("Title", fontSize = 22.sp, fontWeight = FontWeight.Normal)

Shape Token Summary

Elevation

MD3 communicates depth through tonal surface color, not drop shadows.

// Cards respect tonal elevation automatically via surfaceTonalElevation
ElevatedCard(elevation = CardDefaults.elevatedCardElevation(defaultElevation = 6.dp)) { }

Motion Summary

Full details in references/typography-and-shape.md §Motion.

Standard Durations

Component Quick Reference

Full Compose API + examples: references/component-catalog.md

AppTheme Setup (Quick Start)

@Composable
fun AppTheme(
    darkTheme: Boolean = isSystemInDarkTheme(),
    // Dynamic color is Android 12+ only — always falls back to static on Desktop
    dynamicColor: Boolean = true,
    content: @Composable () -> Unit
) {
    val colorScheme = when {
        dynamicColor && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S -> {
            val context = LocalContext.current
            if (darkTheme) dynamicDarkColorScheme(context) else dynamicLightColorScheme(context)
        }
        darkTheme -> DarkColorScheme
        else      -> LightColorScheme
    }

    MaterialTheme(
        colorScheme = colorScheme,
        typography  = AppTypography,
        shapes      = AppShapes,
        content     = content
    )
}

For Compose Multiplatform Desktop: Remove Build.VERSION_SDK_INT check and always use LightColorScheme / DarkColorScheme. Dynamic color has no JVM equivalent.

Full theming guide: references/theming-and-dynamic-color.md

Core Rules

• Never hardcode Color(0xFF...) in composables — always MaterialTheme.colorScheme.*
• Never inline fontSize, fontFamily, fontWeight — always MaterialTheme.typography.*
• Never inline RoundedCornerShape(12.dp) — always MaterialTheme.shapes.*
• Always wrap content in AppTheme at the root — never in individual screens
• Always support dark mode — test every screen with isSystemInDarkTheme()
• Always use Scaffold — it handles topBar, bottomBar, FAB, snackbarHost, padding
• Minimum touch target: 48×48dp for all interactive elements
• Spacing tokens: always multiples of 4dp — define a Dimens object
• For Desktop/JVM: always use static color schemes — no dynamic color API on JVM

MD3 Compliance Audit

When the user asks for an audit, a compliance check, or passes code / a screen name with the audit argument, run a full MD3 compliance report using the template below.

How to trigger

audit [screen name or paste code here]
audit HomeScreen
audit <paste composable code>
check this screen against material 3
run md3 audit

Audit Process

1. Scan the target — read the provided code or ask the user to paste the composable(s) to audit.
2. Check each category below in order.
3. Output the report using the exact format specified.
4. Offer fixes — for every ❌ or ⚠️, provide the corrected Compose code snippet inline.

Audit Report Format

Output the report in this exact structure:

╔══════════════════════════════════════════════════════════╗
║          MD3 COMPLIANCE AUDIT — [Screen/File Name]       ║
║          KMP / Compose Multiplatform Edition             ║
╚══════════════════════════════════════════════════════════╝

Score: [X / 10]   Grade: [A / B / C / D / F]

┌─────────────────────────────────────────────────────────┐
│ CATEGORY RESULTS                                        │
└─────────────────────────────────────────────────────────┘

[✅ / ⚠️ / ❌]  COLOR SYSTEM          [PASS / WARN / FAIL]
[✅ / ⚠️ / ❌]  TYPOGRAPHY            [PASS / WARN / FAIL]
[✅ / ⚠️ / ❌]  SHAPE                 [PASS / WARN / FAIL]
[✅ / ⚠️ / ❌]  SPACING               [PASS / WARN / FAIL]
[✅ / ⚠️ / ❌]  ELEVATION             [PASS / WARN / FAIL]
[✅ / ⚠️ / ❌]  COMPONENTS            [PASS / WARN / FAIL]
[✅ / ⚠️ / ❌]  LAYOUT & ADAPTIVE     [PASS / WARN / FAIL]
[✅ / ⚠️ / ❌]  NAVIGATION            [PASS / WARN / FAIL]
[✅ / ⚠️ / ❌]  MOTION & ANIMATION    [PASS / WARN / FAIL]
[✅ / ⚠️ / ❌]  DARK MODE             [PASS / WARN / FAIL]
[✅ / ⚠️ / ❌]  ACCESSIBILITY         [PASS / WARN / FAIL]
[✅ / ⚠️ / ❌]  THEMING SETUP         [PASS / WARN / FAIL]

┌─────────────────────────────────────────────────────────┐
│ FINDINGS                                                │
└─────────────────────────────────────────────────────────┘

[findings listed per category — see check rules below]

┌─────────────────────────────────────────────────────────┐
│ FIXES                                                   │
└─────────────────────────────────────────────────────────┘

[corrected code snippets for every ❌ and ⚠️]

Audit Check Rules — Per Category

1. COLOR SYSTEM

2. TYPOGRAPHY

3. SHAPE

4. SPACING

5. ELEVATION

6. COMPONENTS

7. LAYOUT & ADAPTIVE

8. NAVIGATION

9. MOTION & ANIMATION

10. DARK MODE

11. ACCESSIBILITY

12. THEMING SETUP

Scoring

Each category scores 1 point: ✅ PASS = 1pt, ⚠️ WARN = 0.5pt, ❌ FAIL = 0pt. Round to nearest 0.5.

Reference Files

Dependencies

⚠️ Deprecation: plugin accessor shorthands

The compose.material3, compose.ui, compose.foundation shorthand accessors previously provided by the Compose Multiplatform Gradle plugin are deprecated as of CMP 1.10.0-beta01.

⚠️ Breaking: material-icons-core is no longer transitive (since CMP 1.8.2)

Starting with CMP 1.8.2, the implicit dependency on material-icons-core was removed. If your project uses Icons.Default.* or any Material icon, add it explicitly.

gradle/libs.versions.toml

[versions]
kotlin               = "2.1.21"
agp                  = "8.10.0"
composeMultiplatform = "1.8.2"   # org.jetbrains.compose plugin version
coroutines           = "1.10.2"
lifecycle            = "2.9.0"

[libraries]
# ✅ Correct module for commonMain
# The CMP plugin maps this → androidx.compose.material3 on Android automatically
compose-material3          = { module = "org.jetbrains.compose.material3:material3",            version.ref = "composeMultiplatform" }
compose-runtime            = { module = "org.jetbrains.compose.runtime:runtime",                version.ref = "composeMultiplatform" }
compose-foundation         = { module = "org.jetbrains.compose.foundation:foundation",          version.ref = "composeMultiplatform" }
compose-ui                 = { module = "org.jetbrains.compose.ui:ui",                          version.ref = "composeMultiplatform" }
# Declare explicitly — no longer a transitive dep since CMP 1.8.2
compose-material-icons-core = { module = "org.jetbrains.compose.material:material-icons-core", version.ref = "composeMultiplatform" }
compose-ui-tooling-preview  = { module = "org.jetbrains.compose.ui:ui-tooling-preview",        version.ref = "composeMultiplatform" }

[plugins]
kotlinMultiplatform  = { id = "org.jetbrains.kotlin.multiplatform",       version.ref = "kotlin" }
androidApplication   = { id = "com.android.application",                  version.ref = "agp" }
composeMultiplatform = { id = "org.jetbrains.compose",                    version.ref = "composeMultiplatform" }
composeCompiler      = { id = "org.jetbrains.kotlin.plugin.compose",      version.ref = "kotlin" }

composeApp/build.gradle.kts

kotlin {
    sourceSets {
        commonMain.dependencies {
            // ✅ Use libs.* — NOT the deprecated compose.* plugin accessors
            implementation(libs.compose.runtime)
            implementation(libs.compose.foundation)
            implementation(libs.compose.ui)
            implementation(libs.compose.material3)
            implementation(libs.compose.material.icons.core)  // explicit since CMP 1.8.2
        }
        androidMain.dependencies {
            implementation(libs.compose.ui.tooling.preview)
        }
    }
}

Module mapping (how it works)

You never need to manually switch to androidx.compose.material3 in build files — the CMP Gradle plugin metadata handles the platform mapping transparently.

Official Docs

• Material 3
• Compose Material 3
• M3 Theme Builder
• Compose Multiplatform
• Material3 Adaptive
• CMP Release Notes