(docs) update theming.md

docs/theming-your-components.md

@@ -0,0 +1,56 @@
+#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 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
+
+```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
+
+```sass
+// Import all the tools needed to customize the theme and extract parts of it
+@import '~@angular/material/core/theming/all-theme';
+
+// 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);
+  }
+}
+```
+
+Now you just have have to call the @mixin function to apply the theme:
+
+```sass
+// 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/candy-carousel/candy-carousel-theme.scss';
+
+//Using the $theme variable from the pre-built theme you can call the theming function
+@include candy-carousel-theme($theme);
+```

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);   
 }
 ```
 
@@ -109,15 +109,25 @@ 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 `md-color` function to extract a specific color from a palette. For example:
+
 ```scss
-.unicorn-carousel {
+// 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);
-  color: md-color($primary, default-contrast);
+  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
+
 ### 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.