Cleaned up and changed as @jelbourn suggested

Author: brunonp

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,15 +29,41 @@ 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
 @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
+// 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);
+}
+```

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,36 +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);   
 }
 ```
 
 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,