Theming your own component doc incorrectly references pre-built theme

Bug, feature request, or proposal:

Bug/Incorrect Documentation

What is the expected behavior?

According to the theming your components documentation you should be able to use pre-built themes with your custom components

// Import a pre-built theme
@import '~@angular/material/prebuilt-themes/deeppurple-amber.css';
// 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);

What is the current behavior?

The Sass compiler throws an error : Undefined variable: "$theme"

What are the steps to reproduce?

Componet Theme scss:

@import '~@angular/material/theming';

@mixin my-component-theme($theme) {
    $primary: map-get($theme, primary);
    my-component{
        background-color: mat-color($primary);
    }
}

Styles.scss

@import '~@angular/material/prebuilt-themes/indigo-pink.css';
@import './path/to/my-component.theme';
@include my-component-theme($theme);

What is the use-case or motivation for changing an existing behavior?

While this isn’t as much of a problem with components that are defined in an application as you can define your own theme, it IS a major issue when creating component libraries that will be consumed by other applications that may choose to use a pre-built theme.

Which versions of Angular, Material, OS, TypeScript, browsers are affected?

Angular: 4.1.3 Material: Beta 6

Is there anything else we should know?

[michael-gregson]

Thank you all to the contributions to this thread, after fighting with the docs this was a very useful resource. I would appreciate confirmation that my understanding of the approach is correct, and specifically does not import the mat-core and angular-material-theme multiple times.

theme_variables.scss

@import '~@angular/material/theming';

// Define the palettes for your theme using the Material Design palettes available in palette.scss
$app-primary: mat-palette($mat-blue-grey);
$app-accent:  mat-palette($mat-grey);
$app-warn:    mat-palette($mat-deep-orange);

// Custom Sass colors vars (will be available in all the project)
$primary: mat-color($app-primary);
$accent: mat-color($app-accent);
$warn: mat-color($app-warn);

theme.scss

@import '~@angular/material/theming';
@import "~theme_variables.scss";

@include mat-core();
$app-theme: mat-light-theme($app-primary, $app-accent, $app-warn);
@include angular-material-theme($app-theme);

styles.scss

@import "theme.scss";

...

nav.component.scss

@import "~theme_variables.scss";

.primary {
    color: $primary;
}

.angular-cli.json

"styles": [
   "styles.scss"
]

I suppose my concern is that the nav component imports the theme_variables which imports angular/material/theming but I cannot see how to accomplish without.

[bezysoftware]

I must agree that the docs behind theming custom components are pretty confusing.

I want to create a custom component (much like angular button etc.) which would work with the current theme’s $primary & $accent colors. This component would be packaged and then consumed by target app (so the component should not have a theme, but use the theme of target app).

So what is the correct way to do this?