Color is a big part of any application. Ember paper allows you to customize how your app is colored based on your configuration. Sensible defaults are included.

Changing default theme

A theme is a collection of palettes. Each palette corresponds to an "intention". An ember-paper theme has palettes for primary, accent and warn intentions.

To customize the default theme, you can override the sass variables for each intention:

// app.scss

// Define desired color palettes for each intention.
$primary: "teal";
$accent: "light-green";
$warn: "pink";

// Import ember-paper.
@import "ember-paper";

// Import or define the rest of your application's styles.

As you can see, you can just specify a name string for the palette you want, if that palette is one of the included ones. If the default included palettes are all you care about, this is all you need.

Included palettes

By default, Ember paper ships with all palettes from the material design spec built in. Valid palettes include:

• red
• pink
• purple
• deep-purple
• indigo
• blue
• light-blue
• cyan
• teal
• green
• light-green
• lime
• yellow
• amber
• orange
• deep-orange
• brown
• grey
• blue-grey

Creating custom palettes

A palette is a collection of hues of a color. You can create such a collection yourself using sass maps. ember-paper expects a palette color map to have the keys 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, A100, A200, A400 and A700.

Each number means a "stronger" shade of the palette, and the "A" prefixed keys are used when the palette is the accent palette.

A palette should also have the contrast information. You can do that using the contrastDefaultColor, contrastLightColors and contrastStrongLightColors keys. contrastLightColors has a list of the keys where a light color contrast is applied. contrastStrongLightColors has a list of the keys where a dark color contrast is applied. Any other key will use the color on the contrastDefaultColor key.

Here is the definition of the "teal" palette, applied to the primary intention:

$primary: (
  '50': #e0f2f1,
  '100': #b2dfdb,
  '200': #80cbc4,
  '300': #4db6ac,
  '400': #26a69a,
  '500': #009688,
  '600': #00897b,
  '700': #00796b,
  '800': #00695c,
  '900': #004d40,
  'A100': #a7ffeb,
  'A200': #64ffda,
  'A400': #1de9b6,
  'A700': #00bfa5,
  'contrastDefaultColor': $dark-contrast-color,
  'contrastLightColors': ('500', '600', '700', '800', '900'),
  'contrastStrongLightColors': ('500', '600', '700')
);

You can find some material palette generators online. Example: http://mcg.mbitson.com/.

Using colors in your styles

ember-paper provides two sass functions that you can use to hook more easily into the provided palettes:

paper-color($palette, $shade) sass function takes a palette or palette name and a shade/tint and returns its color. If no shade is specified, the default is '500'.

paper-contrast-color($palette, $shade) sass function works very similarly, but returns the correct contrast color instead of the color itself. This is useful for placing text on top of a color or whenever you need a color for legibility/contrast purposes.

Here is an example of using these functions:

.my-component {
  color: paper-contrast-paper-color($primary, '500');
  background-color: paper-color($primary, '200');
}

.oh-dear {
  background-color: paper-color($warn, 'A100');
}

Changing themes at runtime

Sometimes we have more complex requirements for when or where to use colors in our app. ember-paper provides a paper-theme service that allows you to install or uninstall themes at runtime.

You can use these controls to change the theme at runtime. Feel from to navigate to other routes of the demo after installing a custom theme.

Primary palette pink

Accent palette green

Warn palette red

Install Theme

Uninstall Theme

Here is the code used for these actions:

installTheme() {
  this.paperTheme.installTheme('main', {
    primary: this.primary.palette,
    accent: this.accent.palette,
    warn: this.warn.palette
  });
},

uninstallTheme() {
  this.paperTheme.uninstallTheme('main');
}

Browser support

Ember-paper uses css variables under the hood for dynamically installed themes. While most browsers support this feature, IE does not. Ember-paper always uses fallback css rules with values from the sass defined theme, so it degrades gracefully to the default theme on IE.

With that being said, you are encouraged to always provide fallback values yourself on your own custom styles. For this purpose, ember-paper provides a paper-var(--var-name) function. Here is an example of using such fallback values:

.site-sidenav {
  background-color: paper-color($primary, '400');
  background-color: paper-var(--primary-400);

  md-toolbar {
    background: linear-gradient(to bottom, paper-color($primary, '600'), paper-color($primary, '400'));
    background: linear-gradient(to bottom, paper-var(--primary-600), paper-var(--primary-400));
  }
}

// this compiles to:

.site-sidenav {
  background-color: #ff7043;
  background-color: RGB(var(--primary-400));

  md-toolbar {
    background: linear-gradient(to bottom, #f4511e, #ff7043);
    background: linear-gradient(to bottom, RGB(var(--primary-600)), RGB(var(--primary-400)));
  }
}

Generating palettes based on a color

Ember-paper provides an utility to automatically generate palettes based on a single color. This can be very useful if, for example, you want to allow the user to customize the app's colors but still want to abstract away the complexity of creating a palette with all its hues.

While nothing beats a manual color selection and tuning, this tool does a pretty decent job in the vast majority of the cases.

To use the utility simply import the function import generatePalette from 'ember-paper/utils/generate-theme';. You can then use the function to create a palette like generatePalette('#326eb6');.

Generated themes are of course compatible with the paper-theme service method installTheme. So you can install any generated palette right away!