angular · Splaktar · Jul 1, 2020 · Jul 8, 2016 · Jul 20, 2018
diff --git a/docs/guides/THEMES_IMPL_NOTES.md b/docs/guides/THEMES_IMPL_NOTES.md
@@ -1,38 +1,45 @@
-# Notes on ng-material's theme implementation
+# Notes on AngularJS Material's theme implementation
 
 #### TL;DR
-Themes are configured by users with `$mdThemingProvider`. The CSS is then generated at run-time by
-the `$mdTheming` service and tacked into the document head.
+You configure themes with `$mdThemingProvider`. The CSS is then generated at run-time by
+the `$mdTheming` service and appended to the document's `<head>`.
 
-## Actual explanation
+## Explanation
 
 ### At build time
-* All of the styles associated with **color** are defined in a separate scss file of the form
+* All the styles associated with **color** are defined in a separate SCSS file of the form
 `xxx-theme.scss`.
-* Instead of using hard-coded color or a SCSS variable, the colors are defined with a mini-DSL
-(described deblow).
-* The build process takes all of those `-theme.scss` files and globs them up into one enourmous
-string.  
-* The build process wraps that string with code to set it an angular module constant:
-    ``` angular.module('material.core').constant('$MD_THEME_CSS', 'HUGE_THEME_STRING'); ```
-* That code gets dumped at the end of `angular-material.js`
+* Instead of using a hard-coded color or a SCSS variable, you define the colors with a mini-DSL
+  (described below).
+* The build process takes all of those `-theme.scss` files and globs them up into one enormous
+string.
+* The build process wraps that string with code to set it as an AngularJS module constant:
+  ```
+    angular.module('material.core').constant('$MD_THEME_CSS', 'HUGE_THEME_STRING');
+  ```
+* That code gets dumped at the end of `angular-material.js`.
 
 ### At run time
 * The user defines some themes with `$mdThemingProvider` during the module config phase.
 * At module run time, the theming service takes `$MD_THEME_CSS` and, for each theme, evaluates the
 mini-DSL, applies the colors for the theme, and appends the resulting CSS into the document head.
 
-
 ### The mini-DSL
-* Each color is written in the form `'{{palette-hue-opacity}}'`, where opacity is optional. 
-* For example, `'{{primary-500}}'`
-* Palettes are `primary`, `accent`, `warn`, `background`, `foreground`
-* The hues for each type except `foreground` use the Material Design hues.
-* The `forground` palette is a number from one to four:
-  * `foreground-1`: text
-  * `foreground-2`: secondary text, icons
-  * `foreground-3`: disabled text, hint text
-  * `foreground-4`: dividers  
-* There is also a special hue called `contrast` that will give a contrast color (for text). 
-For example, `accent-contrast` will be a contrast color for the accent color, for use as a text 
-color on an accent-colored background.
+* You write each color in the form `'{{palette-hue-contrast-opacity}}'`, where `hue`, `contrast`,
+and opacity are optional.
+* For example, `'{{primary-500}}'`.
+* Palettes are `primary`, `accent`, `warn`, `background`.
+* The hues for each type use the Material Design hues. When not specified, each palette defaults
+`hue` to `500` except for `background`.
+* The `opacity` value can be a decimal between 0 and 1 or one of the following values based on the
+hue's contrast type (dark, light, or strongLight):
+  * `icon`: icon (0.54 / 0.87 / 1.0)
+  * `secondary`: secondary text (0.54 / 0.87)
+  * `disabled`: disabled text or icon (0.38 / 0.54)
+  * `hint`: hint text (0.38 / 0.50)
+  * `divider`: divider (0.12)
+* `contrast` will give a contrast color (for text) and can be mixed with `opacity`.
+For example, `accent-contrast` will be a contrast color for the accent color, for use as a text
+color on an accent-colored background. Adding an `opacity` value as in `accent-contrast-icon` will
+apply the Material Design icon opacity. Using a decimal opacity value as in `accent-contrast-0.25`
+will apply the contrast color for the accent color at 25% opacity.
diff --git a/src/components/colors/demoBasicUsage/index.html b/src/components/colors/demoBasicUsage/index.html
@@ -1,25 +1,25 @@
 <div layout="column" ng-cloak class="md-padding">
   <p style="margin-bottom: 10px;">
-    Custom component implementations using Material elements often want to easily apply Theme colors
+    Custom component implementations using Material elements often want to easily apply theme colors
     to their custom components. Consider the custom <code>&lt;user-card&gt;</code> component below
     where the <code>md-colors</code> attribute is used to color the background and text colors
-    using either the current or specified Theme palette colors.
+    using either the current or specified theme palette colors.
   </p>
   <!-- Example 1 -->
-  <span class="card-title"> <code>&lt;user-card&gt;</code> without md-color features</span>
+  <h4 class="card-title"> <code>&lt;user-card&gt;</code> without md-color features</h4>
   <regular-card name="User name" md-theme="default"></regular-card>
   <!-- Example 2 -->
-  <span class="card-title"> <code>&lt;user-card&gt;</code> coloring using the 'default' Theme</span>
+  <h4 class="card-title"> <code>&lt;user-card&gt;</code> coloring using the 'default' theme</h4>
   <user-card name="User name"></user-card>
   <!-- Example 3 -->
-  <span class="card-title"> <code>&lt;user-card&gt;</code> coloring using the 'forest' Theme</span>
+  <h4 class="card-title"> <code>&lt;user-card&gt;</code> coloring using the 'forest' theme</h4>
   <user-card name="User name" theme="forest"></user-card>
   <!-- Footnote -->
   <p class="footnote">
-    Note: The <code>md-colors</code> directive allows pre-defined theme colors to be easily applied
-    as CSS style properties. <code>md-colors</code> uses the Palettes defined at
-    <a class="md-accent" href="https://material.io/archive/guidelines/style/color.html#">Material Design Colors</a>
-    and the Themes defined using <code>$mdThemingProvider</code>. This feature is simply an
-    extension of the <code>$mdTheming</code> features.
+    Note: The <code>md-colors</code> directive allows pre-defined theme colors to be applied
+    as CSS style properties. <code>md-colors</code> uses the palettes defined in the
+    <a class="md-accent" href="https://material.io/archive/guidelines/style/color.html#color-color-palette">
+      Material Design Colors</a> and the themes defined using <code>$mdThemingProvider</code>.
+    This directive is an extension of the <code>$mdTheming</code> features.
   </p>
 </div>
diff --git a/src/components/colors/demoBasicUsage/regularCard.tmpl.html b/src/components/colors/demoBasicUsage/regularCard.tmpl.html
@@ -2,7 +2,7 @@
   <md-card-title>
     <md-card-title-media>
       <div class="md-media-sm card-media" layout>
-        <md-icon md-svg-icon="person" style="color:grey"></md-icon>
+        <md-icon md-svg-icon="social:person" style="color: grey"></md-icon>
       </div>
     </md-card-title-media>
     <md-card-title-text>

diff --git a/src/components/colors/demoBasicUsage/script.js b/src/components/colors/demoBasicUsage/script.js
@@ -5,7 +5,7 @@ angular.module('colorsDemo', ['ngMaterial'])
       .accentPalette('green');
 
     $mdIconProvider
-      .defaultIconSet('img/icons/sets/social-icons.svg', 24);
+      .iconSet('social', 'img/icons/sets/social-icons.svg', 24);
   })
   .directive('regularCard', function () {
     return {

diff --git a/src/components/colors/demoBasicUsage/style.css b/src/components/colors/demoBasicUsage/style.css
@@ -14,22 +14,21 @@
   color: rgba(255, 255, 255, 0.87);
 }
 
-span.card-title {
-  padding-left: 15px;
-  margin-top: 20px;
+h4.card-title {
+  margin: 24px 8px 0;
 }
 
 code.css {
   background-color: #fffcc2;
 }
 
 p.footnote code {
-  font-size:0.85em;
+  font-size: 0.85em;
 }
 
 p.footnote {
-  font-size:0.85em;
-  margin: 30px;
-  padding:5px;
-  background-color: rgba(205,205,205,0.45);
+  font-size: 0.85em;
+  margin: 30px 8px;
+  padding: 16px;
+  background-color: rgba(205, 205, 205, 0.45);
 }
diff --git a/src/components/colors/demoBasicUsage/userCard.tmpl.html b/src/components/colors/demoBasicUsage/userCard.tmpl.html
@@ -2,7 +2,7 @@
   <md-card-title>
     <md-card-title-media>
       <div class="md-media-sm card-media" layout md-colors="::{background: '{{theme}}-accent'}">
-        <md-icon md-svg-icon="person"></md-icon>
+        <md-icon md-svg-icon="social:person"></md-icon>
       </div>
     </md-card-title-media>
     <md-card-title-text>

diff --git a/src/components/colors/demoThemePicker/index.html b/src/components/colors/demoThemePicker/index.html
@@ -1,6 +1,6 @@
 <div layout="column" ng-cloak ng-controller="ThemeDemoCtrl" class="md-padding">
   <p>
-    Select a color from the <a class="md-accent" href="{{mdURL}}">Theme Color Palettes</a>
+    Select two of the <a class="md-accent" href="{{mdURL}}">Material Palettes</a>
     below:
   </p>
   <!-- Theme Options -->
@@ -26,8 +26,8 @@
   <!-- Footnote -->
   <p class="footnote">
     Notice that the foreground colors are automatically determined (from the theme configurations)
-    based on the specified background palette selection. Of course, you could easily override the
-    foreground color also...
+    based on the specified background palette selection. You can also override the foreground color,
+    if desired.
   </p>
 
 </div>
diff --git a/src/components/colors/demoThemePicker/script.js b/src/components/colors/demoThemePicker/script.js
@@ -3,7 +3,7 @@ angular
   .controller('ThemeDemoCtrl', function ($scope, $mdColorPalette) {
     $scope.colors = Object.keys($mdColorPalette);
 
-    $scope.mdURL = 'https://material.google.com/style/color.html#color-color-palette';
+    $scope.mdURL = 'https://material.io/archive/guidelines/style/color.html#color-color-palette';
     $scope.primary = 'purple';
     $scope.accent = 'green';
 

diff --git a/src/components/colors/demoThemePicker/style.css b/src/components/colors/demoThemePicker/style.css
@@ -18,10 +18,10 @@
 }
 
 p.footnote {
-  font-size:0.85em;
-  margin: 30px;
-  padding:5px;
-  background-color: rgba(205,205,205,0.45);
+  font-size: 0.85em;
+  margin: 30px 8px;
+  padding: 16px;
+  background-color: rgba(205, 205, 205, 0.45);
 }
 
 .componentTag {