docs: Fix and finalize all READMEs and package.json files (#98)

- Add instructions to main README to get up and running quickly
- Amend Contributing guidelines to point to overall Material Components
  Contributing guidelines
- Ensure that all package.json files for components have repository,
  license, and description keys.
- Add installation instructions for every component README

Author: traviskaufman

CONTRIBUTING.md

@@ -1,9 +1,10 @@
 # Contributing to Material Components Web (MDC-Web)
 
-We'd love for you to contribute to our source code and to make Material Components Web even better than it is today! Here are the guidelines we'd like you to follow:
+We'd love for you to contribute and make Material Components for the web even better than it is today!
+Here are the guidelines we'd like you to follow:
 
 
-- [Code of Conduct](#code-of-conduct)
+- [General Contributing Guidelines](#general-contributing-guidelines)
 - [Development Process](#development-process)
   - [Setting up your development environment](#setting-up-your-development-environment)
   - [Building Components](#building-components)
@@ -12,17 +13,13 @@ We'd love for you to contribute to our source code and to make Material Componen
   - [Linting / Testing / Coverage Enforcement](#linting--testing--coverage-enforcement)
     - [Running Tests across browsers](#running-tests-across-browsers)
   - [Coding Style](#coding-style)
-  - [Signing the CLA](#signing-the-cla)
   - [Submitting Pull Requests](#submitting-pull-requests)
   - [Releasing MDC-Web](#releasing-mdc-web)
-- [Questions / Problems](#questions--problems)
-- [Issues / Bugs](#issues--bugs)
 - ["What's the core team up to?"](#whats-the-core-team-up-to)
 
-## Code of Conduct
+## General Contributing Guidelines
 
-We follow the [Material Components Code of Conduct](https://github.com/material-components/material-components/blob/develop/CONDUCT.md), and expect the same from all of our
-community members.
+The Material Components contributing policies and procedures can be found in the main Material Components documentation repository’s [contributing page](https://github.com/material-components/material-components/blob/develop/CONTRIBUTING.md).
 
 ## Development Process
 
@@ -103,19 +100,9 @@ Alternatively, you can run `npm run test:watch` and manually open browsers / use
 
 Our entire coding style is enforced automatically through the use of linters. Check out our [eslint config](https://github.com/material-components/material-components-web/blob/master/.eslintrc.yaml) (heavily influenced by [Google's Javascript Styleguide][js-style-guide]) as well as our [stylelint config][css-style-guide] (heavily annotated, with justifications for each rule) for further details.
 
-### Signing the CLA
-
-Please sign our Contributor License Agreement (CLA) before sending pull requests. For any code
-changes to be accepted, the CLA must be signed. It's a quick process, we promise!
-
-* For individuals we have a [simple click-through form][individual-cla].
-* For corporations we'll need you to
-  [print, sign and one of scan+email, fax or mail the form][corporate-cla].
-
-
 ### Submitting Pull Requests
 
-We prefer small, incremental changes over large, sweeping ones, so please try to adhere to this when submitting PRs. Also, make sure you're following our commit message conventions (which are the same as [angular's](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#commit)); our `commit-msg` hook should automatically enforce this. We also support [commitizen](https://www.npmjs.com/package/commitizen), which you can
+When submitting PRs, make sure you're following our commit message conventions (which are the same as [angular's](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#commit)); our `commit-msg` hook should automatically enforce this. We also support [commitizen](https://www.npmjs.com/package/commitizen), which you can
 use to auto-format commit messages for you.
 
 If you've done some experimental work on your branch/fork and committed these via `git commit --no-verify`, you can rebase them into one correctly-formatted commit before submitting.
@@ -124,10 +111,6 @@ Finally, it helps to make sure that your branch/fork is up to date with what's c
 
 > **NOTE**: Please do _not merge_ master into your branch. _Always_ `pull --rebase` instead. This ensures a linear history by always putting the work you've done after the work that's already on master, regardless of the date in which those commits were made.
 
-To submit code, open a PR for your fork/branch against `master`.
-
-Once you've submitted a PR, it'll be assigned to a core team member for review. If all CI tests pass and you get a `LGTM` from a reviewer, your code will be merged into master.
-
 ### Releasing MDC-Web
 
 > NOTE: This section is for collaborators only. Contributors without repo write access can ignore
@@ -148,40 +131,12 @@ To release MDC-Web, you should perform the following steps.
    current release of the overarching `material-components-web` library, and commit those changes.
 4. Push the changelog changes to master, and call it a day!
 
-## Questions / Problems
-
-If you have questions about how to use Material Components Web, please direct these to [StackOverflow][stackoverflow] and use the `material-components-web` tag.
-
-If you feel that we're missing an important bit of documentation, feel free to
-file an issue so we can help. Here's an example to get you started:
-
-```
-Component (if any):
-
-What are you trying to do or find out more about?
-
-Where have you looked?
-
-Where did you expect to find this information?
-```
-
-## Issues / Bugs
-
-If you find a bug in the source code or a mistake in the documentation, you can help us by
-submitting an issue to our [GitHub Repository][github]. Even better, you can submit a Pull Request with a fix. Before submitting issues, please ensure that you've read through our [issue template](https://github.com/material-components/material-components-web/blob/master/.github/ISSUE_TEMPLATE.md) to ensure a fast and helpful response from the maintainers.
-
 ## "What's the core team up to?"
 
 The core team maintains a [public Pivotal Tracker](https://www.pivotaltracker.com/n/projects/1664011) (**tracker** for short) which details all the items we're working on within our current two-week [iteration](https://www.agilealliance.org/glossary/iteration/). This tracker mirrors in what's in our GH issues. It is used _purely for planning and prioritization purposes, **not** for discussions or community issue filing_. That being said, it's a great place to look at the overall state of our project as well as some the big ticket issues we're working on.
 
 Each tracker story contains a link to its corresponding GH issue within its description. Each GH issue present in tracker is tagged with an `in-tracker` label. This will hopefully make it easy to move between the two if so desired.
 
 
-[github]: https://github.com/material-components/material-components-web
-[individual-cla]: http://code.google.com/legal/individual-cla-v1.0.html
-[corporate-cla]: http://code.google.com/legal/corporate-cla-v1.0.html
 [js-style-guide]: https://google.github.io/styleguide/jsguide.html
 [css-style-guide]: https://github.com/material-components/material-components-web/blob/master/.stylelintrc.yaml
-[jsbin]: http://jsbin.com/
-[stackoverflow]: http://stackoverflow.com/questions/tagged/material-components-web
-[global-gitignore]: https://help.github.com/articles/ignoring-files/#create-a-global-gitignore

README.md

@@ -1,6 +1,6 @@
 # Material Components for the web
 
-Material Components for the web (MDC-Web) help developers execute [Material Design](https://www.material.io). 
+Material Components for the web (MDC-Web) help developers execute [Material Design](https://www.material.io).
 Developed by a core team of engineers and UX designers at Google, these components enable a reliable development workflow to build beautiful and functional web projects.
 
 Material Components for the web is the successor to [Material Design Lite](https://getmdl.io/), and has 3 high-level goals:
@@ -9,18 +9,114 @@ Material Components for the web is the successor to [Material Design Lite](https
 - Best-in-class performance and adherence to the [Material Design guidelines](https://material.google.com)
 - Seamless integration with other JS frameworks and libraries
 
-## Useful Links
+## Quick start
 
-- [Developer's Guide](docs/developer.md)
-- [All Components](packages/)
-- [Demos](demos/)
-- [Framework Integration Examples](framework-examples/)
-- [Contributing](CONTRIBUTING.md)
-- [MDC-Web on Stack Overflow](https://stackoverflow.com/questions/tagged/material-components+web)
-- [Material.io](https://www.material.io) (external site)
-- [Material Design Guidelines](https://material.google.com) (external site)
+Install the library
+
+```
+npm install --save material-components-web
+```
+
+Then simply include the correct files, write some HTML, and call `mdc.autoInit()` within a closing
+`<script>` tag.
+
+```html
+<!DOCTYPE html>
+<html class="mdc-typography">
+  <head>
+    <title>Material Components for the web</title>
+    <link rel="stylesheet"
+          href="node_modules/material-components-web/dist/material-components-web.css">
+  </head>
+  <body>
+    <h2 class="mdc-typography--display2">Hello, Material Components!</h2>
+    <div class="mdc-textfield" data-mdc-auto-init="MDCTextfield">
+      <input type="text" class="mdc-textfield__input" id="demo-input">
+      <label for="demo-input" class="mdc-textfield__label">Tell us how you feel!</label>
+    </div>
+    <script src="node_modules/material-components-web/dist/material-components-web.js"></script>
+    <script>mdc.autoInit()</script>
+  </body>
+</html>
+```
+
+That's all there is to it! This is the easiest way to get up and running with Material Components
+for web. Check out our [Getting Started guide](./docs/getting-started.md) for a more in-depth
+introduction to the library.
+
+## Installing invidual components
+
+MDC-Web is modular by design. Each component lives within its own packages under the
+[@material npm scope](https://www.npmjs.com/~material).
+
+```
+npm install --save @material/button @material/card @material/textfield @material/typography
+```
+
+All our components can be found in the [packages](./packages) directory. Each component has a
+README documenting installation and usage.
+
+## Including components
+
+### Javascript
+
+If you are using a module loader such as Webpack or SystemJS to load your JS modules, you can simply
+`import` every component you need from `material-components-web` and use it as such.
+
+```js
+import {checkbox as mdcCheckbox} from 'material-components-web';
+
+const {MDCCheckbox, MDCCheckboxFoundation} = mdcCheckbox;
+// Use MDCCheckbox and/or MDCCheckboxFoundation
+```
 
-## Getting Started
+You can do the same with individual components
+
+```js
+import {MDCCheckbox, MDCCheckboxFoundation} from '@material/checkbox';
+// Use MDCCheckbox and/or MDCCheckboxFoundation
+```
+
+We also provide [UMD](http://bob.yexley.net/umd-javascript-that-runs-anywhere/) bundles for both `material-components-web` as
+well as all individual components.
+
+```js
+const {checkbox: mdcCheckbox} = require('material-components-web/dist/material-components-web');
+// Use mdcCheckbox
+
+const {MDCCheckbox, MDCCheckboxFoundation} = require('@material/checkbox/dist/mdc.checkbox');
+// Use MDCCheckbox, MDCCheckboxFoundation
+```
+
+When no module system is used, every component is added under the global `mdc` namespace. This
+occurs regardless of whether or not the entire library or the individual components are used.
+
+Every component also ships with a minified version of its UMD bundle, which can be found at
+`dist/mdc.COMPONENT.min.js`.
+
+### CSS
+
+All components which include styles provide them at `dist/mdc.COMPONENT.css`, as well as a
+complementary minified version at `dist/mdc.COMPONENT.min.css`. Note that _CSS files for a
+component's dependencies are not included within the component's CSS file_, so if you are using
+individual components you'll have to include each separately.
+
+Each component also comes with a Sass source file that can be included in your application's Sass
+
+```scss
+// Using the whole library
+@import 'material-components-web';
+
+// Using individual components / mixins
+@import '@material/checkbox';
+@import '@material/typography';
+@import '@material/elevation/mixins'; // Mixins for elevation.
+```
+
+> NOTE: The components' sass files expect that the `node_modules` directory containing the
+`@material` scope folder is present on the sass include path.
+
+## Running the demos
 
 Setup the repo:
 
@@ -37,6 +133,16 @@ npm run dev
 open http://localhost:8080
 ```
 
+## Useful Links
+
+- [Developer's Guide](docs/developer.md)
+- [All Components](packages/)
+- [Demos](demos/)
+- [Framework Integration Examples](framework-examples/)
+- [Contributing](CONTRIBUTING.md)
+- [Material.io](https://www.material.io) (external site)
+- [Material Design Guidelines](https://material.google.com) (external site)
+
 ## Browser Support
 
 - Chrome

packages/material-components-web/README.md

@@ -5,7 +5,9 @@ sibling packages up into one comprehensive library for convenience.
 
 ## Installation
 
-> Installation via npm will be available post-alpha.
+```
+npm install --save material-components-web
+```
 
 ## Usage
 

packages/material-components-web/package.json

@@ -1,9 +1,13 @@
 {
   "name": "material-components-web",
-  "description": "Production-quality UI components for the web platform",
+  "description": "Modular and customizable Material Design UI components for the web",
   "version": "0.1.0",
   "license": "Apache-2.0",
   "main": "index.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/material-components/material-components-web"
+  },
   "dependencies": {
     "@material/animation": "^0.1.0",
     "@material/auto-init": "^0.1.0",

packages/mdc-animation/README.md

@@ -4,7 +4,9 @@ mdc-animation is a sass / css library which provides variables, mixins, and clas
 
 ## Installation
 
-> Note: Installation via the npm registry will be available after alpha.
+```
+npm install --save @material/animation
+```
 
 ## Usage
 

packages/mdc-animation/package.json

@@ -1,7 +1,10 @@
 {
   "name": "@material/animation",
-  "description": "Animation Variables and Mixins for Material Design",
+  "description": "Animation Variables and Mixins used by Material Components for the web",
   "version": "0.1.0",
   "license": "Apache-2.0",
-  "devDependencies": {}
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/material-components/material-components-web.git"
+  }
 }

packages/mdc-auto-init/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@material/auto-init",
+  "description": "Declarative, easy-to-use auto-initialization for Material Components for the web",
   "version": "0.1.0",
   "main": "index.js",
   "license": "Apache-2.0",
-  "description": "data-mdc-auto-init=<globalComponentName>"
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/material-components/material-components-web.git"
+  }
 }

packages/mdc-base/README.md

@@ -8,7 +8,9 @@ Most of the time, you shouldn't need to depend on `mdc-base` directly. It is use
 
 First install the module:
 
-> NOTE: Installation via the npm registry will be available after alpha.
+```
+npm install --save @material/base
+```
 
 Then include it in your code in one of the following ways:
 

packages/mdc-base/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@material/base",
-  "description": "The set of base classes for Material Components Web",
+  "description": "The set of base classes for Material Components for the web",
   "version": "0.1.0",
   "license": "Apache-2.0",
-  "main": "index.js"
+  "main": "index.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/material-components/material-components-web.git"
+  }
 }

packages/mdc-button/README.md

@@ -7,7 +7,9 @@ The MDC Button component is a spec-aligned button component adhering to the
 
 ## Installation
 
-> Note: Installation via the npm registry will be available after alpha.
+```
+npm install --save @material/button
+```
 
 ## Usage