(docs) update theming.md

docs/theming-your-components.md

@@ -0,0 +1,69 @@
+#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.
+
+## Using `@mixin` to automatically apply a theme
+
+### 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.
+
+### 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.
+
+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);
+```
+
+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 `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 `_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
+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);
+}
+```

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,26 +97,16 @@ 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);   
+
+  @include angular-material-theme($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
-.unicorn-carousel {
-  background-color: md-color($primary);
-  color: md-color($primary, default-contrast);
-}
-```
+### 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,