Why FlexSurfaceMode.highScaffoldLowSurface and FlexSurfaceMode.highScaffoldLowSurfaces?

[sgehrman]

Are they the same?

highScaffoldLowSurface
highScaffoldLowSurfaces

[rydmike]

Yes this is a correct observation. In version 8 and later they are the same.

      // Result: Surfaces (1/2x) Scaffold (3x)
      case FlexSurfaceMode.highScaffoldLowSurface:
        return FlexAlphaValues(
          primaryAlpha: blendLevel,
          primaryContainerAlpha: blendLevel * 2,
          secondaryAlpha: blendLevel,
          secondaryContainerAlpha: blendLevel * 2,
          tertiaryAlpha: blendLevel,
          tertiaryContainerAlpha: blendLevel * 2,
          errorAlpha: blendLevel,
          errorContainerAlpha: blendLevel * 2,
          surfaceAlpha: blendLevel ~/ 2,
          inverseSurfaceAlpha: blendLevel ~/ 2,
          dialogAlpha: blendLevel ~/ 2,
          scaffoldAlpha: blendLevel * 3,
        );

and

      // Result: Surfaces (1/2x) Scaffold (3x)
      case FlexSurfaceMode.highScaffoldLowSurfaces:
      case FlexSurfaceMode.highScaffoldLowSurfacesVariantDialog:
        return FlexAlphaValues(
          primaryAlpha: blendLevel,
          primaryContainerAlpha: blendLevel * 2,
          secondaryAlpha: blendLevel,
          secondaryContainerAlpha: blendLevel * 2,
          tertiaryAlpha: blendLevel,
          tertiaryContainerAlpha: blendLevel * 2,
          errorAlpha: blendLevel,
          errorContainerAlpha: blendLevel * 2,
          surfaceAlpha: blendLevel ~/ 2,
          inverseSurfaceAlpha: blendLevel ~/ 2,
          dialogAlpha: blendLevel ~/ 2,
          scaffoldAlpha: blendLevel * 3,
        );

This is because Flutter 3.22 removed the ColorScheme.background color, so I had to do the same in V8, but I did not want to remove past enums as that would have been very breaking.

When background existed these choices used to be different, so that in highScaffoldLowSurfaces both surface and background colors were at blendLevel ~/ 2 whereas in highScaffoldLowSurface the surface color was at blendLevel ~/ 2 and background was at blendLevel * 3 ~/ 2.

With the introduction of all the new surface colors, you do however have even more options for different surface color shades and tints to use on components and background. You just have to change default selections in component themes.

Before Flutter 3.22 there was no hard definition in the design standard what the shade relations between surface, background, scalffoldBackgroundColor and dialogBackgroundColor should be. So you could define those relationships as you wanted to. The FlexSurfaceModewas something I created to allow you to do that quickly and have single blend level value impact the rate at which those colors get more shaded or tinted when using the alpha blendLevel.

It still work liek this for scalffoldBackgroundColor and dialogBackgroundColor, but all the new surface colors now have a fixed expected shade relationship. If I were to introduce different blend factors for all the different surface colors, it would get confusing as their semantic and expected blend relationships might cross their allowed range borders and into the next shades "territory". So I opted to keep the blend level blending factor same for all the surface colors in the ColorScheme.

Before V8 there was also surfaceVariant color in ColorScheme. It also got removed in Flutter 3.22 in favor of all the new surface colors. It was based on design spec always more tinted shaded than surface, but since there was only one color, I could then also vary its blend factor a bit depending on FlexSurfaceMode used. To get style variation on it too.

In fact in 7.3.1 and earlier the blend factors looked like this:

      // Result: Scaffold (3x) background (3/2x) surface (1x).
      // surfaceVariant (Surface*2)
      case FlexSurfaceMode.highScaffoldLevelSurface:
        return FlexAlphaValues(
          primaryAlpha: blendLevel,
          primaryContainerAlpha: blendLevel * 2,
          secondaryAlpha: blendLevel,
          secondaryContainerAlpha: blendLevel * 2,
          tertiaryAlpha: blendLevel,
          tertiaryContainerAlpha: blendLevel * 2,
          errorAlpha: blendLevel,
          errorContainerAlpha: blendLevel * 2,
          surfaceAlpha: blendLevel,
          surfaceVariantAlpha: blendLevel * 2,
          inverseSurfaceAlpha: blendLevel,
          dialogAlpha: blendLevel,
          backgroundAlpha: blendLevel * 3 ~/ 2,
          scaffoldAlpha: blendLevel * 3,
        );

and

      // Result: Scaffold (3x) Surface and background (1/2x).
      // surfaceVariant (Surface*2)
      case FlexSurfaceMode.highScaffoldLowSurfaces:
      case FlexSurfaceMode.highScaffoldLowSurfacesVariantDialog:
        return FlexAlphaValues(
          primaryAlpha: blendLevel,
          primaryContainerAlpha: blendLevel * 2,
          secondaryAlpha: blendLevel,
          secondaryContainerAlpha: blendLevel * 2,
          tertiaryAlpha: blendLevel,
          tertiaryContainerAlpha: blendLevel * 2,
          errorAlpha: blendLevel,
          errorContainerAlpha: blendLevel * 2,
          surfaceAlpha: blendLevel ~/ 2,
          surfaceVariantAlpha: blendLevel ~/ 2 * 2,
          inverseSurfaceAlpha: blendLevel ~/ 2,
          dialogAlpha: blendLevel ~/ 2,
          backgroundAlpha: blendLevel ~/ 2,
          scaffoldAlpha: blendLevel * 3,
        );
    }

While we now have less degrees of freedom due to spec saying what the surface color relationships should be, we do have a lot of more shaded surface colors we can use.

The blend modes are still useful for assigning blend factor and blend level of how much blend all the surface colors will get in relation to used scaffoldBackgroundColor and dialogBackgroundColor, so the mode still varies those relations and we have a lot more surface colors we can use.

I originally added the blend modes, to give users more variation on surface tints, with fewer usable colors in ColorScheme. The new ColorScheme adds a lot of different colors to do it that way. We can now use both ways in FlexColorScheme.

The blend mode and blend levels originally also existed before seed generated M3 ColorScheme was a thing, that adds primary tint into surfaces. I created it as an easy way to do this before it was a very well known thing in Material design. Well it did exist, but only fleetingly mentioned in Material-2 guide that you can use alpha blends with primary color, in dark mode to created "branded" dark surface colors.

In FlexColorSchme you can use either alpha blended surface, or very configurable seed generated ColorSchemes, that are also typically surface tinted, with varying degree depending on chosen style, or they can also get monochrome surface. And you can even combine seed generation and surface blends.

---

Summary

This was a good observation. It is however expected behavior in the new version done on purpose to not break pats APIs and conform to less degrees of freedom in Flutter Material design, when background and surfaceVariant was removed in Flutter 3.22. I will turn it into Question & Answer and move it over to the discussions section.