material-design-lite/README.md

154 lines
6.3 KiB
Markdown
Raw Normal View History

# Material Design Lite
2014-04-16 06:26:21 -07:00
2015-06-01 05:51:05 -07:00
> A library of [Material Design](http://www.google.com/design/spec/material-design/introduction.html) components in CSS, JS, and HTML
2015-02-04 22:46:41 -08:00
2015-06-02 07:23:04 -07:00
Material Design Lite lets you add a Material Design look and feel to your static content websites. It doesnt rely on any JavaScript frameworks or libraries. Optimised for cross-device use, gracefully degrades in older browsers, and offers an experience that is accessible from the get-go.
2015-02-09 06:20:21 -08:00
## Quick start
Four quick start options are available:
- [Download the latest release](https://github.com/google/material-design-lite/archive/master.zip).
- Clone the repo: `git clone https://github.com/google/material-design-lite.git`.
- Install with [Bower](http://bower.io): `bower install material-design-lite`.
- Install with [npm](https://www.npmjs.org): `npm install material-design-lite`.
### What's included
2015-06-01 05:51:05 -07:00
Within the download you'll find the following directories and files.
2015-06-05 08:51:14 -07:00
| File/Folder | Provides |
|-------------|----------|
| bower.json | Bower package configuration. |
| CONTRIBUTING.md | MDL contribution guidelines. |
| docs | Template files for documentation. |
| gulpfile.js | gulp configuration for MDL. |
| LICENSE | Project license information. |
| package.json | NPM package information |
| README.md | Details for quickly understanding the project. |
| src | Source code for MDL. |
| templates | Example templates |
| test | Project test files. |
2014-04-16 07:12:57 -07:00
## Browser Support
| IE9 | IE10 | IE11 | Chrome | Opera | Firefox | Safari | Chrome (Android) | Mobile Safari |
|-----|-----|------|--------|-------|---------|--------|------------------|---------------|
| B | A | A | A | A | A | A | A | A |
A-grade browsers are fully supported. B-grade browsers will gracefully degrade to our CSS-only experience.
2015-02-04 02:14:46 -08:00
## Getting Started
2014-04-16 07:12:57 -07:00
2015-02-04 22:46:41 -08:00
### Download
Clone or
[download](https://github.com/google/material-design-lite/archive/master.zip)
this repository, [build it](#development) and reference the following files in your project:
2014-05-23 12:02:58 -07:00
2015-02-04 02:14:46 -08:00
```html
<script src="dist/js/material.min.js"></script>
<link rel="stylesheet" href="dist/css/material.min.css">
2015-02-04 02:14:46 -08:00
```
2015-02-04 02:14:46 -08:00
You will want to include the entire package to ensure optional assets like images or fonts are correctly
included.
2014-05-27 02:27:36 -07:00
2015-02-04 22:46:41 -08:00
### npm
2014-06-16 07:03:08 -07:00
2015-02-04 22:46:41 -08:00
```
2015-06-01 05:51:05 -07:00
npm install --save material-design-lite
2015-02-04 02:14:46 -08:00
```
2014-06-19 05:50:10 -07:00
2015-02-04 22:46:41 -08:00
### bower
2014-05-16 02:59:52 -07:00
2015-02-04 22:46:41 -08:00
```
2015-06-01 05:51:05 -07:00
bower install --save material-design-lite
2015-02-04 02:14:46 -08:00
```
2014-06-16 03:26:01 -07:00
2015-06-02 04:55:59 -07:00
## Icons
2015-06-26 09:30:15 -07:00
Material Design Lite uses the official [Material Icons font](https://www.google.com/design/icons/). We recommend you include it using:
2015-06-02 04:55:59 -07:00
```
<link href="https://fonts.googleapis.com/icon?family=Material+Icons"
rel="stylesheet">
```
2015-06-26 09:30:15 -07:00
You can check for other options on the [Developer's Guide](http://google.github.io/material-design-icons/#icon-font-for-the-web).
2015-06-02 04:55:59 -07:00
All of the demos and templates in this project use the preferred ligature syntax:
```
<i class="material-icons">face</i>
```
2015-06-26 09:30:15 -07:00
If you need to support older browsers, take a look at the [Developer's Guide](http://google.github.io/material-design-icons/#icon-font-for-the-web) for
2015-06-02 04:55:59 -07:00
how to use codepoints instead, as well as the [list of supported codepoints](https://github.com/google/material-design-icons/blob/master/iconfont/codepoints).
2015-02-04 22:46:41 -08:00
2015-02-04 02:14:46 -08:00
## Development
2014-06-19 07:22:40 -07:00
2015-02-04 02:14:46 -08:00
The sources (JS, Sass) and demo files for all components can be found in the `src` directory. To get started
modifying them, first install the necessary dependencies, from the root of the project:
2014-06-16 03:26:01 -07:00
2015-02-04 22:46:41 -08:00
```
2015-06-01 05:51:05 -07:00
npm install && npm install -g gulp
2015-02-04 02:14:46 -08:00
```
2014-06-16 03:26:01 -07:00
2015-02-04 02:14:46 -08:00
Next, run the following one-liner to preview the components:
2014-06-16 03:26:01 -07:00
2015-02-04 22:46:41 -08:00
```
2015-06-01 05:51:05 -07:00
gulp serve
2015-02-04 02:14:46 -08:00
```
2014-06-06 03:55:13 -07:00
2015-02-04 02:14:46 -08:00
Any changes made to files inside the `src` directory will cause the page to reload. This page can also be loaded
up on physical devices thanks to BrowserSync.
2015-02-04 02:14:46 -08:00
To build a production version of the components, run:
2015-02-04 22:46:41 -08:00
```
2015-06-01 05:51:05 -07:00
gulp
2015-02-04 02:14:46 -08:00
```
2015-06-01 05:51:05 -07:00
This will clean the `dist` folder and rebuild the assets for serving.
2014-06-16 03:14:04 -07:00
2015-04-16 06:55:28 -07:00
## Templates
The `templates/` subdirectory contains a few exemplary usages of MDL. Templates have their own, quasi-separate
gulp pipeline and can be compiled with `gulp templates`. The templates use the vanilla MDL JS and
[themed](http://google.github.io/material-design-lite/customizer/customizer.html) CSS files. Extraneous
2015-04-16 07:20:39 -07:00
styles are kept in a separate CSS file. Use `gulp serve` to take a look at the templates:
* [General template](http://localhost:3000/templates/general)
* [Blog template](http://localhost:3000/templates/blog) and [blog entry](http://localhost:3000/templates/blog/entry.html)
* [Dashboard template](http://localhost:3000/templates/dashboard)
2015-04-27 08:12:24 -07:00
* [Product template](http://localhost:3000/templates/product)
2015-04-16 06:55:28 -07:00
> Templates are not officially supported in IE9 and legacy browsers that do not pass the minimum-requirements defined in our [cutting-the-mustard test](https://github.com/google/material-design-lite/blob/master/src/mdlComponentHandler.js#L256-269).
2015-02-20 17:18:54 -08:00
## Versioning
For transparency into our release cycle and in striving to maintain backward compatibility, Material Design Lite is maintained under [the Semantic Versioning guidelines](http://semver.org/). Sometimes we screw up, but we'll adhere to those rules whenever possible.
2015-03-30 05:36:22 -07:00
## Feature requests
2015-06-01 05:51:05 -07:00
If you find MDL doesn't contain a particular component you think would be useful, please check the issue tracker in case work has already started on it. If not, you can request a [new component](https://github.com/Google/material-design-lite/issues/new?title=[Component%20Request]%20{Component}&body=Please%20include:%0A*%20Description%0A*%20Material%20Design%20Spec%20link%0A*%20Use%20Case%28s%29).
2015-02-04 22:46:41 -08:00
## In-development
Here, you can find early live previews of our work for testing or demo purposes.
* [Visual tests](http://google.github.io/material-design-lite/test/visual/) for components
* [Android.com](http://google.github.io/material-lite-samples/android-dot-com/) Material Design Lite demo
* [Theme customiser prototype](http://google.github.io/material-design-lite/customizer/customizer.html)
## Do you include any features that a framework comes with?
2015-04-16 06:55:28 -07:00
Material Design Lite is focused on delivering a vanilla CSS/JS/HTML library of components. We are not a framework. If you are building a single-page app and require features like two-way data-binding, templating, CSS scoping and so forth, we recommend trying out the excellent [Polymer](http://polymer-project.org) project.
2014-06-06 05:06:29 -07:00
## License
Copyright Google, 2015. Licensed under an Apache-2 license.