From 0359c5eb7069dd7a0383ee74ad66b41c8589445f Mon Sep 17 00:00:00 2001
From: Jeremy Elbourn <jelbourn@google.com>
Date: Tue, 9 Feb 2016 10:34:27 -0800
Subject: [PATCH] docs(): add docs for new devs to get started.

---
 DEV_ENVIRONMENT.md           | 22 ++++++++++++++++++
 docs/scss-theming.md         | 43 ++++++++++++++++++++++++++++++++++++
 src/core/style/_palette.scss |  4 ++++
 3 files changed, 69 insertions(+)
 create mode 100644 DEV_ENVIRONMENT.md
 create mode 100644 docs/scss-theming.md

diff --git a/DEV_ENVIRONMENT.md b/DEV_ENVIRONMENT.md
new file mode 100644
index 00000000000..6252a1b3566
--- /dev/null
+++ b/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>
diff --git a/docs/scss-theming.md b/docs/scss-theming.md
new file mode 100644
index 00000000000..d2a385da61f
--- /dev/null
+++ b/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.
diff --git a/src/core/style/_palette.scss b/src/core/style/_palette.scss
index f05d85e89f0..ed0aff502a6 100644
--- a/src/core/style/_palette.scss
+++ b/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.