What is difference between primary and onPrimary properties in ColorScheme Flutter

Question

While defining ThemeData of the Flutter app, we can define colorScheme property. This property has inner-properties such as background & onBackground, primary & onPrimary, secondary & onSecondary, etc. Also, all these properties are set as required.

  static final ThemeData lightTheme = ThemeData(
    colorScheme: ColorScheme(
      background: appBackgroundColor,
      brightness: Brightness.light,
      error: Colors.white,
      onBackground: primaryColor,
      onError: null,
      onPrimary: null,
      onSecondary: null,
      onSurface: null,
      primary: null,
      secondary: secondaryColor,
      surface: null,
    ),
  );

I tried referring the documentation of Flutter but I was not quite able to understand the difference between them.

Answer 1

"On" colors App surfaces use colors from specific categories in your color palette, such as a primary color. Whenever elements, such as text or icons, appear in front of those surfaces, those elements should use colors designed to be clear and legible against the colors behind them.

This category of colors is called “on” colors, referring to the fact that they color elements that appear “on” top of surfaces that use the following colors: a primary color, secondary color, surface color, background color, or error color. When a color appears “on” top of a primary color, it’s called an “on primary color.” They are labelled using the original color category (such as primary color) with the prefix “on.”

“On” colors are primarily applied to text, iconography, and strokes. Sometimes, they are applied to surfaces.

The default values for “on” colors are #FFFFFF and #000000.

check this : The color system

Answer 2

Many of the colors have matching 'on' colors, which are used for drawing content on top of the matching color. For example, if something is using primary for a background color, onPrimary would be used to paint text and icons on top of it. For this reason, the 'on' colors should have a contrast ratio with their matching colors of at least 4.5:1 in order to be readable.

Got this from https://api.flutter.dev/flutter/material/ColorScheme-class.html