diff --git a/packages/flutter/lib/src/material/colors.dart b/packages/flutter/lib/src/material/colors.dart
index fde3e5a23e..a25b9c6341 100644
--- a/packages/flutter/lib/src/material/colors.dart
+++ b/packages/flutter/lib/src/material/colors.dart
@@ -17,6 +17,11 @@ import 'package:flutter/painting.dart';
 ///  * [Colors], which defines all of the standard material colors.
 class MaterialColor extends ColorSwatch<int> {
   /// Creates a color swatch with a variety of shades.
+  ///
+  /// The `primary` argument should be the 32 bit ARGB value of one of the
+  /// values in the swatch, as would be passed to the [new Color] constructor
+  /// for that same color, and as is exposed by [value]. (This is distinct from
+  /// the specific index of the color in the swatch.)
   const MaterialColor(int primary, Map<int, Color> swatch) : super(primary, swatch);
 
   /// The lightest shade.
diff --git a/packages/flutter/lib/src/painting/colors.dart b/packages/flutter/lib/src/painting/colors.dart
index e0a8269e36..64def58b3f 100644
--- a/packages/flutter/lib/src/painting/colors.dart
+++ b/packages/flutter/lib/src/painting/colors.dart
@@ -205,6 +205,11 @@ class HSVColor {
 ///  * [material.Colors], which defines all of the standard material design colors.
 class ColorSwatch<T> extends Color {
   /// Creates a color that has a small table of related colors called a "swatch".
+  ///
+  /// The `primary` argument should be the 32 bit ARGB value of one of the
+  /// values in the swatch, as would be passed to the [new Color] constructor
+  /// for that same color, and as is exposed by [value]. (This is distinct from
+  /// the specific index of the color in the swatch.)
   const ColorSwatch(int primary, this._swatch) : super(primary);
 
   @protected