Improve docs for colors (#6473)

packages/flutter/lib/src/material/colors.dart

@@ -7,6 +7,11 @@ import 'dart:ui' show Color;
 /// [Color] constants which represent Material design's
 /// [color palette](http://material.google.com/style/color.html).
 ///
+/// Instead of using an absolute color from these palettes, consider using
+/// [Theme.of] to obtain the local [ThemeData] structure, which exposes the
+/// colors selected for the current theme, such as [ThemeData.primaryColor] and
+/// [ThemeData.accentColor] (among many others).
+///
 /// To select a specific color from one of the swatches, index into the swatch
 /// using an integer for the specific color desired, as follows:
 ///
@@ -32,9 +37,25 @@ class Colors {
   static const Color black   = const Color(0xFF000000);
 
   /// Black with 87% opacity.
+  ///
+  /// This is a good contrasting color for text in light themes.
+  ///
+  /// See also:
+  ///
+  /// * [Typography.black], which uses this color for its text styles.
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Color black87 = const Color(0xDD000000);
 
   /// Black with 54% opacity.
+  ///
+  /// This is a color commonly used for headings in light themes.
+  ///
+  /// See also:
+  ///
+  /// * [Typography.black], which uses this color for its text styles.
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Color black54 = const Color(0x8A000000);
 
   /// Black with 38% opacity.
@@ -50,6 +71,12 @@ class Colors {
   /// Black with 26% opacity.
   ///
   /// Used for disabled radio buttons and the text of disabled flat buttons in light themes.
+  ///
+  /// See also:
+  ///
+  /// * [ThemeData.disabledColor], which uses this color by default in light themes.
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Color black26 = const Color(0x42000000);
 
   /// Black with 12% opacity.
@@ -59,14 +86,37 @@ class Colors {
 
 
   /// Completely opaque white.
+  ///
+  /// This is a good contrasting color for the [ThemeData.primaryColor] in the
+  /// dark theme. See [ThemeData.brightness].
+  ///
+  /// See also:
+  ///
+  /// * [Typography.white], which uses this color for its text styles.
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Color white   = const Color(0xFFFFFFFF);
 
   /// White with 70% opacity.
+  ///
+  /// This is a color commonly used for headings in dark themes.
+  ///
+  /// See also:
+  ///
+  /// * [Typography.white], which uses this color for its text styles.
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Color white70 = const Color(0xB3FFFFFF);
 
   /// White with 32% opacity.
   ///
   /// Used for disabled radio buttons and the text of disabled flat buttons in dark themes.
+  ///
+  /// See also:
+  ///
+  /// * [ThemeData.disabledColor], which uses this color by default in dark themes.
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Color white30 = const Color(0x4DFFFFFF);
 
   /// White with 12% opacity.
@@ -79,6 +129,19 @@ class Colors {
 
 
   /// The red primary swatch.
+  ///
+  /// ```dart
+  ///  new Icon(
+  ///    icon: Icons.widgets,
+  ///    color: Colors.red[400],
+  ///  ),
+  /// ```
+  ///
+  /// See also:
+  ///
+  /// * [redAccent], the corresponding accent colors.
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Map<int, Color> red = const <int, Color>{
      50: const Color(0xFFFFEBEE),
     100: const Color(0xFFFFCDD2),
@@ -93,6 +156,19 @@ class Colors {
   };
 
   /// The red accent swatch.
+  ///
+  /// ```dart
+  ///  new Icon(
+  ///    icon: Icons.widgets,
+  ///    color: Colors.redAccent[400],
+  ///  ),
+  /// ```
+  ///
+  /// See also:
+  ///
+  /// * [red], the corresponding primary colors.
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Map<int, Color> redAccent = const <int, Color>{
     100: const Color(0xFFFF8A80),
     200: const Color(0xFFFF5252),
@@ -101,6 +177,19 @@ class Colors {
   };
 
   /// The pink primary swatch.
+  ///
+  /// ```dart
+  ///  new Icon(
+  ///    icon: Icons.widgets,
+  ///    color: Colors.pink[400],
+  ///  ),
+  /// ```
+  ///
+  /// See also:
+  ///
+  /// * [pinkAccent], the corresponding accent colors.
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Map<int, Color> pink = const <int, Color>{
      50: const Color(0xFFFCE4EC),
     100: const Color(0xFFF8BBD0),
@@ -115,6 +204,19 @@ class Colors {
   };
 
   /// The pink accent swatch.
+  ///
+  /// ```dart
+  ///  new Icon(
+  ///    icon: Icons.widgets,
+  ///    color: Colors.pinkAccent[400],
+  ///  ),
+  /// ```
+  ///
+  /// See also:
+  ///
+  /// * [pink], the corresponding primary colors.
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Map<int, Color> pinkAccent = const <int, Color>{
     100: const Color(0xFFFF80AB),
     200: const Color(0xFFFF4081),
@@ -123,6 +225,19 @@ class Colors {
   };
 
   /// The purple primary swatch.
+  ///
+  /// ```dart
+  ///  new Icon(
+  ///    icon: Icons.widgets,
+  ///    color: Colors.purple[400],
+  ///  ),
+  /// ```
+  ///
+  /// See also:
+  ///
+  /// * [purpleAccent], the corresponding accent colors.
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Map<int, Color> purple = const <int, Color>{
      50: const Color(0xFFF3E5F5),
     100: const Color(0xFFE1BEE7),
@@ -137,6 +252,19 @@ class Colors {
   };
 
   /// The purple accent swatch.
+  ///
+  /// ```dart
+  ///  new Icon(
+  ///    icon: Icons.widgets,
+  ///    color: Colors.purpleAccent[400],
+  ///  ),
+  /// ```
+  ///
+  /// See also:
+  ///
+  /// * [purple], the corresponding primary colors.
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Map<int, Color> purpleAccent = const <int, Color>{
     100: const Color(0xFFEA80FC),
     200: const Color(0xFFE040FB),
@@ -145,6 +273,19 @@ class Colors {
   };
 
   /// The deep purple primary swatch.
+  ///
+  /// ```dart
+  ///  new Icon(
+  ///    icon: Icons.widgets,
+  ///    color: Colors.deepPurple[400],
+  ///  ),
+  /// ```
+  ///
+  /// See also:
+  ///
+  /// * [deepPurpleAccent], the corresponding accent colors.
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Map<int, Color> deepPurple = const <int, Color>{
      50: const Color(0xFFEDE7F6),
     100: const Color(0xFFD1C4E9),
@@ -159,6 +300,19 @@ class Colors {
   };
 
   /// The deep purple accent swatch.
+  ///
+  /// ```dart
+  ///  new Icon(
+  ///    icon: Icons.widgets,
+  ///    color: Colors.deepPurpleAccent[400],
+  ///  ),
+  /// ```
+  ///
+  /// See also:
+  ///
+  /// * [deepPurple], the corresponding primary colors.
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Map<int, Color> deepPurpleAccent = const <int, Color>{
     100: const Color(0xFFB388FF),
     200: const Color(0xFF7C4DFF),
@@ -167,6 +321,19 @@ class Colors {
   };
 
   /// The indigo primary swatch.
+  ///
+  /// ```dart
+  ///  new Icon(
+  ///    icon: Icons.widgets,
+  ///    color: Colors.indigo[400],
+  ///  ),
+  /// ```
+  ///
+  /// See also:
+  ///
+  /// * [indigoAccent], the corresponding accent colors.
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Map<int, Color> indigo = const <int, Color>{
      50: const Color(0xFFE8EAF6),
     100: const Color(0xFFC5CAE9),
@@ -181,6 +348,19 @@ class Colors {
   };
 
   /// The indigo accent swatch.
+  ///
+  /// ```dart
+  ///  new Icon(
+  ///    icon: Icons.widgets,
+  ///    color: Colors.indigoAccent[400],
+  ///  ),
+  /// ```
+  ///
+  /// See also:
+  ///
+  /// * [indigo], the corresponding primary colors.
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Map<int, Color> indigoAccent = const <int, Color>{
     100: const Color(0xFF8C9EFF),
     200: const Color(0xFF536DFE),
@@ -189,6 +369,19 @@ class Colors {
   };
 
   /// The blue primary swatch.
+  ///
+  /// ```dart
+  ///  new Icon(
+  ///    icon: Icons.widgets,
+  ///    color: Colors.blue[400],
+  ///  ),
+  /// ```
+  ///
+  /// See also:
+  ///
+  /// * [blueAccent], the corresponding accent colors.
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Map<int, Color> blue = const <int, Color>{
      50: const Color(0xFFE3F2FD),
     100: const Color(0xFFBBDEFB),
@@ -203,6 +396,19 @@ class Colors {
   };
 
   /// The blue accent swatch.
+  ///
+  /// ```dart
+  ///  new Icon(
+  ///    icon: Icons.widgets,
+  ///    color: Colors.blueAccent[400],
+  ///  ),
+  /// ```
+  ///
+  /// See also:
+  ///
+  /// * [blue], the corresponding primary colors.
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Map<int, Color> blueAccent = const <int, Color>{
     100: const Color(0xFF82B1FF),
     200: const Color(0xFF448AFF),
@@ -211,6 +417,19 @@ class Colors {
   };
 
   /// The light blue primary swatch.
+  ///
+  /// ```dart
+  ///  new Icon(
+  ///    icon: Icons.widgets,
+  ///    color: Colors.lightBlue[400],
+  ///  ),
+  /// ```
+  ///
+  /// See also:
+  ///
+  /// * [lightBlueAccent], the corresponding accent colors.
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Map<int, Color> lightBlue = const <int, Color>{
      50: const Color(0xFFE1F5FE),
     100: const Color(0xFFB3E5FC),
@@ -225,6 +444,19 @@ class Colors {
   };
 
   /// The light blue accent swatch.
+  ///
+  /// ```dart
+  ///  new Icon(
+  ///    icon: Icons.widgets,
+  ///    color: Colors.lightBlueAccent[400],
+  ///  ),
+  /// ```
+  ///
+  /// See also:
+  ///
+  /// * [lightBlue], the corresponding primary colors.
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Map<int, Color> lightBlueAccent = const <int, Color>{
     100: const Color(0xFF80D8FF),
     200: const Color(0xFF40C4FF),
@@ -233,6 +465,19 @@ class Colors {
   };
 
   /// The cyan primary swatch.
+  ///
+  /// ```dart
+  ///  new Icon(
+  ///    icon: Icons.widgets,
+  ///    color: Colors.cyan[400],
+  ///  ),
+  /// ```
+  ///
+  /// See also:
+  ///
+  /// * [cyanAccent], the corresponding accent colors.
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Map<int, Color> cyan = const <int, Color>{
      50: const Color(0xFFE0F7FA),
     100: const Color(0xFFB2EBF2),
@@ -247,6 +492,19 @@ class Colors {
   };
 
   /// The cyan accent swatch.
+  ///
+  /// ```dart
+  ///  new Icon(
+  ///    icon: Icons.widgets,
+  ///    color: Colors.cyanAccent[400],
+  ///  ),
+  /// ```
+  ///
+  /// See also:
+  ///
+  /// * [cyan], the corresponding primary colors.
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Map<int, Color> cyanAccent = const <int, Color>{
     100: const Color(0xFF84FFFF),
     200: const Color(0xFF18FFFF),
@@ -255,6 +513,19 @@ class Colors {
   };
 
   /// The teal primary swatch.
+  ///
+  /// ```dart
+  ///  new Icon(
+  ///    icon: Icons.widgets,
+  ///    color: Colors.teal[400],
+  ///  ),
+  /// ```
+  ///
+  /// See also:
+  ///
+  /// * [tealAccent], the corresponding accent colors.
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Map<int, Color> teal = const <int, Color>{
      50: const Color(0xFFE0F2F1),
     100: const Color(0xFFB2DFDB),
@@ -269,6 +540,19 @@ class Colors {
   };
 
   /// The teal accent swatch.
+  ///
+  /// ```dart
+  ///  new Icon(
+  ///    icon: Icons.widgets,
+  ///    color: Colors.tealAccent[400],
+  ///  ),
+  /// ```
+  ///
+  /// See also:
+  ///
+  /// * [teal], the corresponding primary colors.
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Map<int, Color> tealAccent = const <int, Color>{
     100: const Color(0xFFA7FFEB),
     200: const Color(0xFF64FFDA),
@@ -277,6 +561,19 @@ class Colors {
   };
 
   /// The green primary swatch.
+  ///
+  /// ```dart
+  ///  new Icon(
+  ///    icon: Icons.widgets,
+  ///    color: Colors.green[400],
+  ///  ),
+  /// ```
+  ///
+  /// See also:
+  ///
+  /// * [greenAccent], the corresponding accent colors.
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Map<int, Color> green = const <int, Color>{
      50: const Color(0xFFE8F5E9),
     100: const Color(0xFFC8E6C9),
@@ -291,6 +588,19 @@ class Colors {
   };
 
   /// The green accent swatch.
+  ///
+  /// ```dart
+  ///  new Icon(
+  ///    icon: Icons.widgets,
+  ///    color: Colors.greenAccent[400],
+  ///  ),
+  /// ```
+  ///
+  /// See also:
+  ///
+  /// * [green], the corresponding primary colors.
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Map<int, Color> greenAccent = const <int, Color>{
     100: const Color(0xFFB9F6CA),
     200: const Color(0xFF69F0AE),
@@ -299,6 +609,19 @@ class Colors {
   };
 
   /// The light green primary swatch.
+  ///
+  /// ```dart
+  ///  new Icon(
+  ///    icon: Icons.widgets,
+  ///    color: Colors.lightGreen[400],
+  ///  ),
+  /// ```
+  ///
+  /// See also:
+  ///
+  /// * [lightGreenAccent], the corresponding accent colors.
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Map<int, Color> lightGreen = const <int, Color>{
      50: const Color(0xFFF1F8E9),
     100: const Color(0xFFDCEDC8),
@@ -313,6 +636,19 @@ class Colors {
   };
 
   /// The light green accent swatch.
+  ///
+  /// ```dart
+  ///  new Icon(
+  ///    icon: Icons.widgets,
+  ///    color: Colors.lightGreenAccent[400],
+  ///  ),
+  /// ```
+  ///
+  /// See also:
+  ///
+  /// * [lightGreen], the corresponding primary colors.
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Map<int, Color> lightGreenAccent = const <int, Color>{
     100: const Color(0xFFCCFF90),
     200: const Color(0xFFB2FF59),
@@ -321,6 +657,19 @@ class Colors {
   };
 
   /// The lime primary swatch.
+  ///
+  /// ```dart
+  ///  new Icon(
+  ///    icon: Icons.widgets,
+  ///    color: Colors.lime[400],
+  ///  ),
+  /// ```
+  ///
+  /// See also:
+  ///
+  /// * [limeAccent], the corresponding accent colors.
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Map<int, Color> lime = const <int, Color>{
      50: const Color(0xFFF9FBE7),
     100: const Color(0xFFF0F4C3),
@@ -335,6 +684,19 @@ class Colors {
   };
 
   /// The lime accent primary swatch.
+  ///
+  /// ```dart
+  ///  new Icon(
+  ///    icon: Icons.widgets,
+  ///    color: Colors.limeAccent[400],
+  ///  ),
+  /// ```
+  ///
+  /// See also:
+  ///
+  /// * [lime], the corresponding primary colors.
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Map<int, Color> limeAccent = const <int, Color>{
     100: const Color(0xFFF4FF81),
     200: const Color(0xFFEEFF41),
@@ -343,6 +705,19 @@ class Colors {
   };
 
   /// The yellow primary swatch.
+  ///
+  /// ```dart
+  ///  new Icon(
+  ///    icon: Icons.widgets,
+  ///    color: Colors.yellow[400],
+  ///  ),
+  /// ```
+  ///
+  /// See also:
+  ///
+  /// * [yellowAccentAccent], the corresponding accent colors.
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Map<int, Color> yellow = const <int, Color>{
      50: const Color(0xFFFFFDE7),
     100: const Color(0xFFFFF9C4),
@@ -357,6 +732,19 @@ class Colors {
   };
 
   /// The yellow accent swatch.
+  ///
+  /// ```dart
+  ///  new Icon(
+  ///    icon: Icons.widgets,
+  ///    color: Colors.yellowAccent[400],
+  ///  ),
+  /// ```
+  ///
+  /// See also:
+  ///
+  /// * [yellow], the corresponding primary colors.
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Map<int, Color> yellowAccent = const <int, Color>{
     100: const Color(0xFFFFFF8D),
     200: const Color(0xFFFFFF00),
@@ -365,6 +753,19 @@ class Colors {
   };
 
   /// The amber primary swatch.
+  ///
+  /// ```dart
+  ///  new Icon(
+  ///    icon: Icons.widgets,
+  ///    color: Colors.amber[400],
+  ///  ),
+  /// ```
+  ///
+  /// See also:
+  ///
+  /// * [amberAccent], the corresponding accent colors.
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Map<int, Color> amber = const <int, Color>{
      50: const Color(0xFFFFF8E1),
     100: const Color(0xFFFFECB3),
@@ -379,6 +780,19 @@ class Colors {
   };
 
   /// The amber accent swatch.
+  ///
+  /// ```dart
+  ///  new Icon(
+  ///    icon: Icons.widgets,
+  ///    color: Colors.amberAccent[400],
+  ///  ),
+  /// ```
+  ///
+  /// See also:
+  ///
+  /// * [amber], the corresponding primary colors.
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Map<int, Color> amberAccent = const <int, Color>{
     100: const Color(0xFFFFE57F),
     200: const Color(0xFFFFD740),
@@ -387,6 +801,19 @@ class Colors {
   };
 
   /// The orange primary swatch.
+  ///
+  /// ```dart
+  ///  new Icon(
+  ///    icon: Icons.widgets,
+  ///    color: Colors.orange[400],
+  ///  ),
+  /// ```
+  ///
+  /// See also:
+  ///
+  /// * [orangeAccent], the corresponding accent colors.
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Map<int, Color> orange = const <int, Color>{
      50: const Color(0xFFFFF3E0),
     100: const Color(0xFFFFE0B2),
@@ -401,6 +828,19 @@ class Colors {
   };
 
   /// The orange accent swatch.
+  ///
+  /// ```dart
+  ///  new Icon(
+  ///    icon: Icons.widgets,
+  ///    color: Colors.orangeAccent[400],
+  ///  ),
+  /// ```
+  ///
+  /// See also:
+  ///
+  /// * [orange], the corresponding primary colors.
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Map<int, Color> orangeAccent = const <int, Color>{
     100: const Color(0xFFFFD180),
     200: const Color(0xFFFFAB40),
@@ -409,6 +849,19 @@ class Colors {
   };
 
   /// The deep orange primary swatch.
+  ///
+  /// ```dart
+  ///  new Icon(
+  ///    icon: Icons.widgets,
+  ///    color: Colors.deepOrange[400],
+  ///  ),
+  /// ```
+  ///
+  /// See also:
+  ///
+  /// * [deepOrangeAccent], the corresponding accent colors.
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Map<int, Color> deepOrange = const <int, Color>{
      50: const Color(0xFFFBE9E7),
     100: const Color(0xFFFFCCBC),
@@ -423,6 +876,19 @@ class Colors {
   };
 
   /// The deep orange accent swatch.
+  ///
+  /// ```dart
+  ///  new Icon(
+  ///    icon: Icons.widgets,
+  ///    color: Colors.deepOrangeAccent[400],
+  ///  ),
+  /// ```
+  ///
+  /// See also:
+  ///
+  /// * [deepOrange], the corresponding primary colors.
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Map<int, Color> deepOrangeAccent = const <int, Color>{
     100: const Color(0xFFFF9E80),
     200: const Color(0xFFFF6E40),
@@ -431,6 +897,20 @@ class Colors {
   };
 
   /// The brown primary swatch.
+  ///
+  /// ```dart
+  ///  new Icon(
+  ///    icon: Icons.widgets,
+  ///    color: Colors.brown[400],
+  ///  ),
+  /// ```
+  ///
+  /// This swatch has no corresponding accent swatch.
+  ///
+  /// See also:
+  ///
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Map<int, Color> brown = const <int, Color>{
      50: const Color(0xFFEFEBE9),
     100: const Color(0xFFD7CCC8),
@@ -445,22 +925,55 @@ class Colors {
   };
 
   /// The grey primary swatch.
+  ///
+  /// ```dart
+  ///  new Icon(
+  ///    icon: Icons.widgets,
+  ///    color: Colors.grey[400],
+  ///  ),
+  /// ```
+  ///
+  /// This swatch has no corresponding accent swatch.
+  ///
+  /// This swatch, in addition to the values 50 and 100 to 900 in 100
+  /// increments, also features the special values 350 and 850. The 350 value is
+  /// used for raised button while pressed in light themes, and 850 is used for
+  /// the background color of the dark theme. See [ThemeData.brightness].
+  ///
+  /// See also:
+  ///
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Map<int, Color> grey = const <int, Color>{
      50: const Color(0xFFFAFAFA),
     100: const Color(0xFFF5F5F5),
     200: const Color(0xFFEEEEEE),
     300: const Color(0xFFE0E0E0),
-    350: const Color(0xFFD6D6D6), // only for raised button while pressed in Light theme
+    350: const Color(0xFFD6D6D6), // only for raised button while pressed in light theme
     400: const Color(0xFFBDBDBD),
     500: const Color(0xFF9E9E9E),
     600: const Color(0xFF757575),
     700: const Color(0xFF616161),
     800: const Color(0xFF424242),
-    850: const Color(0xFF303030), // only for background color in Dark theme
+    850: const Color(0xFF303030), // only for background color in dark theme
     900: const Color(0xFF212121),
   };
 
   /// The blue-grey primary swatch.
+  ///
+  /// ```dart
+  ///  new Icon(
+  ///    icon: Icons.widgets,
+  ///    color: Colors.blueGrey[400],
+  ///  ),
+  /// ```
+  ///
+  /// This swatch has no corresponding accent swatch.
+  ///
+  /// See also:
+  ///
+  /// * [Theme.of], which allows you to select colors from the current theme
+  ///   rather than hard-coding colors in your build methods.
   static const Map<int, Color> blueGrey = const <int, Color>{
      50: const Color(0xFFECEFF1),
     100: const Color(0xFFCFD8DC),

packages/flutter/lib/src/material/icon.dart

@@ -12,13 +12,15 @@ import 'theme.dart';
 
 /// A material design icon.
 ///
-/// Available icons are shown on this page:
-/// <https://design.google.com/icons/>
+/// Icons are not interactive. For an interactive icon, consider [IconButton].
 ///
 /// Icons are identified by their name (as given on that page), with
 /// spaces converted to underscores, from the [Icons] class. For
 /// example, the "alarm add" icon is [Icons.alarm_add].
 ///
+/// Available icons are shown on this page:
+/// <https://design.google.com/icons/>
+///
 /// To use this class, make sure you set `uses-material-design: true`
 /// in your project's `flutter.yaml` file. This ensures that the
 /// MaterialIcons font is included in your application. This font is