From 379a57fe0d7908dc44ea5a9099473d29d2ecc093 Mon Sep 17 00:00:00 2001 From: Jeremy Elbourn Date: Thu, 15 Sep 2016 14:51:36 -0700 Subject: [PATCH] docs(theming): add initial guide for theming. (#1246) --- docs/scss-theming.md | 45 --------------- docs/theming.md | 127 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 127 insertions(+), 45 deletions(-) delete mode 100644 docs/scss-theming.md create mode 100644 docs/theming.md diff --git a/docs/scss-theming.md b/docs/scss-theming.md deleted file mode 100644 index 488be9d8074..00000000000 --- a/docs/scss-theming.md +++ /dev/null @@ -1,45 +0,0 @@ -# Theming components with SCSS -ng-material comes packaged with the [color palettes in the Material Design spec](https://www.google.com/design/spec/style/color.html#color-color-palette). -The palettes are in `_palette.scss`. -Each will be a SCSS map: -$md-indigo: ( - 50: #e8eaf6, - 100: #c5cae9, - 200: #9fa8da, - ... -); - -A theme, then, is a _set_ of palettes defined in terms of these (or custom) color palettes: - -```scss -/** A typical theme definition file. */ - -$md-is-dark-theme: false; - -$md-primary: md-palette($md-indigo, 500, 100, 700, $md-contrast-palettes); -$md-accent: md-palette($md-red, A200, A100, A400, $md-contrast-palettes); -$md-warn: md-palette($md-red, 500, 300, 800, $md-contrast-palettes); -$md-foreground: if($md-is-dark-theme, $md-dark-theme-foreground, $md-light-theme-foreground); -$md-background: if($md-is-dark-theme, $md-dark-theme-background, $md-light-theme-background); -``` - -The md-palette function creates a theme palette that contains all the colors of the original color -palette plus contrast colors and semantic shortcuts for the specified hues. - - -Once that is defined, an individual component is styled in terms of the theme palettes: -```scss -my-comp { - color: md-color($md-foreground, text); - background-color: md-color($md-background, lighter); // Use one of the configured hue by semantic name. - &.md-primary { - color: md-color($md-primary, 300-contrast); - background-color: md-color($md-primary, 300, 0.7); // Use a specific hue and opacity - } -} -``` - -The md-color function lets the user reference a specific color from the theme palette, -either by a semantic name (e.g., "primary, lighter"), or directly by numbered hue -(e.g., "accent, A700"). For each hue, a "-contrast" version is also present in the theme palette. -The function also allows the user to specify an opacity. diff --git a/docs/theming.md b/docs/theming.md new file mode 100644 index 00000000000..183b966bc1c --- /dev/null +++ b/docs/theming.md @@ -0,0 +1,127 @@ +# Theming your Angular Material app + + +### 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]. + +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. +* A warn palette: colors used to convey error state. +* A foreground palette: colors for text and icons. +* A background palette: colors used for element backgrounds. + +In Angular Material 2, all theme styles are generated _statically_ at build-time so that your +app doesn't have to spend cycles generating theme styles on startup. + +[1]: https://material.google.com/style/color.html#color-color-palette + +### 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. + +You can include a theme file directly into your application from +`@angular2-material/core/theming/prebuilt` + +If you're using Angular CLI, this is as simple as including one line +in your `style.css` file: +```css +@import '~@angular2-material/core/theming/prebuilt/deeppurple-amber.css'; +``` + +Alternatively, you can just reference the file directly. This would look something like +```html + +``` +The actual path will depend on your server setup. + +You can also concatenate the file with the rest of your application's css. + +### Defining a custom theme +When you want more customization than a pre-built theme offers, you can create your own theme file. + +A theme file is a simple Sass file that defines your palettes and passes them to mixins that output +the corresponding styles. A typical theme file will look something like this: +```scss +@import '~@angular2-material/core/theming/theming'; +@import '~@angular2-material/core/theming/palette'; +@import '~@angular2-material/core/core'; +@import '~@angular2-material/button/button-theme'; +// Plus imports for other components in your app. + +// Include the base styles for Angular Material core. We include this here so that you only +// have to load a single css file for Angular Material in your app. +@include md-core(); + +// 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); +$warn: md-palette($md-red); + +// Create the theme object (a Sass map containing all of the palettes). +$theme: md-light-theme($primary, $accent, $warn); + +// Include theme styles for core and each component used in your app. +@include md-core-theme($theme); +@include md-button-theme($theme); +// Plus includes for other components in your app. +``` + +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 +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 +as gulp-sass or grunt-sass). The simplest approach is to use the `node-sass` CLI; you simply run: +``` +node-sass src/unicorn-app-theme.scss dist/unicorn-app-theme.css +``` +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 +secondary dark theme: +```scss +.unicorn-dark-theme { + $dark-primary: md-palette($md-blue-grey); + $dark-accent: md-palette($md-amber, A200, A100, A400); + $dark-warn: md-palette($md-deep-orange); + + $dark-theme: md-dark-theme($dark-primary, $dark-accent, $dark-warn); + + @include md-core-theme($dark-theme); + @include md-button-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 `@angular2-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); +} +``` + +### Future work +* When the "all" package is released, there will be a mixin that captures all of the component's + theme styles so that you don't have to include them all individually. +* 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.