1# Material Design 3 Theming
2 
3## Color System
4 
5### Dynamic Color (Material You)
6 
7```kotlin
8@Composable
9fun AppTheme(
10    darkTheme: Boolean = isSystemInDarkTheme(),
11    dynamicColor: Boolean = true,
12    content: @Composable () -> Unit
13) {
14    val colorScheme = when {
15        dynamicColor && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S -> {
16            val context = LocalContext.current
17            if (darkTheme) dynamicDarkColorScheme(context)
18            else dynamicLightColorScheme(context)
19        }
20        darkTheme -> DarkColorScheme
21        else -> LightColorScheme
22    }
23 
24    MaterialTheme(
25        colorScheme = colorScheme,
26        typography = AppTypography,
27        shapes = AppShapes,
28        content = content
29    )
30}
31```
32 
33### Custom Color Scheme
34 
35```kotlin
36// Define color palette
37val md_theme_light_primary = Color(0xFF6750A4)
38val md_theme_light_onPrimary = Color(0xFFFFFFFF)
39val md_theme_light_primaryContainer = Color(0xFFEADDFF)
40val md_theme_light_onPrimaryContainer = Color(0xFF21005D)
41val md_theme_light_secondary = Color(0xFF625B71)
42val md_theme_light_onSecondary = Color(0xFFFFFFFF)
43val md_theme_light_secondaryContainer = Color(0xFFE8DEF8)
44val md_theme_light_onSecondaryContainer = Color(0xFF1D192B)
45val md_theme_light_tertiary = Color(0xFF7D5260)
46val md_theme_light_onTertiary = Color(0xFFFFFFFF)
47val md_theme_light_tertiaryContainer = Color(0xFFFFD8E4)
48val md_theme_light_onTertiaryContainer = Color(0xFF31111D)
49val md_theme_light_error = Color(0xFFB3261E)
50val md_theme_light_onError = Color(0xFFFFFFFF)
51val md_theme_light_errorContainer = Color(0xFFF9DEDC)
52val md_theme_light_onErrorContainer = Color(0xFF410E0B)
53val md_theme_light_background = Color(0xFFFFFBFE)
54val md_theme_light_onBackground = Color(0xFF1C1B1F)
55val md_theme_light_surface = Color(0xFFFFFBFE)
56val md_theme_light_onSurface = Color(0xFF1C1B1F)
57val md_theme_light_surfaceVariant = Color(0xFFE7E0EC)
58val md_theme_light_onSurfaceVariant = Color(0xFF49454F)
59val md_theme_light_outline = Color(0xFF79747E)
60val md_theme_light_outlineVariant = Color(0xFFCAC4D0)
61 
62val LightColorScheme = lightColorScheme(
63    primary = md_theme_light_primary,
64    onPrimary = md_theme_light_onPrimary,
65    primaryContainer = md_theme_light_primaryContainer,
66    onPrimaryContainer = md_theme_light_onPrimaryContainer,
67    secondary = md_theme_light_secondary,
68    onSecondary = md_theme_light_onSecondary,
69    secondaryContainer = md_theme_light_secondaryContainer,
70    onSecondaryContainer = md_theme_light_onSecondaryContainer,
71    tertiary = md_theme_light_tertiary,
72    onTertiary = md_theme_light_onTertiary,
73    tertiaryContainer = md_theme_light_tertiaryContainer,
74    onTertiaryContainer = md_theme_light_onTertiaryContainer,
75    error = md_theme_light_error,
76    onError = md_theme_light_onError,
77    errorContainer = md_theme_light_errorContainer,
78    onErrorContainer = md_theme_light_onErrorContainer,
79    background = md_theme_light_background,
80    onBackground = md_theme_light_onBackground,
81    surface = md_theme_light_surface,
82    onSurface = md_theme_light_onSurface,
83    surfaceVariant = md_theme_light_surfaceVariant,
84    onSurfaceVariant = md_theme_light_onSurfaceVariant,
85    outline = md_theme_light_outline,
86    outlineVariant = md_theme_light_outlineVariant
87)
88 
89// Dark colors follow the same pattern
90val DarkColorScheme = darkColorScheme(
91    primary = md_theme_dark_primary,
92    // ... other colors
93)
94```
95 
96### Color Roles Usage
97 
98```kotlin
99@Composable
100fun ColorRolesExample() {
101    Column(
102        modifier = Modifier.padding(16.dp),
103        verticalArrangement = Arrangement.spacedBy(16.dp)
104    ) {
105        // Primary - Key actions, FABs
106        Button(onClick = { }) {
107            Text("Primary Action")
108        }
109 
110        // Primary Container - Less prominent containers
111        Surface(
112            color = MaterialTheme.colorScheme.primaryContainer,
113            shape = RoundedCornerShape(12.dp)
114        ) {
115            Text(
116                "Primary Container",
117                modifier = Modifier.padding(16.dp),
118                color = MaterialTheme.colorScheme.onPrimaryContainer
119            )
120        }
121 
122        // Secondary - Less prominent actions
123        FilledTonalButton(onClick = { }) {
124            Text("Secondary Action")
125        }
126 
127        // Tertiary - Contrast accents
128        Badge(
129            containerColor = MaterialTheme.colorScheme.tertiaryContainer,
130            contentColor = MaterialTheme.colorScheme.onTertiaryContainer
131        ) {
132            Text("New")
133        }
134 
135        // Error - Destructive actions
136        Button(
137            onClick = { },
138            colors = ButtonDefaults.buttonColors(
139                containerColor = MaterialTheme.colorScheme.error
140            )
141        ) {
142            Text("Delete")
143        }
144 
145        // Surface variants
146        Surface(
147            color = MaterialTheme.colorScheme.surfaceVariant,
148            shape = RoundedCornerShape(8.dp)
149        ) {
150            Text(
151                "Surface Variant",
152                modifier = Modifier.padding(16.dp),
153                color = MaterialTheme.colorScheme.onSurfaceVariant
154            )
155        }
156    }
157}
158```
159 
160### Extended Colors
161 
162```kotlin
163// Custom semantic colors beyond M3 defaults
164data class ExtendedColors(
165    val success: Color,
166    val onSuccess: Color,
167    val successContainer: Color,
168    val onSuccessContainer: Color,
169    val warning: Color,
170    val onWarning: Color,
171    val warningContainer: Color,
172    val onWarningContainer: Color
173)
174 
175val LocalExtendedColors = staticCompositionLocalOf {
176    ExtendedColors(
177        success = Color(0xFF4CAF50),
178        onSuccess = Color.White,
179        successContainer = Color(0xFFE8F5E9),
180        onSuccessContainer = Color(0xFF1B5E20),
181        warning = Color(0xFFFF9800),
182        onWarning = Color.White,
183        warningContainer = Color(0xFFFFF3E0),
184        onWarningContainer = Color(0xFFE65100)
185    )
186}
187 
188@Composable
189fun AppTheme(
190    content: @Composable () -> Unit
191) {
192    val extendedColors = ExtendedColors(
193        // ... define colors based on light/dark theme
194    )
195 
196    CompositionLocalProvider(
197        LocalExtendedColors provides extendedColors
198    ) {
199        MaterialTheme(
200            colorScheme = colorScheme,
201            content = content
202        )
203    }
204}
205 
206// Usage
207@Composable
208fun SuccessBanner() {
209    val extendedColors = LocalExtendedColors.current
210 
211    Surface(
212        color = extendedColors.successContainer,
213        shape = RoundedCornerShape(8.dp)
214    ) {
215        Row(
216            modifier = Modifier.padding(16.dp),
217            horizontalArrangement = Arrangement.spacedBy(12.dp)
218        ) {
219            Icon(
220                Icons.Default.CheckCircle,
221                contentDescription = null,
222                tint = extendedColors.success
223            )
224            Text(
225                "Operation successful!",
226                color = extendedColors.onSuccessContainer
227            )
228        }
229    }
230}
231```
232 
233## Typography
234 
235### Material 3 Type Scale
236 
237```kotlin
238val AppTypography = Typography(
239    // Display styles - Hero text, large numerals
240    displayLarge = TextStyle(
241        fontFamily = FontFamily.Default,
242        fontWeight = FontWeight.Normal,
243        fontSize = 57.sp,
244        lineHeight = 64.sp,
245        letterSpacing = (-0.25).sp
246    ),
247    displayMedium = TextStyle(
248        fontFamily = FontFamily.Default,
249        fontWeight = FontWeight.Normal,
250        fontSize = 45.sp,
251        lineHeight = 52.sp,
252        letterSpacing = 0.sp
253    ),
254    displaySmall = TextStyle(
255        fontFamily = FontFamily.Default,
256        fontWeight = FontWeight.Normal,
257        fontSize = 36.sp,
258        lineHeight = 44.sp,
259        letterSpacing = 0.sp
260    ),
261 
262    // Headline styles - High emphasis, short text
263    headlineLarge = TextStyle(
264        fontFamily = FontFamily.Default,
265        fontWeight = FontWeight.Normal,
266        fontSize = 32.sp,
267        lineHeight = 40.sp,
268        letterSpacing = 0.sp
269    ),
270    headlineMedium = TextStyle(
271        fontFamily = FontFamily.Default,
272        fontWeight = FontWeight.Normal,
273        fontSize = 28.sp,
274        lineHeight = 36.sp,
275        letterSpacing = 0.sp
276    ),
277    headlineSmall = TextStyle(
278        fontFamily = FontFamily.Default,
279        fontWeight = FontWeight.Normal,
280        fontSize = 24.sp,
281        lineHeight = 32.sp,
282        letterSpacing = 0.sp
283    ),
284 
285    // Title styles - Medium emphasis headers
286    titleLarge = TextStyle(
287        fontFamily = FontFamily.Default,
288        fontWeight = FontWeight.Normal,
289        fontSize = 22.sp,
290        lineHeight = 28.sp,
291        letterSpacing = 0.sp
292    ),
293    titleMedium = TextStyle(
294        fontFamily = FontFamily.Default,
295        fontWeight = FontWeight.Medium,
296        fontSize = 16.sp,
297        lineHeight = 24.sp,
298        letterSpacing = 0.15.sp
299    ),
300    titleSmall = TextStyle(
301        fontFamily = FontFamily.Default,
302        fontWeight = FontWeight.Medium,
303        fontSize = 14.sp,
304        lineHeight = 20.sp,
305        letterSpacing = 0.1.sp
306    ),
307 
308    // Body styles - Long-form text
309    bodyLarge = TextStyle(
310        fontFamily = FontFamily.Default,
311        fontWeight = FontWeight.Normal,
312        fontSize = 16.sp,
313        lineHeight = 24.sp,
314        letterSpacing = 0.5.sp
315    ),
316    bodyMedium = TextStyle(
317        fontFamily = FontFamily.Default,
318        fontWeight = FontWeight.Normal,
319        fontSize = 14.sp,
320        lineHeight = 20.sp,
321        letterSpacing = 0.25.sp
322    ),
323    bodySmall = TextStyle(
324        fontFamily = FontFamily.Default,
325        fontWeight = FontWeight.Normal,
326        fontSize = 12.sp,
327        lineHeight = 16.sp,
328        letterSpacing = 0.4.sp
329    ),
330 
331    // Label styles - Buttons, chips, navigation
332    labelLarge = TextStyle(
333        fontFamily = FontFamily.Default,
334        fontWeight = FontWeight.Medium,
335        fontSize = 14.sp,
336        lineHeight = 20.sp,
337        letterSpacing = 0.1.sp
338    ),
339    labelMedium = TextStyle(
340        fontFamily = FontFamily.Default,
341        fontWeight = FontWeight.Medium,
342        fontSize = 12.sp,
343        lineHeight = 16.sp,
344        letterSpacing = 0.5.sp
345    ),
346    labelSmall = TextStyle(
347        fontFamily = FontFamily.Default,
348        fontWeight = FontWeight.Medium,
349        fontSize = 11.sp,
350        lineHeight = 16.sp,
351        letterSpacing = 0.5.sp
352    )
353)
354```
355 
356### Custom Fonts
357 
358```kotlin
359// Load custom fonts
360val Inter = FontFamily(
361    Font(R.font.inter_regular, FontWeight.Normal),
362    Font(R.font.inter_medium, FontWeight.Medium),
363    Font(R.font.inter_semibold, FontWeight.SemiBold),
364    Font(R.font.inter_bold, FontWeight.Bold)
365)
366 
367val AppTypography = Typography(
368    displayLarge = TextStyle(
369        fontFamily = Inter,
370        fontWeight = FontWeight.Normal,
371        fontSize = 57.sp,
372        lineHeight = 64.sp
373    ),
374    // Apply to all styles...
375)
376 
377// Variable fonts (Android 12+)
378val InterVariable = FontFamily(
379    Font(
380        R.font.inter_variable,
381        variationSettings = FontVariation.Settings(
382            FontVariation.weight(400)
383        )
384    )
385)
386```
387 
388## Shape System
389 
390### Material 3 Shapes
391 
392```kotlin
393val AppShapes = Shapes(
394    // Extra small - Chips, small buttons
395    extraSmall = RoundedCornerShape(4.dp),
396 
397    // Small - Text fields, small cards
398    small = RoundedCornerShape(8.dp),
399 
400    // Medium - Cards, dialogs
401    medium = RoundedCornerShape(12.dp),
402 
403    // Large - Large cards, bottom sheets
404    large = RoundedCornerShape(16.dp),
405 
406    // Extra large - Full-screen dialogs
407    extraLarge = RoundedCornerShape(28.dp)
408)
409```
410 
411### Custom Shape Usage
412 
413```kotlin
414@Composable
415fun ShapedComponents() {
416    Column(
417        verticalArrangement = Arrangement.spacedBy(16.dp)
418    ) {
419        // Small shape for text field
420        OutlinedTextField(
421            value = "",
422            onValueChange = {},
423            shape = MaterialTheme.shapes.small,
424            label = { Text("Input") }
425        )
426 
427        // Medium shape for cards
428        Card(
429            shape = MaterialTheme.shapes.medium
430        ) {
431            Text("Card content", modifier = Modifier.padding(16.dp))
432        }
433 
434        // Large shape for prominent containers
435        Surface(
436            shape = MaterialTheme.shapes.large,
437            color = MaterialTheme.colorScheme.primaryContainer
438        ) {
439            Text("Featured", modifier = Modifier.padding(24.dp))
440        }
441 
442        // Custom asymmetric shape
443        Surface(
444            shape = RoundedCornerShape(
445                topStart = 24.dp,
446                topEnd = 24.dp,
447                bottomStart = 0.dp,
448                bottomEnd = 0.dp
449            ),
450            color = MaterialTheme.colorScheme.surface
451        ) {
452            Text("Bottom sheet style", modifier = Modifier.padding(16.dp))
453        }
454    }
455}
456```
457 
458## Elevation and Shadows
459 
460### Tonal Elevation
461 
462```kotlin
463@Composable
464fun ElevationExample() {
465    Column(
466        verticalArrangement = Arrangement.spacedBy(16.dp)
467    ) {
468        // Level 0 - No elevation
469        Surface(
470            tonalElevation = 0.dp,
471            shadowElevation = 0.dp
472        ) {
473            Text("Level 0", modifier = Modifier.padding(16.dp))
474        }
475 
476        // Level 1 - Low emphasis surfaces
477        Surface(
478            tonalElevation = 1.dp,
479            shadowElevation = 1.dp
480        ) {
481            Text("Level 1", modifier = Modifier.padding(16.dp))
482        }
483 
484        // Level 2 - Cards, switches
485        Surface(
486            tonalElevation = 3.dp,
487            shadowElevation = 2.dp
488        ) {
489            Text("Level 2", modifier = Modifier.padding(16.dp))
490        }
491 
492        // Level 3 - Navigation components
493        Surface(
494            tonalElevation = 6.dp,
495            shadowElevation = 4.dp
496        ) {
497            Text("Level 3", modifier = Modifier.padding(16.dp))
498        }
499 
500        // Level 4 - Navigation rail
501        Surface(
502            tonalElevation = 8.dp,
503            shadowElevation = 6.dp
504        ) {
505            Text("Level 4", modifier = Modifier.padding(16.dp))
506        }
507 
508        // Level 5 - FAB
509        Surface(
510            tonalElevation = 12.dp,
511            shadowElevation = 8.dp
512        ) {
513            Text("Level 5", modifier = Modifier.padding(16.dp))
514        }
515    }
516}
517```
518 
519## Responsive Design
520 
521### Window Size Classes
522 
523```kotlin
524@Composable
525fun AdaptiveLayout() {
526    val windowSizeClass = calculateWindowSizeClass(LocalContext.current as Activity)
527 
528    when (windowSizeClass.widthSizeClass) {
529        WindowWidthSizeClass.Compact -> {
530            // Phone portrait - Single column, bottom nav
531            CompactLayout()
532        }
533        WindowWidthSizeClass.Medium -> {
534            // Tablet portrait, phone landscape - Navigation rail
535            MediumLayout()
536        }
537        WindowWidthSizeClass.Expanded -> {
538            // Tablet landscape, desktop - Navigation drawer, multi-pane
539            ExpandedLayout()
540        }
541    }
542}
543 
544@Composable
545fun CompactLayout() {
546    Scaffold(
547        bottomBar = { NavigationBar { /* items */ } }
548    ) { padding ->
549        Content(modifier = Modifier.padding(padding))
550    }
551}
552 
553@Composable
554fun MediumLayout() {
555    Row {
556        NavigationRail { /* items */ }
557        Content(modifier = Modifier.weight(1f))
558    }
559}
560 
561@Composable
562fun ExpandedLayout() {
563    PermanentNavigationDrawer(
564        drawerContent = {
565            PermanentDrawerSheet { /* items */ }
566        }
567    ) {
568        Row {
569            ListPane(modifier = Modifier.weight(0.4f))
570            DetailPane(modifier = Modifier.weight(0.6f))
571        }
572    }
573}
574```
575 
576### Foldable Support
577 
578```kotlin
579@Composable
580fun FoldableAwareLayout() {
581    val foldingFeature = LocalFoldingFeature.current
582 
583    when {
584        foldingFeature?.state == FoldingFeature.State.HALF_OPENED -> {
585            // Device is half-folded (tabletop mode)
586            TwoHingeLayout(
587                top = { CameraPreview() },
588                bottom = { CameraControls() }
589            )
590        }
591        foldingFeature?.orientation == FoldingFeature.Orientation.VERTICAL -> {
592            // Vertical fold (book mode)
593            TwoPaneLayout(
594                first = { NavigationPane() },
595                second = { ContentPane() }
596            )
597        }
598        else -> {
599            // Regular or fully opened
600            SinglePaneLayout()
601        }
602    }
603}
604```
605