Rebase against master

docs/_assets/main.css

@@ -71,7 +71,8 @@ body:not(.about) .docs-layout .docs-layout-header.mdl-layout__header {
   background-image: url('templates.png');
   background-size: auto 29px;
 }
-.started .docs-layout-header.mdl-layout__header {
+.started .docs-layout-header.mdl-layout__header,
+.faq .docs-layout-header.mdl-layout__header {
   background-color: #2E2E2E;
   background-image: url('logo.png');
   background-size: auto 32px;
@@ -215,7 +216,7 @@ body:not(.about) .mdl-navigation__link.download > button {
 .started .docs-navigation .started,
 .styles .docs-navigation .styles,
 .components .docs-navigation .components,
-.styles .docs-navigation .styles,
+.faq .docs-navigation .faq,
 .customize .docs-navigation .customize {
   opacity: 1;
   border-bottom-color: #18FFFF;
@@ -1122,3 +1123,90 @@ code[class*=language-], pre[class*=language-] {
   margin-top: 16px;
   margin-bottom: 16px;
 }
+
+
+/* faq */
+.faq img {
+  max-width: 100%;
+}
+.faq .mdl-tabs__tab-bar {
+  justify-content: flex-start;
+  border-bottom: 0;
+}
+.faq .mdl-tabs.is-upgraded .mdl-tabs__tab.is-active {
+  color: #00ACC1;
+}
+.faq .mdl-tabs.is-upgraded .mdl-tabs__tab.is-active:after {
+  background-color: #00ACC1;
+}
+.faq .docs-layout-content {
+  text-align: center;
+}
+.faq .chapter-toc {
+  display: table;
+}
+.faq .content h3 {
+  display: table-cell;
+  width: 140px;
+  font-size: 15px;
+  font-weight: bold;
+  padding-right: 60px;
+  line-height: 25px;
+}
+.faq .content section {
+  margin-bottom: 30px;
+}
+.faq .section-content {
+  display: table-cell;
+}
+.faq .content {
+  padding: 40px;
+  display: inline-block;
+  text-align: left;
+}
+.faq .content p {
+  margin-top: 10px;
+  margin-bottom: 15px;
+}
+.faq .mdl-tabs {
+  margin-bottom: 22px;
+}
+.faq .content h4 {
+  font-size: 15px;
+  font-weight: bold;
+  margin-bottom: 5px;
+  margin-top: 20px;
+}
+.faq .content .mdl-tabs__panel {
+  padding-top: 10px;
+}
+.faq .caption {
+  font-size: 13px;
+  max-width: 640px;
+  box-sizing: border-box;
+  margin-top: 15px;
+  padding: 15px;
+  background-color: rgb(255, 255, 255);
+  border-radius: 3px;
+}
+.faq .caption h4 {
+  font-size: 13px;
+  font-weight: normal;
+  font-style: italic;
+  margin-top: 0;
+}
+.faq ol {
+  padding-left: 18px;
+  font-size: 13px;
+  max-width: 640px;
+  box-sizing: border-box;
+}
+.faq pre {
+  width: 640px;
+  box-sizing: border-box;
+  word-wrap: break-word;
+}
+.faq .snippet-group {
+  max-width: 640px;
+  margin: 60px 0 40px 0;
+}

docs/_pages/faq.md

@@ -0,0 +1,165 @@
+---
+layout: styles
+title: FAQ
+bodyclass: faq
+include_prefix: ../
+---
+
+<div class="docs-text-styling">
+  <section class="docs-toc">
+    <h3>Contents</h3>
+    <nav class="section-content">
+      <ul>
+        <li><a href="#where-should-i-use">Where should I use Material Design Lite (MDL)?</a></li>
+        <li><a href="#css-naming-conventions">What CSS naming conventions does MDL use?</a></li>
+        <li><a href="#progressive-enhancement">Does MDL support progressive enhancement?</a></li>
+        <li><a href="#browser-support">What browsers does MDL support?</a></li>
+        <li><a href="#polymer">Does MDL play nicely with Polymer?</a></li>
+        <li><a href="#bootstrap">Is MDL comparable to Twitter Bootstrap?</a></li>
+        <li><a href="#existing-implementations">How does it compare to existing Material CSS implementations?</a></li>
+        <li><a href="#options-available">Should I use the minified, CDN or Sass versions of MDL?</a></li>
+        <li><a href="#official-cdn">What service does the official CDN use?</a></li>
+        <li><a href="#web-starter-kit">How does MDL relate to Web Starter Kit?</a></li>
+        <li><a href="#mdl-in-production">Do any Google properties use MDL in production?</a></li>
+        <li><a href="#individual-components">Can I build or use individual MDL components (e.g a button)?</a></li>
+        <li><a href="#slide-decks">Are there any presentations or slide-decks available on MDL?</a></li>
+        <li><a href="#new-components">Can I request or contribute components to MDL?</a></li>
+      </ul>
+    </nav>
+  </section>
+
+<h2 id="where-should-i-use">Where should I use Material Design Lite (MDL)?</h2>
+
+If you’re interested in a [Material Design](www.google.com/design/spec/material-design/introduction.html) experience using vanilla Web technologies like CSS, JavaScript and HTML, MDL might be a useful option to consider. We optimise for websites heavy on content, such as marketing pages, articles, blogs and general web content that isn’t particularly app-y.  If you just want to pick some colors, customise a template and ship a Material experience, we try to help make that process simpler.
+
+Whilst there exist several community-driven options for Material Design (e.g Material Bootstrap, Materialize), our experience has shown that there are several gaps in the Material specification when it comes to the web. Rather than guessing how these gaps should be filled (something we know the community has struggled with), we’ve opted for a close collaboration with the Material Design team to provide a Material library that is both spec compatible for today and provides guidance on aspects of the spec still being evolved.
+
+<h2 id="css-naming-conventions">What CSS naming conventions does MDL use?</h2>
+
+MDL was written using [BEM](https://en.bem.info/method/). BEM stands for Block, Element, Modifier. It is a method used to construct CSS class-names so they are consistent, isolated, and expressive. A few good resources for learning more about BEM methods are:
+
+* [CSSWizardry](http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/)
+* [CSS-Tricks](https://css-tricks.com/bem-101/)
+* [Smashing Magazine](http://www.smashingmagazine.com/2012/04/16/a-new-front-end-methodology-bem/)
+
+These are great resources that simplify the data needed to understand BEM. If you want to read the methodology from the inventors, [Yandex provides the resource](https://en.bem.info/). This holds no bars and goes way beyond just the CSS and into the full JavaScript setup they use as well.
+
+Our [wiki](https://github.com/google/material-design-lite/wiki/Understanding-BEM) includes a section on the namespacing used for MDL specifically.
+
+<h2 id="progressive-enhancement">Does MDL support progressive enhancement?</h2>
+
+MDL’s components were designed from the ground up with progressive enhancement in mind. We attempt to build on native HTML elements as much as possible, relying on JavaScript where absolutely necessary for ‘enhancements’.
+
+One example of this is our ‘Text only’ Material Design template. Switching JavaScript off in Chrome DevTools, the page still renders CSS fine:
+
+![image alt text](../assets/image_0.png)
+
+This allows us to render important content first and then ‘enhance’ the page with things like Material Design button ripples and pop-out menu components.
+
+MDL will degrade to a no-JavaScript experience on IE9, though you can pull in polyfills for an enhanced experience. If components require JavaScript to function, such as Layout, these will otherwise need to be planned for in development. IE10+ and evergreen browsers are fully supported. For more details on our browser support, see ‘What browsers does MDL support?’.
+
+Note: the MDL site itself attempts to use progressive enhancement where possible. We do however have aspects of the site (e.g our component page) that rely more heavily on JS. The MDL Templates and Components otherwise try to render as well as they can with JS off.
+
+<h2 id="browser-support">What browsers does MDL support?</h2>
+
+The complete MDL experience should work in the last two versions of all evergreen browsers, whilst we gracefully degrade to CSS-only in browsers like IE9 that don’t pass our [Cutting-the-mustard](https://github.com/google/material-design-lite/blob/master/src/mdlComponentHandler.js#L262) test.
+
+Our [browser compatibility matrix](https://github.com/google/material-design-lite/#browser-support) has the most up to date information on the browsers we officially support. For components, at minimum we require support for [querySelector](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector),[classList](https://developer.mozilla.org/en-US/docs/Web/API/Element/classList) and [addEventListener](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener), which can be [polyfilled](https://github.com/Modernizr/Modernizr/wiki/HTML5-Cross-Browser-Polyfills) as needed. Our Templates will work in IE10+, primarily due to our use of Flexbox.
+
+The polyfills that we’re currently using for the MDL site to improve support in oldIE are the following:
+
+```html
+<!--[if IE]>
+<script src="//cdnjs.cloudflare.com/ajax/libs/es5-shim/4.1.7/es5-shim.min.js"></script>
+<script src="//cdnjs.cloudflare.com/ajax/libs/classlist/2014.01.31/classList.min.js"></script>
+<script src="//cdnjs.cloudflare.com/ajax/libs/selectivizr/1.0.2/selectivizr-min.js"></script>
+<![endif]-->
+```
+
+IE10 standards mode [removes](http://bit.ly/1dypChT) support for conditional comments, so the above will only get interpreted by older versions of IE, such as IE9.
+
+We do not officially support IE8. That said, some components will degrade using the CSS-only (or native HTML element) experience there better than others. For example:
+
+**Buttons**
+
+<img alt="Buttons rendering in IE8" src="../assets/image_1.png">
+
+**Tables**
+
+<img alt="Tables gracefully degrading in IE8" src="../assets/image_2.png">
+
+**Sliders (degrade to input fields)**
+
+<img alt="Sliders degrading in IE8 to input fields" src="../assets/image_3.png">
+
+<h2 id="polymer">Does MDL play nicely with Polymer? Is it a replacement for the Paper elements?</h2>
+
+MDL focuses on delivering an experience that is optimised for static content sites, like blogs, marketing pages and more traditional text-based web pages. <a href="http://polymer-project.org">Polymer</a> excels at helping compose web applications and sites requiring more advanced user interaction support. They are both good tools and should be evaluated based on your needs.
+
+That said, MDL can be used alongside the Polymer element counterparts. Polymer uses the power of Web Components to encapsulate the designs used for those components. MDL does not affect the styling within custom components.
+
+<h2 id="bootstrap">Is MDL comparable to Twitter Bootstrap?</h2>
+
+*If we're using it instead of Bootstrap, can we expect the same level of component styling?*
+
+Material Design can replace many parts of Bootstrap. However, it does not intend to feature-match everything Bootstrap offers. Instead MDL intends to implement the components specified by the Material Design specification. This allows it to provide the most comprehensive and accurate solution available.
+
+<h2 id="existing-implementations">How does it compare to existing Material CSS implementations?</h2>
+
+*Materialize, Material Bootstrap, etc*
+
+We think the community does a great job offering their own take on how Material Design should be implemented for CSS libraries.
+
+That said, large, diverse number of implementations available are often quite liberal with their interpretation of the spec (not their fault!) and their opinions don’t always reflect what the Material Design team would consider ‘correct’. MDL was developed in close collaboration with the Material Design and Chrome UX teams and undergoes regular reviews for spec compliance. When we run into an area of the spec that isn’t yet fully fleshed out, MDL is able to offer reviewed opinions on how these should be solved in a way that tries to stay true to Material Design.
+
+<h2 id="options-availale">Should I use the minified, CDN or Sass versions of MDL?</h2>
+
+*Should I build my own version or download the minified version or simply refer to CDN objects?*
+
+**Minified: **If it’s your first time using MDL, we recommend downloading one of the default packages from the ‘Getting Started’ page that include a minified version of our CSS/JS and optionally our pre-made Templates.
+
+**CDN: **If you’re just prototyping or want to avoid hosting your own copy of the MDL CSS and JS files, you can use our CDN to pull down a heavily edge-cached version.
+
+**Customiser: **If you’re creating a new site with MDL and are using a custom color scheme, we recommend downloading the default package then generating a custom build using the Customiser tool. You can use this to override the material.min.css file for your own needs.
+
+**Sass: **If you would prefer to go all in, you can get the Sass version of MDL, which includes our original sources, docs and templates. This version allows maximum customisation using CSS variables and the rest of the Sass goodness you’re used to.
+
+<h2 id="official-cdn">What service does the official CDN use?</h2>
+
+The official CDN is hosted using [Google Cloud Storage](https://cloud.google.com/storage/).
+
+<h2 id="web-starter-kit">How does MDL relate to Web Starter Kit?</h2>
+
+MDL is an evolutionary step from the styleguide provided in Web Starter Kit. The more [Web Starter Kit](https://developers.google.com/web/tools/starter-kit/) was used, the more it became clear that many developers simply wanted Material Design in their sites.
+
+The WSK Styleguide also did not align to Material Design fully, it was simply based on the idea. From the WSK project, MDL was born to try and fill this need for developers. In the process making the implementation as direct as possible to the specification.
+
+<h2 id="mdl-in-production">Do any Google properties use MDL in production?</h2>
+
+MDL is used in production by a few different Google properties. These use an older, incomplete version but demonstrate what deployed experiences can look like. Examples include:
+
+The [Google Services](https://developers.google.com/mobile/add) site:
+
+![image alt text](../assets/image_4.png)
+
+[RichMediaGallery](http://www.richmediagallery.com/) by DoubleClick
+
+![image alt text](../assets/image_5.png)
+
+and is being used by many other teams on upcoming projects, including Google Shopping.
+
+<h2 id="#individual-components">Can I build or use individual MDL components (e.g a button)?</h2>
+
+For V1 of MDL we are focused on the use-case of folks who are likely to need a few different components on their page and will want to include most of the MDL library. This means that support and docs around just plucking single components on their own is minimal.
+
+That said, if you need to generate a build using just a single (or smaller number of) components, you will need to use Gulp with our Sass build. You can [comment out](https://github.com/google/material-design-lite/blob/master/src/material-design-lite.scss) those components you don’t need in material-design-lite.scss, [comment out](https://github.com/google/material-design-lite/blob/master/gulpfile.js#L191) the scripts you don’t need in the Gulpfile and then run `gulp` to create your build.
+
+We have talked about offering up components in a more modular fashion but will be exploring this in the post V1 timeline.
+
+## Are there any presentations or slide-decks available on MDL?
+
+We did a preview talk at Google I/O 2015 on MDL and the slides for that talk can be found on [SpeakerDeck](https://speakerdeck.com/gauntface/material-design-lite-preview).
+
+<h2 id="new-components">Can I request or contribute components to MDL?</h2>
+
+We’ll be trying to ship new components to MDL based on the availability of a reliable section in the Material Design spec covering it (for Web). We also factor in the usefulness of implementing it to our users.

docs/_templates/layout.html

@@ -56,6 +56,7 @@
           <a href="{{page.include_prefix}}components/index.html" class="mdl-navigation__link components">Components</a>
           <a href="{{page.include_prefix}}styles/index.html" class="mdl-navigation__link styles">Styles</a>
           <a href="{{page.include_prefix}}customize/index.html" class="mdl-navigation__link customize">Customize</a>
+          <a href="{{page.include_prefix}}faq/index.html" class="mdl-navigation__link faq">FAQ</a>
           <div class="spacer"></div>
           <a href="https://github.com/google/material-design-lite" class="mdl-navigation__link mdl-navigation__link--icon github"><i class="material-icons">link</i><span>GitHub</span></a>
           <a href="{{page.include_prefix}}started/index.html#download" class="mdl-navigation__link mdl-navigation__link--icon download">