Material 3 theming

What is a design system?

A design system is a set of rules and ready components that make an app look consistent: which colours mean what, which font sizes to use, how rounded corners are. Material Design is Google's design system; version 3 (also called Material You) is the current one, and Compose's material3 library implements it.

The theme

private val LightColors = lightColorScheme(
    primary = Color(0xFF00695C),          // brand teal
    secondary = Color(0xFFFF8F00),        // saffron accent
)
private val DarkColors = darkColorScheme(
    primary = Color(0xFF4DB6AC),
    secondary = Color(0xFFFFB74D),
)

@Composable
fun ShopTheme(darkTheme: Boolean = isSystemInDarkTheme(), content: @Composable () -> Unit) {
    MaterialTheme(
        colorScheme = if (darkTheme) DarkColors else LightColors,
        typography = Typography(),        // default Material 3 type scale
        content = content,
    )
}

A colour scheme is more than a few colours. Material 3 defines roles: primary, onPrimary (text on primary), primaryContainer, secondary, surface, onSurface, error and more. Components pick the right role automatically, so a Button uses primary with onPrimary text, and a Card uses a surface colour.

Use roles, not raw colours

// Good: follows the theme, works in dark mode
Text("Rs 499", color = MaterialTheme.colorScheme.primary)
Surface(color = MaterialTheme.colorScheme.secondaryContainer) { Text("Offer") }

// Avoid: breaks dark mode and rebranding
Text("Rs 499", color = Color(0xFF00695C))

Dark mode is not just "invert the colours". Material 3 dark schemes use dark grey surfaces rather than pure black, and lighter versions of your brand colours so they stay readable. Define both schemes from the start; adding dark mode later to an app full of hard-coded colours is painful.

Typography and shapes

The type scale has roles like displayLarge, headlineMedium, titleLarge, bodyMedium and labelSmall. Use them through MaterialTheme.typography.titleLarge instead of picking font sizes by hand. Shapes (small, medium, large corner styles) work the same way through MaterialTheme.shapes. You can load your own fonts (for example a font with good Devanagari support) into the Typography.

Dynamic colour

On Android 12 (API 31) and later, the system can generate a colour scheme from the user's wallpaper. Apps can opt in, so they feel part of the user's phone. Many brands keep their own colours instead; it is a product choice.

val colorScheme = when {
    Build.VERSION.SDK_INT >= Build.VERSION_CODES.S ->
        if (darkTheme) dynamicDarkColorScheme(context) else dynamicLightColorScheme(context)
    darkTheme -> DarkColors
    else -> LightColors
}

Building a scheme

Picking a full, accessible set of colour roles by hand is hard. The Material Theme Builder (linked from m3.material.io) generates light and dark schemes from one brand colour and exports Compose code.

Common mistakes

• Hard-coded colours scattered through screens: dark mode looks broken.
• Low contrast text, such as light grey on white, which is hard to read outdoors in sunlight. Use on-colours (onSurface, onPrimary).
• Forgetting to wrap previews in your theme, so previews look different from the app.
• Mixing material (Material 2) and material3 components in one screen.