docs(): add docs for new devs to get started.

Author: jelbourn

DEV_ENVIRONMENT.md

@@ -0,0 +1,22 @@
+# Developer guide: getting your environment set up
+
+1. Make sure you have `node` installed with a version at _least_ 4.2.3.
+2. Run `npm install -g angular-cli` to install the Angular CLI.
+3. Fork the `angular/material2` repo. 
+4. Clone your fork. 
+   Recommendation: name your git remotes `upstream` for `angular/material2`
+   and `<your-username>` for your fork. Also see the [team git shortcuts](https://github.com/angular/material2/wiki/Team-git----bash-shortcuts).
+5. From the root of the project, run `npm install`
+
+
+To build the project, run `ng build`. 
+To watch for changes and automatically rebuild, run `ng build --watch`
+
+To bring up a local server, run `ng serve`. This will automatically watch for changes and rebuild.
+After the changes rebuild, the browser currently needs to be manually refreshed.
+
+To run unit tests, run `ng test`.
+
+Running e2e tests: <not yet implemented>
+Running benchmarks: <not yet implemented>
+Running screenshot diff tests: <not yet implemented>

docs/scss-theming.md

@@ -0,0 +1,43 @@
+# 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:
+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.

src/core/style/_palette.scss

@@ -374,6 +374,10 @@ $md-dark-theme-foreground: (
 );
 
 
+
+// TODO(jelbourn): Do we actually need these any more? Updates to the spec about how foreground
+// colors are used may have made this obsolete.
+
 // Contrast colors. These are hard-coded because it is too difficult (probably impossible) to
 // calculate them. These contrast colors are pulled from the public Material Design spec swatches.
 // While the contrast colors in the spec are not perscriptive, we will use them for convenience.