From 0e5fc4da0c251fe44d53aba1c246b066ffd886c4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bruno=20da=20Silva=20jo=C3=A3o?= <bruno@tzadi.com>
Date: Fri, 30 Sep 2016 08:54:54 -0300
Subject: [PATCH 01/16] (docs) update theming.md

@jelbourn, I've used /src/lib/input/_input-theme.scss as base to updat the custom component.
---
 docs/theming.md | 86 ++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 81 insertions(+), 5 deletions(-)

diff --git a/docs/theming.md b/docs/theming.md
index 16a242516f52..8bba30556255 100644
--- a/docs/theming.md
+++ b/docs/theming.md
@@ -109,15 +109,91 @@ dark theme.
 In order to style your own components with our tooling, the component's styles must be defined 
 with Sass. 
 
-You can consume the theming functions and variables from the `@angular/material/core/theming`.
-You can use the `md-color` function to extract a specific color from a palette. For example:
+You can consume the theming functions and variables from the @angular/material/core/theming. You can use the `map-get` function to extract the theming variables and `md-color` function to extract a specific color from a palette. For example:
+
+app/custom-input/custom-input-theme.scss
+
 ```scss
-.unicorn-carousel {
-  background-color: md-color($primary);
-  color: md-color($primary, default-contrast);
+@import '~@angular/material/core/theming/theming';
+
+@mixin custom-input-theme($theme) {
+  // Extract theme variables
+  $primary: map-get($theme, primary);
+  $accent: map-get($theme, accent);
+  $warn: map-get($theme, warn);
+  $background: map-get($theme, background);
+  $foreground: map-get($theme, foreground);
+
+  // Placeholder colors. Required is used for the `*` star shown in the placeholder.
+  $input-placeholder-color: md-color($foreground, hint-text);
+  $input-floating-placeholder-color: md-color($primary);
+  $input-required-placeholder-color: md-color($accent);
+
+  // Underline colors.
+  $input-underline-color: md-color($foreground, hint-text);
+  $input-underline-color-accent: md-color($accent);
+  $input-underline-color-warn: md-color($warn);
+  $input-underline-disabled-color: md-color($foreground, hint-text);
+  $input-underline-focused-color: md-color($primary);
+
+  .custom-input-placeholder {
+    color: $input-placeholder-color;
+
+    // :focus is applied to the input, but we apply md-focused to the other elements
+    // that need to listen to it.
+    &.md-focused {
+      color: $input-floating-placeholder-color;
+
+      &.md-accent {
+        color: $input-underline-color-accent;
+      }
+      &.md-warn {
+        color: $input-underline-color-warn;
+      }
+    }
+  }
+
+  // See md-input-placeholder-floating mixin in input.scss
+  custom-input input:-webkit-autofill + .custom-input-placeholder,
+  .custom-input-placeholder.md-float:not(.md-empty), .custom-input-placeholder.md-float.md-focused {
+
+    .custom-placeholder-required {
+      color: $input-required-placeholder-color;
+    }
+  }
+
+  .custom-input-underline {
+    border-color: $input-underline-color;
+
+    .md-input-ripple {
+      background-color: $input-underline-focused-color;
+
+      &.md-accent {
+        background-color: $input-underline-color-accent;
+      }
+      &.md-warn {
+        background-color: $input-underline-color-warn;
+      }
+    }
+  }
 }
 ```
 
+And in the unicorn-app-theme.scss you have to call this scss function to apply the custom theme to your custom component:
+
+```scss
+@import '~@angular/material/core/theming/all-theme';
+@include md-core();
+$primary: md-palette($md-indigo);
+$accent:  md-palette($md-pink, A200, A100, A400);
+$warn:    md-palette($md-red);
+$theme: md-light-theme($primary, $accent, $warn);
+
+
+@include angular-material-theme($theme);
+@include custom-input-theme($theme); // Here ou apply the theme to your custom component
+```
+
 ### Future work
 * Once CSS variables (custom properties) are available in all the browsers we support,
   we will explore how to take advantage of them to make theming even simpler.

From 2ac781352fb40b2060c51a45a87be5e9c1e7d4b8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bruno=20da=20Silva=20jo=C3=A3o?= <bruno@tzadi.com>
Date: Mon, 3 Oct 2016 14:26:45 -0300
Subject: [PATCH 02/16] Added theming-your-components.md

As @jelbourn pointed, "Rather than making this document much longer, I'd rather create another file theming-your-components.md that covers how to theme your own components with the material tools."
---
 docs/theming-your-components.md | 92 +++++++++++++++++++++++++++++++++
 1 file changed, 92 insertions(+)
 create mode 100644 docs/theming-your-components.md

diff --git a/docs/theming-your-components.md b/docs/theming-your-components.md
new file mode 100644
index 000000000000..7121052fdb24
--- /dev/null
+++ b/docs/theming-your-components.md
@@ -0,0 +1,92 @@
+#Theming your custom components
+
+In order to style your own components with our tooling, the component's styles must be defined with Sass.
+
+You can consume the theming functions and variables from the @angular/material/core/theming. You can use the `map-get` function to extract the theming variables and `md-color` function to extract a specific color from a palette. For example, to theming a custom form input:
+
+Create a css file for your custom input with the `@mixin custom-input-theme` function that will be responsible for applying the theme to your custom component:
+
+app/custom-input/custom-input-theme.scss
+
+```sass
+@import '~@angular/material/core/theming/theming';
+
+@mixin custom-input-theme($theme) {
+  // Extract theme variables
+  $primary: map-get($theme, primary);
+  $accent: map-get($theme, accent);
+  $warn: map-get($theme, warn);
+  $background: map-get($theme, background);
+  $foreground: map-get($theme, foreground);
+
+  // Placeholder colors. Required is used for the `*` star shown in the placeholder.
+  $input-placeholder-color: md-color($foreground, hint-text);
+  $input-floating-placeholder-color: md-color($primary);
+  $input-required-placeholder-color: md-color($accent);
+
+  // Underline colors.
+  $input-underline-color: md-color($foreground, hint-text);
+  $input-underline-color-accent: md-color($accent);
+  $input-underline-color-warn: md-color($warn);
+  $input-underline-disabled-color: md-color($foreground, hint-text);
+  $input-underline-focused-color: md-color($primary);
+
+  .custom-input-placeholder {
+    color: $input-placeholder-color;
+
+    // :focus is applied to the input, but we apply md-focused to the other elements
+    // that need to listen to it.
+    &.md-focused {
+      color: $input-floating-placeholder-color;
+
+      &.md-accent {
+        color: $input-underline-color-accent;
+      }
+      &.md-warn {
+        color: $input-underline-color-warn;
+      }
+    }
+  }
+
+  // See md-input-placeholder-floating mixin in input.scss
+  custom-input input:-webkit-autofill + .custom-input-placeholder,
+  .custom-input-placeholder.md-float:not(.md-empty), .custom-input-placeholder.md-float.md-focused {
+
+    .custom-placeholder-required {
+      color: $input-required-placeholder-color;
+    }
+  }
+
+  .custom-input-underline {
+    border-color: $input-underline-color;
+
+    .md-input-ripple {
+      background-color: $input-underline-focused-color;
+
+      &.md-accent {
+        background-color: $input-underline-color-accent;
+      }
+      &.md-warn {
+        background-color: $input-underline-color-warn;
+      }
+    }
+  }
+}
+```
+
+And in the unicorn-app-theme.scss you have to call this scss function `custom-input-theme($theme)` to apply the custom theme to your custom component:
+
+```sass
+@import 'app/custom-input/custom-input-theme.scss';
+@import '~@angular/material/core/theming/all-theme';
+
+@include md-core();
+$primary: md-palette($md-indigo);
+$accent:  md-palette($md-pink, A200, A100, A400);
+$warn:    md-palette($md-red);
+$theme: md-light-theme($primary, $accent, $warn);
+
+
+@include angular-material-theme($theme);
+@include custom-input-theme($theme); // Here ou apply the theme to your custom component
+```

From c85eeb0175c47dd7a21b94b5ae293a14eabad790 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bruno=20da=20Silva=20jo=C3=A3o?= <bruno@tzadi.com>
Date: Mon, 3 Oct 2016 14:33:50 -0300
Subject: [PATCH 03/16] Update theming.md

As @jelbourn pointed out, We can communicate the idea of theming custo components with much less code. I added just enougth code to show how to customize custom component and I added a new file with a more deep answer.
---
 docs/theming.md | 82 ++++++-------------------------------------------
 1 file changed, 9 insertions(+), 73 deletions(-)

diff --git a/docs/theming.md b/docs/theming.md
index 8bba30556255..f030f06ce7eb 100644
--- a/docs/theming.md
+++ b/docs/theming.md
@@ -111,88 +111,24 @@ with Sass.
 
 You can consume the theming functions and variables from the @angular/material/core/theming. You can use the `map-get` function to extract the theming variables and `md-color` function to extract a specific color from a palette. For example:
 
-app/custom-input/custom-input-theme.scss
-
 ```scss
-@import '~@angular/material/core/theming/theming';
-
-@mixin custom-input-theme($theme) {
-  // Extract theme variables
+// Define a mixin that accepts a theme and outputs the color styles for the component.
+@mixin candy-carousel-theme($theme) {
+  // Extract whichever individual palettes you need from the theme.
   $primary: map-get($theme, primary);
   $accent: map-get($theme, accent);
-  $warn: map-get($theme, warn);
-  $background: map-get($theme, background);
-  $foreground: map-get($theme, foreground);
-
-  // Placeholder colors. Required is used for the `*` star shown in the placeholder.
-  $input-placeholder-color: md-color($foreground, hint-text);
-  $input-floating-placeholder-color: md-color($primary);
-  $input-required-placeholder-color: md-color($accent);
-
-  // Underline colors.
-  $input-underline-color: md-color($foreground, hint-text);
-  $input-underline-color-accent: md-color($accent);
-  $input-underline-color-warn: md-color($warn);
-  $input-underline-disabled-color: md-color($foreground, hint-text);
-  $input-underline-focused-color: md-color($primary);
-
-  .custom-input-placeholder {
-    color: $input-placeholder-color;
-
-    // :focus is applied to the input, but we apply md-focused to the other elements
-    // that need to listen to it.
-    &.md-focused {
-      color: $input-floating-placeholder-color;
-
-      &.md-accent {
-        color: $input-underline-color-accent;
-      }
-      &.md-warn {
-        color: $input-underline-color-warn;
-      }
-    }
-  }
-
-  // See md-input-placeholder-floating mixin in input.scss
-  custom-input input:-webkit-autofill + .custom-input-placeholder,
-  .custom-input-placeholder.md-float:not(.md-empty), .custom-input-placeholder.md-float.md-focused {
-
-    .custom-placeholder-required {
-      color: $input-required-placeholder-color;
-    }
-  }
-
-  .custom-input-underline {
-    border-color: $input-underline-color;
-
-    .md-input-ripple {
-      background-color: $input-underline-focused-color;
 
-      &.md-accent {
-        background-color: $input-underline-color-accent;
-      }
-      &.md-warn {
-        background-color: $input-underline-color-warn;
-      }
-    }
+  // Use md-color to extract individual colors from a palette as necessary.
+  .candy-carousel {
+    background-color: md-color($primary);
+    border-color: md-color($accent, A400);
   }
 }
 ```
 
-And in the unicorn-app-theme.scss you have to call this scss function to apply the custom theme to your custom component:
+You can see a complete example in [theming-your-components.md][2]
 
-```scss
-@import '~@angular/material/core/theming/all-theme';
-@include md-core();
-$primary: md-palette($md-indigo);
-$accent:  md-palette($md-pink, A200, A100, A400);
-$warn:    md-palette($md-red);
-$theme: md-light-theme($primary, $accent, $warn);
-
-
-@include angular-material-theme($theme);
-@include custom-input-theme($theme); // Here ou apply the theme to your custom component
-```
+[2]: https://github.com/angular/material2/blob/master/docs/theming-your-components.md
 
 ### Future work
 * Once CSS variables (custom properties) are available in all the browsers we support,

From f9e30f49d73da39b0a89947daf8ff6283632a43f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bruno=20da=20Silva=20jo=C3=A3o?= <bruno@tzadi.com>
Date: Mon, 3 Oct 2016 14:58:45 -0300
Subject: [PATCH 04/16] Update theming-your-components.md

More explanations about files and functions used.
---
 docs/theming-your-components.md | 28 ++++++++++++++++------------
 1 file changed, 16 insertions(+), 12 deletions(-)

diff --git a/docs/theming-your-components.md b/docs/theming-your-components.md
index 7121052fdb24..e2cab200e50f 100644
--- a/docs/theming-your-components.md
+++ b/docs/theming-your-components.md
@@ -2,16 +2,18 @@
 
 In order to style your own components with our tooling, the component's styles must be defined with Sass.
 
-You can consume the theming functions and variables from the @angular/material/core/theming. You can use the `map-get` function to extract the theming variables and `md-color` function to extract a specific color from a palette. For example, to theming a custom form input:
+You can consume the theming functions and variables from the @angular/material/core/theming. You can use the `map-get` function to extract the theming variables and `md-color` function to extract a specific color from a palette.
+For example, to theming a custom form input we can use the same approach used for theming the Angular 2 Material `md-input` component, as ou can see in `@angular/material/input/_input-theme.scss` file:
 
-Create a css file for your custom input with the `@mixin custom-input-theme` function that will be responsible for applying the theme to your custom component:
+Create a scss file for your custom input with a function that will be responsible for applying the theme to your custom component. In this example, we will call this function `custom-input-theme($theme)`.
 
 app/custom-input/custom-input-theme.scss
 
 ```sass
-@import '~@angular/material/core/theming/theming';
+// Import all the tools needed to customize the theme and extract parts of it
+@import '~@angular/material/core/theming/all-theme';
 
-@mixin custom-input-theme($theme) {
+@mixin custom-input-theme($theme) { // here is the function responsible for applying the theme to your custom component.
   // Extract theme variables
   $primary: map-get($theme, primary);
   $accent: map-get($theme, accent);
@@ -74,19 +76,21 @@ app/custom-input/custom-input-theme.scss
 }
 ```
 
-And in the unicorn-app-theme.scss you have to call this scss function `custom-input-theme($theme)` to apply the custom theme to your custom component:
+Now you have to apply the theme to the custom component. For that, we can create a theme file with a custom theme or a pre-built one. We will use a pre-built one to show you how to do this.
+In the src/app-theme.scss you have to call this scss function `custom-input-theme($theme)` to apply the custom theme to your custom component:
 
 ```sass
-@import 'app/custom-input/custom-input-theme.scss';
+// Import all the tools needed to customize the theme and extract parts of it
 @import '~@angular/material/core/theming/all-theme';
+// Import a pre-built theme
+@import '~@angular/material/core/theming/prebuilt/deep-purple-amber';
+// Import your custom input theme file so you can call the custom-input-theme function
+@import 'app/custom-input/custom-input-theme.scss';
 
 @include md-core();
-$primary: md-palette($md-indigo);
-$accent:  md-palette($md-pink, A200, A100, A400);
-$warn:    md-palette($md-red);
-$theme: md-light-theme($primary, $accent, $warn);
 
+$theme: md-light-theme($primary, $accent, $warn); // $primary, $accent, $warn comes from the prebuilt theme
 
-@include angular-material-theme($theme);
-@include custom-input-theme($theme); // Here ou apply the theme to your custom component
+@include angular-material-theme($theme); // Apply the theme to the material design components
+@include custom-input-theme($theme); // Here you apply the theme to your custom component
 ```

From 7da5872b33507321adfc22b966349fc01dea9733 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bruno=20da=20Silva=20jo=C3=A3o?= <bruno@tzadi.com>
Date: Mon, 3 Oct 2016 15:14:14 -0300
Subject: [PATCH 05/16] Update theming-your-components.md

Improved css look.
---
 docs/theming-your-components.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/theming-your-components.md b/docs/theming-your-components.md
index e2cab200e50f..da5407da661a 100644
--- a/docs/theming-your-components.md
+++ b/docs/theming-your-components.md
@@ -52,7 +52,8 @@ app/custom-input/custom-input-theme.scss
 
   // See md-input-placeholder-floating mixin in input.scss
   custom-input input:-webkit-autofill + .custom-input-placeholder,
-  .custom-input-placeholder.md-float:not(.md-empty), .custom-input-placeholder.md-float.md-focused {
+  .custom-input-placeholder.md-float:not(.md-empty),
+  .custom-input-placeholder.md-float.md-focused {
 
     .custom-placeholder-required {
       color: $input-required-placeholder-color;

From 69f66547e5dd2975e69cd78520df0276fb07eabc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bruno=20da=20Silva=20jo=C3=A3o?= <bruno@tzadi.com>
Date: Wed, 5 Oct 2016 10:39:07 -0300
Subject: [PATCH 06/16] Update hteming.md

Removed unnecessary code.
---
 docs/theming.md | 28 +++++++++++++++-------------
 1 file changed, 15 insertions(+), 13 deletions(-)

diff --git a/docs/theming.md b/docs/theming.md
index f030f06ce7eb..64d952f57b76 100644
--- a/docs/theming.md
+++ b/docs/theming.md
@@ -98,7 +98,7 @@ secondary dark theme:
 
   $dark-theme: md-dark-theme($dark-primary, $dark-accent, $dark-warn);
   
-@include angular-material-theme($dark-theme);   
+  @include angular-material-theme($dark-theme);   
 }
 ```
 
@@ -112,21 +112,23 @@ with Sass.
 You can consume the theming functions and variables from the @angular/material/core/theming. You can use the `map-get` function to extract the theming variables and `md-color` function to extract a specific color from a palette. For example:
 
 ```scss
-// Define a mixin that accepts a theme and outputs the color styles for the component.
-@mixin candy-carousel-theme($theme) {
-  // Extract whichever individual palettes you need from the theme.
-  $primary: map-get($theme, primary);
-  $accent: map-get($theme, accent);
-
-  // Use md-color to extract individual colors from a palette as necessary.
-  .candy-carousel {
-    background-color: md-color($primary);
-    border-color: md-color($accent, A400);
-  }
+// Import theming functions and variables
+@import '~@angular/material/core/theming/all-theme';
+// Import a pre-built theme
+@import '~@angular/material/core/theming/prebuilt/deep-purple-amber';
+
+// Extract whichever individual palettes you need from the pre-built theme.
+$primary: map-get($theme, primary);
+$accent: map-get($theme, accent);
+
+// Use md-color to extract individual colors from a palette as necessary.
+.candy-carousel {
+  background-color: md-color($primary);
+  border-color: md-color($accent, A400);
 }
 ```
 
-You can see a complete example in [theming-your-components.md][2]
+You can see a more complete example in [theming-your-components.md][2]
 
 [2]: https://github.com/angular/material2/blob/master/docs/theming-your-components.md
 

From cee6d395b228db1777dc09551d38416728254933 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bruno=20da=20Silva=20jo=C3=A3o?= <bruno@tzadi.com>
Date: Wed, 5 Oct 2016 10:59:16 -0300
Subject: [PATCH 07/16] Update theming-your-components.md

Removed unnecessary code.
Created two examples to showing customizations with and without @mixin.
No more custom theme used. Using only pre-built one.
---
 docs/theming-your-components.md | 107 +++++++++++---------------------
 1 file changed, 36 insertions(+), 71 deletions(-)

diff --git a/docs/theming-your-components.md b/docs/theming-your-components.md
index da5407da661a..4a9f526ea2a6 100644
--- a/docs/theming-your-components.md
+++ b/docs/theming-your-components.md
@@ -2,96 +2,61 @@
 
 In order to style your own components with our tooling, the component's styles must be defined with Sass.
 
-You can consume the theming functions and variables from the @angular/material/core/theming. You can use the `map-get` function to extract the theming variables and `md-color` function to extract a specific color from a palette.
-For example, to theming a custom form input we can use the same approach used for theming the Angular 2 Material `md-input` component, as ou can see in `@angular/material/input/_input-theme.scss` file:
+You can consume the theming functions from the `@angular/material/core/theming/all-theme` and theming variables from a pre-built theme or a custom one. You can use the `map-get` function to extract the theming variables and `md-color` function to extract a specific color from a palette.
+For example, to theming a custom form input:
 
-Create a scss file for your custom input with a function that will be responsible for applying the theme to your custom component. In this example, we will call this function `custom-input-theme($theme)`.
+app/candy-carousel/candy-carousel-theme.scss
 
-app/custom-input/custom-input-theme.scss
-
-```sass
-// Import all the tools needed to customize the theme and extract parts of it
+```scss
+// Import theming functions and variables
 @import '~@angular/material/core/theming/all-theme';
+// Import a pre-built theme
+@import '~@angular/material/core/theming/prebuilt/deep-purple-amber';
 
-@mixin custom-input-theme($theme) { // here is the function responsible for applying the theme to your custom component.
-  // Extract theme variables
-  $primary: map-get($theme, primary);
-  $accent: map-get($theme, accent);
-  $warn: map-get($theme, warn);
-  $background: map-get($theme, background);
-  $foreground: map-get($theme, foreground);
-
-  // Placeholder colors. Required is used for the `*` star shown in the placeholder.
-  $input-placeholder-color: md-color($foreground, hint-text);
-  $input-floating-placeholder-color: md-color($primary);
-  $input-required-placeholder-color: md-color($accent);
-
-  // Underline colors.
-  $input-underline-color: md-color($foreground, hint-text);
-  $input-underline-color-accent: md-color($accent);
-  $input-underline-color-warn: md-color($warn);
-  $input-underline-disabled-color: md-color($foreground, hint-text);
-  $input-underline-focused-color: md-color($primary);
-
-  .custom-input-placeholder {
-    color: $input-placeholder-color;
-
-    // :focus is applied to the input, but we apply md-focused to the other elements
-    // that need to listen to it.
-    &.md-focused {
-      color: $input-floating-placeholder-color;
+// Extract whichever individual palettes you need from the pre-built theme.
+$primary: map-get($theme, primary);
+$accent: map-get($theme, accent);
 
-      &.md-accent {
-        color: $input-underline-color-accent;
-      }
-      &.md-warn {
-        color: $input-underline-color-warn;
-      }
-    }
-  }
+// Use md-color to extract individual colors from a palette as necessary.
+.candy-carousel {
+  background-color: md-color($primary);
+  border-color: md-color($accent, A400);
+}
+```
 
-  // See md-input-placeholder-floating mixin in input.scss
-  custom-input input:-webkit-autofill + .custom-input-placeholder,
-  .custom-input-placeholder.md-float:not(.md-empty),
-  .custom-input-placeholder.md-float.md-focused {
+## Using @mixin to automatically apply a theme
+We can better theming our custom components adding a @mixin function to its theme file and then calling this function to apply a theme.
 
-    .custom-placeholder-required {
-      color: $input-required-placeholder-color;
-    }
-  }
+All you need is to create a @mixin function in the custom-component-theme.scss
 
-  .custom-input-underline {
-    border-color: $input-underline-color;
+```sass
+// Import all the tools needed to customize the theme and extract parts of it
+@import '~@angular/material/core/theming/all-theme';
 
-    .md-input-ripple {
-      background-color: $input-underline-focused-color;
+// Define a mixin that accepts a theme and outputs the color styles for the component.
+@mixin candy-carousel-theme($theme) {
+  // Extract whichever individual palettes you need from the theme.
+  $primary: map-get($theme, primary);
+  $accent: map-get($theme, accent);
 
-      &.md-accent {
-        background-color: $input-underline-color-accent;
-      }
-      &.md-warn {
-        background-color: $input-underline-color-warn;
-      }
-    }
+  // Use md-color to extract individual colors from a palette as necessary.
+  .candy-carousel {
+    background-color: md-color($primary);
+    border-color: md-color($accent, A400);
   }
 }
 ```
 
-Now you have to apply the theme to the custom component. For that, we can create a theme file with a custom theme or a pre-built one. We will use a pre-built one to show you how to do this.
-In the src/app-theme.scss you have to call this scss function `custom-input-theme($theme)` to apply the custom theme to your custom component:
+Now you have to apply a theme to the custom component. We have to call the @mixin function to apply the custom theme:
 
 ```sass
-// Import all the tools needed to customize the theme and extract parts of it
+// Import theming functions and variables
 @import '~@angular/material/core/theming/all-theme';
 // Import a pre-built theme
 @import '~@angular/material/core/theming/prebuilt/deep-purple-amber';
 // Import your custom input theme file so you can call the custom-input-theme function
-@import 'app/custom-input/custom-input-theme.scss';
-
-@include md-core();
-
-$theme: md-light-theme($primary, $accent, $warn); // $primary, $accent, $warn comes from the prebuilt theme
+@import 'app/candy-carousel/candy-carousel-theme.scss';
 
-@include angular-material-theme($theme); // Apply the theme to the material design components
-@include custom-input-theme($theme); // Here you apply the theme to your custom component
+//Using the $theme variable from the pre-built theme you can call the theming function
+@include candy-carousel-theme($theme);
 ```

From 21e80d14496d812f3cdd7e076268b75925208d3d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bruno=20da=20Silva=20jo=C3=A3o?= <bruno@tzadi.com>
Date: Wed, 5 Oct 2016 11:11:11 -0300
Subject: [PATCH 08/16] Update theming-your-components.md

Removed unnecessary text.
---
 docs/theming-your-components.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/theming-your-components.md b/docs/theming-your-components.md
index 4a9f526ea2a6..9bc207b34769 100644
--- a/docs/theming-your-components.md
+++ b/docs/theming-your-components.md
@@ -3,7 +3,7 @@
 In order to style your own components with our tooling, the component's styles must be defined with Sass.
 
 You can consume the theming functions from the `@angular/material/core/theming/all-theme` and theming variables from a pre-built theme or a custom one. You can use the `map-get` function to extract the theming variables and `md-color` function to extract a specific color from a palette.
-For example, to theming a custom form input:
+For example:
 
 app/candy-carousel/candy-carousel-theme.scss
 

From 2388c76807c150d7ef06421784f63ac615cbfb75 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bruno=20da=20Silva=20jo=C3=A3o?= <bruno@tzadi.com>
Date: Wed, 5 Oct 2016 11:15:36 -0300
Subject: [PATCH 09/16] Update theming-your-components.md

Removed unnecessary imports.
---
 docs/theming-your-components.md | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/docs/theming-your-components.md b/docs/theming-your-components.md
index 9bc207b34769..37f3036535a9 100644
--- a/docs/theming-your-components.md
+++ b/docs/theming-your-components.md
@@ -47,11 +47,9 @@ All you need is to create a @mixin function in the custom-component-theme.scss
 }
 ```
 
-Now you have to apply a theme to the custom component. We have to call the @mixin function to apply the custom theme:
+Now you just have have to call the @mixin function to apply the theme:
 
 ```sass
-// Import theming functions and variables
-@import '~@angular/material/core/theming/all-theme';
 // Import a pre-built theme
 @import '~@angular/material/core/theming/prebuilt/deep-purple-amber';
 // Import your custom input theme file so you can call the custom-input-theme function

From 5c1cc1b8cddd0b9c132cc4b00bb9fb5c68d4eb3d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bruno=20da=20Silva=20jo=C3=A3o?= <bruno@tzadi.com>
Date: Wed, 5 Oct 2016 11:19:55 -0300
Subject: [PATCH 10/16] Update theming.md

Shortest example.
---
 docs/theming.md | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/docs/theming.md b/docs/theming.md
index 64d952f57b76..393f9493387c 100644
--- a/docs/theming.md
+++ b/docs/theming.md
@@ -117,10 +117,6 @@ You can consume the theming functions and variables from the @angular/material/c
 // Import a pre-built theme
 @import '~@angular/material/core/theming/prebuilt/deep-purple-amber';
 
-// Extract whichever individual palettes you need from the pre-built theme.
-$primary: map-get($theme, primary);
-$accent: map-get($theme, accent);
-
 // Use md-color to extract individual colors from a palette as necessary.
 .candy-carousel {
   background-color: md-color($primary);

From 5d824847193ef7bdc078cca0ad7ec6619d09bd63 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bruno=20da=20Silva=20jo=C3=A3o?= <bruno@tzadi.com>
Date: Wed, 5 Oct 2016 11:20:08 -0300
Subject: [PATCH 11/16] Update theming-your-components.md

Shortest example.
---
 docs/theming-your-components.md | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

diff --git a/docs/theming-your-components.md b/docs/theming-your-components.md
index 37f3036535a9..55e1720f9793 100644
--- a/docs/theming-your-components.md
+++ b/docs/theming-your-components.md
@@ -2,7 +2,7 @@
 
 In order to style your own components with our tooling, the component's styles must be defined with Sass.
 
-You can consume the theming functions from the `@angular/material/core/theming/all-theme` and theming variables from a pre-built theme or a custom one. You can use the `map-get` function to extract the theming variables and `md-color` function to extract a specific color from a palette.
+You can consume the theming functions from the `@angular/material/core/theming/all-theme` and theming variables from a pre-built theme or a custom one. You can use the `md-color` function to extract a specific color from a palette.
 For example:
 
 app/candy-carousel/candy-carousel-theme.scss
@@ -13,10 +13,6 @@ app/candy-carousel/candy-carousel-theme.scss
 // Import a pre-built theme
 @import '~@angular/material/core/theming/prebuilt/deep-purple-amber';
 
-// Extract whichever individual palettes you need from the pre-built theme.
-$primary: map-get($theme, primary);
-$accent: map-get($theme, accent);
-
 // Use md-color to extract individual colors from a palette as necessary.
 .candy-carousel {
   background-color: md-color($primary);

From e3f5ff154baba72a194215a52bca00ceee26382d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bruno=20da=20Silva=20jo=C3=A3o?= <bruno@tzadi.com>
Date: Wed, 5 Oct 2016 11:28:04 -0300
Subject: [PATCH 12/16] Update theming.md

Removed unnecessary text
---
 docs/theming.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/theming.md b/docs/theming.md
index 393f9493387c..7802444aab7d 100644
--- a/docs/theming.md
+++ b/docs/theming.md
@@ -109,7 +109,7 @@ dark theme.
 In order to style your own components with our tooling, the component's styles must be defined 
 with Sass. 
 
-You can consume the theming functions and variables from the @angular/material/core/theming. You can use the `map-get` function to extract the theming variables and `md-color` function to extract a specific color from a palette. For example:
+You can consume the theming functions and variables from the @angular/material/core/theming. You can use the `md-color` function to extract a specific color from a palette. For example:
 
 ```scss
 // Import theming functions and variables

From bdc78adbce3b2101aae71b45519cd0165a277ec6 Mon Sep 17 00:00:00 2001
From: Bruno Joao <bruno@tzadi.com>
Date: Fri, 14 Oct 2016 10:01:27 -0300
Subject: [PATCH 13/16] Cleaned up and changed as @jelbourn suggested

---
 docs/theming-your-components.md | 61 ++++++++++++++++++++-------------
 docs/theming.md                 | 56 ++++++++++--------------------
 2 files changed, 55 insertions(+), 62 deletions(-)

diff --git a/docs/theming-your-components.md b/docs/theming-your-components.md
index 55e1720f9793..5bc9bb6de544 100644
--- a/docs/theming-your-components.md
+++ b/docs/theming-your-components.md
@@ -1,29 +1,16 @@
 #Theming your custom components
+In order to style your own components with Angular Material's tooling, the component's styles must be defined with Sass.
 
-In order to style your own components with our tooling, the component's styles must be defined with Sass.
+## Using `@mixin` to automatically apply a theme
 
-You can consume the theming functions from the `@angular/material/core/theming/all-theme` and theming variables from a pre-built theme or a custom one. You can use the `md-color` function to extract a specific color from a palette.
-For example:
+### Why using `@mixin`
+The advantage of using a `@mixin` function is that when you change your theme, every file that uses it will be updated automatically.
+Calling it with a different theme argument allow multiple themes within the app or component.
 
-app/candy-carousel/candy-carousel-theme.scss
+### How to use `@mixin`
+We can better theming our custom components adding a `@mixin` function to its theme file and then calling this function to apply a theme.
 
-```scss
-// Import theming functions and variables
-@import '~@angular/material/core/theming/all-theme';
-// Import a pre-built theme
-@import '~@angular/material/core/theming/prebuilt/deep-purple-amber';
-
-// Use md-color to extract individual colors from a palette as necessary.
-.candy-carousel {
-  background-color: md-color($primary);
-  border-color: md-color($accent, A400);
-}
-```
-
-## Using @mixin to automatically apply a theme
-We can better theming our custom components adding a @mixin function to its theme file and then calling this function to apply a theme.
-
-All you need is to create a @mixin function in the custom-component-theme.scss
+All you need is to create a `@mixin` function in the custom-component-theme.scss
 
 ```sass
 // Import all the tools needed to customize the theme and extract parts of it
@@ -42,8 +29,7 @@ All you need is to create a @mixin function in the custom-component-theme.scss
   }
 }
 ```
-
-Now you just have have to call the @mixin function to apply the theme:
+Now you just have have to call the `@mixin` function to apply the theme:
 
 ```sass
 // Import a pre-built theme
@@ -51,6 +37,33 @@ Now you just have have to call the @mixin function to apply the theme:
 // Import your custom input theme file so you can call the custom-input-theme function
 @import 'app/candy-carousel/candy-carousel-theme.scss';
 
-//Using the $theme variable from the pre-built theme you can call the theming function
+// Using the $theme variable from the pre-built theme you can call the theming function
 @include candy-carousel-theme($theme);
 ```
+
+For more details about the theming functions, see the comments in the
+[source](https://github.com/angular/material2/blob/master/src/lib/core/theming/_theming.scss).
+
+### Best practices using `@mixin`
+When using `@mixin`, the theme file should only contain the definitions that are affected by the passed-in theme.
+
+All styles that are not affected by the theme should be placed in a `component.scss` file. This file should contain sizes, transitions, positioning and everything that is not affected by the theme.
+
+Styles that are affected by the theme should be placed in a separated theming file as `component-theme.scss`. This file should contain the `@mixin` function responsible for applying the theme to the component.
+
+
+## Using colors from a pallete
+You can consume the theming functions from the `@angular/material/core/theming/theming` and Material pallete vars from `@angular/material/core/theming/palette`. You can use the `md-color` function to extract a specific color from a palette. For example:
+
+```scss
+// Import theming functions
+@import '~@angular/material/core/theming/theming';
+// Import your custom theme
+@import 'src/unicorn-app-theme.scss';
+
+// Use md-color to extract individual colors from a palette as necessary.
+.candy-carousel {
+  background-color: md-color($candy-app-primary);
+  border-color: md-color($candy-app-accent, A400);
+}
+```
diff --git a/docs/theming.md b/docs/theming.md
index 7802444aab7d..cef94c7b891e 100644
--- a/docs/theming.md
+++ b/docs/theming.md
@@ -3,9 +3,9 @@
 
 ### What is a theme?
 A **theme** is the set of colors that will be applied to the Angular Material components. The
-library's approach to theming is based on the guidance from the [Material Design spec][1]. 
+library's approach to theming is based on the guidance from the [Material Design spec][1].
 
-In Angular Material, a theme is created by composing multiple palettes. In particular, 
+In Angular Material, a theme is created by composing multiple palettes. In particular,
 a theme consists of:
 * A primary palette: colors most widely used across all screens and components.
 * An accent palette: colors used for the floating action button and interactive elements.
@@ -21,9 +21,9 @@ app doesn't have to spend cycles generating theme styles on startup.
 ### Using a pre-built theme
 Angular Material comes prepackaged with several pre-built theme css files. These theme files also
 include all of the styles for core (styles common to all components), so you only have to include a
-single css file for Angular Material in your app. 
+single css file for Angular Material in your app.
 
-You can include a theme file directly into your application from 
+You can include a theme file directly into your application from
 `@angular/material/core/theming/prebuilt`
 
 If you're using Angular CLI, this is as simple as including one line
@@ -35,8 +35,8 @@ in your `style.css`  file:
 Alternatively, you can just reference the file directly. This would look something like
 ```html
 <link href="node_modules/@angular/material/core/theming/prebuilt/indigo-pink.css" rel="stylesheet">
-``` 
-The actual path will depend on your server setup. 
+```
+The actual path will depend on your server setup.
 
 You can also concatenate the file with the rest of your application's css.
 
@@ -56,25 +56,25 @@ the corresponding styles. A typical theme file will look something like this:
 // Define the palettes for your theme using the Material Design palettes available in palette.scss
 // (imported above). For each palette, you can optionally specify a default, lighter, and darker
 // hue.
-$primary: md-palette($md-indigo);
-$accent:  md-palette($md-pink, A200, A100, A400);
+$candy-app-primary: md-palette($md-indigo);
+$candy-app-accent:  md-palette($md-pink, A200, A100, A400);
 
 // The warn palette is optional (defaults to red).
-$warn:    md-palette($md-red);
+$candy-app-warn:    md-palette($md-red);
 
 // Create the theme object (a Sass map containing all of the palettes).
-$theme: md-light-theme($primary, $accent, $warn);
+$candy-app-theme: md-light-theme($candy-app-primary, $candy-app-accent, $candy-app-warn);
 
 // Include theme styles for core and each component used in your app.
 // Alternatively, you can import and @include the theme mixins for each component
 // that you are using.
-@include angular-material-theme($theme);
+@include angular-material-theme($candy-app-theme);
 ```
 
 You only need this single Sass file; you do not need to use Sass to style the rest of your app.
 
-If you are using the Angular CLI, support for compiling Sass to css is built-in; you only have to 
-add a new entry to the `"styles"` list in `angular-cli.json` pointing to the theme 
+If you are using the Angular CLI, support for compiling Sass to css is built-in; you only have to
+add a new entry to the `"styles"` list in `angular-cli.json` pointing to the theme
 file (e.g., `unicorn-app-theme.scss`).
 
 If you're not using the Angular CLI, you can use any existing Sass tooling to build the file (such
@@ -87,8 +87,8 @@ and then include the output file in your application.
 The theme file can be concatenated and minified with the rest of the application's css.
 
 #### Multiple themes
-You can extend the example above to define a second (or third or fourth) theme that is gated by 
-some selector. For example, we could append the following to the example above to define a 
+You can extend the example above to define a second (or third or fourth) theme that is gated by
+some selector. For example, we could append the following to the example above to define a
 secondary dark theme:
 ```scss
 .unicorn-dark-theme {
@@ -97,7 +97,7 @@ secondary dark theme:
   $dark-warn:    md-palette($md-deep-orange);
 
   $dark-theme: md-dark-theme($dark-primary, $dark-accent, $dark-warn);
-  
+
   @include angular-material-theme($dark-theme);   
 }
 ```
@@ -105,28 +105,8 @@ secondary dark theme:
 With this, any element inside of a parent with the `unicorn-dark-theme` class will use this
 dark theme.
 
-### Styling your own components
-In order to style your own components with our tooling, the component's styles must be defined 
-with Sass. 
-
-You can consume the theming functions and variables from the @angular/material/core/theming. You can use the `md-color` function to extract a specific color from a palette. For example:
-
-```scss
-// Import theming functions and variables
-@import '~@angular/material/core/theming/all-theme';
-// Import a pre-built theme
-@import '~@angular/material/core/theming/prebuilt/deep-purple-amber';
-
-// Use md-color to extract individual colors from a palette as necessary.
-.candy-carousel {
-  background-color: md-color($primary);
-  border-color: md-color($accent, A400);
-}
-```
-
-You can see a more complete example in [theming-your-components.md][2]
-
-[2]: https://github.com/angular/material2/blob/master/docs/theming-your-components.md
+### Theming your own components
+For more details about theming your own components, see [theming-your-components.md](https://github.com/angular/material2/blob/master/docs/theming-your-components.md)
 
 ### Future work
 * Once CSS variables (custom properties) are available in all the browsers we support,

From eb916d38a136aacd4793cac5c12605e092c35abb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bruno=20da=20Silva=20jo=C3=A3o?= <bruno@tzadi.com>
Date: Fri, 14 Oct 2016 10:21:25 -0300
Subject: [PATCH 14/16] Update theming-your-components.md

Clean up
---
 docs/theming-your-components.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/theming-your-components.md b/docs/theming-your-components.md
index 5bc9bb6de544..6b2c6a452782 100644
--- a/docs/theming-your-components.md
+++ b/docs/theming-your-components.md
@@ -47,7 +47,7 @@ For more details about the theming functions, see the comments in the
 ### Best practices using `@mixin`
 When using `@mixin`, the theme file should only contain the definitions that are affected by the passed-in theme.
 
-All styles that are not affected by the theme should be placed in a `component.scss` file. This file should contain sizes, transitions, positioning and everything that is not affected by the theme.
+All styles that are not affected by the theme should be placed in a `component.scss` file. This file should contain everything that is not affected by the theme like sizes, transitions...
 
 Styles that are affected by the theme should be placed in a separated theming file as `component-theme.scss`. This file should contain the `@mixin` function responsible for applying the theme to the component.
 

From 0e1f1a7fd64ffbe292359af8f9c327215abc19ec Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bruno=20da=20Silva=20jo=C3=A3o?= <bruno@tzadi.com>
Date: Mon, 17 Oct 2016 09:08:11 -0200
Subject: [PATCH 15/16] Update theming-your-components.md

Improved @mixin file name to match the candy-carousel example.
---
 docs/theming-your-components.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/theming-your-components.md b/docs/theming-your-components.md
index 6b2c6a452782..d081d89ef775 100644
--- a/docs/theming-your-components.md
+++ b/docs/theming-your-components.md
@@ -47,9 +47,9 @@ For more details about the theming functions, see the comments in the
 ### Best practices using `@mixin`
 When using `@mixin`, the theme file should only contain the definitions that are affected by the passed-in theme.
 
-All styles that are not affected by the theme should be placed in a `component.scss` file. This file should contain everything that is not affected by the theme like sizes, transitions...
+All styles that are not affected by the theme should be placed in a `candy-carousel.scss` file. This file should contain everything that is not affected by the theme like sizes, transitions...
 
-Styles that are affected by the theme should be placed in a separated theming file as `component-theme.scss`. This file should contain the `@mixin` function responsible for applying the theme to the component.
+Styles that are affected by the theme should have a `_` before the name and should be placed in a separated theming file as `_candy-carousel-theme.scss`. This file should contain the `@mixin` function responsible for applying the theme to the component.
 
 
 ## Using colors from a pallete

From eda28bbb64a99c88f520461a0b2b7f9bef0ccf04 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bruno=20da=20Silva=20jo=C3=A3o?= <bruno@tzadi.com>
Date: Mon, 17 Oct 2016 09:10:28 -0200
Subject: [PATCH 16/16] Update theming-your-components.md

Improved `@mixin` paragraph.
---
 docs/theming-your-components.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/theming-your-components.md b/docs/theming-your-components.md
index d081d89ef775..6481e5e222fe 100644
--- a/docs/theming-your-components.md
+++ b/docs/theming-your-components.md
@@ -49,7 +49,7 @@ When using `@mixin`, the theme file should only contain the definitions that are
 
 All styles that are not affected by the theme should be placed in a `candy-carousel.scss` file. This file should contain everything that is not affected by the theme like sizes, transitions...
 
-Styles that are affected by the theme should have a `_` before the name and should be placed in a separated theming file as `_candy-carousel-theme.scss`. This file should contain the `@mixin` function responsible for applying the theme to the component.
+Styles that are affected by the theme should be placed in a separated theming file as `_candy-carousel-theme.scss` and the file should have a `_` before the name. This file should contain the `@mixin` function responsible for applying the theme to the component.
 
 
 ## Using colors from a pallete