What's the difference between MaterialTheme.colors vs MaterialTheme.coloScheme

Question

I am learning Jetpack compose of Android Development.

Sometimes, I use

MaterialTheme.colors MaterialTheme.coloScheme

because one of them shows red.

For example,

Surface(
        color = MaterialTheme.colorScheme.primary,
        modifier = Modifier.padding(vertical = 4.dp, horizontal = 8.dp)
    ) {
        Row(modifier = Modifier.padding(24.dp)) {
            Column(modifier = Modifier
                .weight(1f)
                .padding(bottom = extraPadding)
            ) {
                Text(text = "Hello, ")
                Text(text = name)
            }
            ElevatedButton(
                onClick = { expanded.value = !expanded.value }
            ) {
                Text(if (expanded.value) "Show less" else "Show more")
            }
        }
    }

So, what's the difference and which one is better or how to use them properly?

Answer 1

These are 2 different color selection systems. In material design 2 Color swatches with color between 100, and 900 is used. You can check out swatches in material color picker. M3 uses shades between 0-100 from their new color system HCT.

TL;DR

When you pick Composables suc as Button from Material Design2 colors from M2 are used. When you pick Composables from Material Design3 tokens from M3 are used.

Material Design2

When you select primary 500 and 700, for selecting secondary 200 and 700 variants are used.

When you call androidx.compose.material.MaterialTheme.colors.x

you are getting these colors.

Material Design3

For Material Design 3 they invented a new color system(RGB, HSV, HSL) called HCT(hue-colorfulness-tone). If you are interested in details you can check out this blog. Now, instead of colors with 200 and 900 colors are selected as tones between 0 and 100.

There is util library from google that creates these tones from the color you picked. But there was a bug creating colors last time i checked.

I also built a M2, and M3 color selection library that depends google's library for M3 creation.

Google's theme builder to create M3 colors for Compose

When you pick primary, secondary, teriatry in material builder or any tool, or using default colors by creating M3 project variants of 40-20, etc are created for primary, secondary color roles. You might pick Red but its tone(40) is used for Primary color.

#FF00000 -> #c001000

Color Roles

The primary key color is used to derive roles for key components across the UI, such as the FAB, prominent buttons, active states, as well as the tint of elevated surfaces.

The secondary key color is used for less prominent components in the UI such as filter chips, while expanding the opportunity for color expression.

The tertiary key color is used to derive the roles of contrasting accents that can be used to balance primary and secondary colors or bring heightened attention to an element. The tertiary color role is left for teams to use at their discretion and is intended to support broader color expression in products.

You can check out official m3 page when to use primary, secondary and teriatry colors

Primary

Primary roles are used for key components across the UI, such as the FAB, prominent buttons, active states, as well as the tint of elevated surfaces.

Secondary

Secondary roles are used for less prominent components in the UI, such as filter chips, while expanding the opportunity for color expression.

Tertiary

Tertiary roles are used for contrasting accents that can be used to balance primary and secondary colors or bring heightened attention to an element, such as an input field.

The tertiary color role is left for makers to use at their discretion and is intended to support broader color expression in products.

How are these in code are like this? As in mentioned above Composables pick respective color tokens, Buttons primary to match with your theme's set colors.

internal object FilledButtonTokens {
    val ContainerColor = ColorSchemeKeyTokens.Primary
    val ContainerElevation = ElevationTokens.Level0
    val ContainerHeight = 40.0.dp
    val ContainerShape = ShapeKeyTokens.CornerFull
    val DisabledContainerColor = ColorSchemeKeyTokens.OnSurface
    val DisabledContainerElevation = ElevationTokens.Level0
    const val DisabledContainerOpacity = 0.12f
    val DisabledLabelTextColor = ColorSchemeKeyTokens.OnSurface
    const val DisabledLabelTextOpacity = 0.38f
    val FocusContainerElevation = ElevationTokens.Level0
    val FocusLabelTextColor = ColorSchemeKeyTokens.OnPrimary
    val HoverContainerElevation = ElevationTokens.Level1
    val HoverLabelTextColor = ColorSchemeKeyTokens.OnPrimary
    val LabelTextColor = ColorSchemeKeyTokens.OnPrimary
    val LabelTextFont = TypographyKeyTokens.LabelLarge
    val PressedContainerElevation = ElevationTokens.Level0
    val PressedLabelTextColor = ColorSchemeKeyTokens.OnPrimary
    val DisabledIconColor = ColorSchemeKeyTokens.OnSurface
    const val DisabledIconOpacity = 0.38f
    val FocusIconColor = ColorSchemeKeyTokens.OnPrimary
    val HoverIconColor = ColorSchemeKeyTokens.OnPrimary
    val IconColor = ColorSchemeKeyTokens.OnPrimary
    val IconSize = 18.0.dp
    val PressedIconColor = ColorSchemeKeyTokens.OnPrimary
}

Answer 2

In Material 2 you would use one and in Material 3 the other. For instance:

Material 2:

    Surface(
    color = MaterialTheme.colors.surface,
    contentColor = contentColorFor(color),
    // ...

TopAppBar(
    backgroundColor = MaterialTheme.colors.primarySurface,
    contentColor = contentColorFor(backgroundColor),
    // ...

Material 3:

    Card(
    colors = CardDefaults.cardColors(
        containerColor =
        if (isSelected) MaterialTheme.colorScheme.primaryContainer
        else
            MaterialTheme.colorScheme.surfaceVariant)
) {
    Text(
        text = “Dinner club”,
        style = MaterialTheme.typography.bodyLarge,
        color =
        if (isSelected) MaterialTheme.colorScheme.onPrimaryContainer
        else MaterialTheme.colorScheme.onSurface, ),
        ….
        ….
}