Gitiles
Code Review Sign In
gerrit.avm99963.com / hores-external / be50d49a1de3579494650ceb3cad0f04719b087f / . / node_modules / material-design-lite / dist / faq / index.html
blob: ac3535fb32b45e864472f54045daf987351c476f [file] [log] [blame]
Copybara botbe50d492023-11-30 00:16:42 +0100[diff] [blame^]1<!doctype html>
2<html lang="en">
3 <head>
4 <meta charset="utf-8">
5 <meta http-equiv="X-UA-Compatible" content="IE=edge">
6 <meta name="description" content="A front-end template that helps you build fast, modern mobile web apps.">
7 <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
8 <title>Material Design Lite</title>
9
10 <!-- Add to homescreen -->
11 <link rel="manifest" href="manifest.json">
12
13 <!-- Fallback to homescreen for Chrome <39 on Android -->
14 <meta name="mobile-web-app-capable" content="yes">
15 <meta name="application-name" content="Material Design Lite">
16 <link rel="icon" sizes="192x192" href="../assets/android-desktop.png">
17
18 <!-- Add to homescreen for Safari on iOS -->
19 <meta name="apple-mobile-web-app-capable" content="yes">
20 <meta name="apple-mobile-web-app-status-bar-style" content="black">
21 <meta name="apple-mobile-web-app-title" content="Material Design Lite">
22 <link rel="apple-touch-icon" href="../assets/ios-desktop.png">
23
24 <!-- TODO: Tile icon for Win8 (144x144 + tile color) -->
25 <!-- <meta name="msapplication-TileImage" content="images/touch/ms-touch-icon-144x144-precomposed.png"> -->
26 <!-- <meta name="msapplication-TileColor" content="#3372DF"> -->
27
28 <meta name="theme-color" content="#263238">
29
30 <link rel="shortcut icon" href="../assets/favicon.png">
31 <!-- SEO: If your mobile URL is different from the desktop URL, add a canonical link to the desktop page https://developers.google.com/webmasters/smartphone-sites/feature-phones -->
32 <!--
33 <link rel="canonical" href="http://www.example.com/">
34 -->
35
36 <!-- Page styles -->
37 <link rel="stylesheet" href="../assets/prism-default.css">
38 <link rel="stylesheet" href="../material.min.css">
39 <link rel="stylesheet" href="../assets/main.css">
40
41 <!-- Fonts -->
42 <link href='https://fonts.googleapis.com/css?family=Roboto:regular,bold,italic,thin,light,bolditalic,black,medium&amp;lang=en' rel='stylesheet' type='text/css'>
43 <link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
44 </head>
45 <body class="faq">
46 <!-- Google Analytics: change UA-XXXXX-X to be your site's ID -->
47 <script>
48 // if (document.location.hostname !== 'localhost' &&
49 // document.location.hostname !== '127.0.0.1' &&
50 // document.location.hostname.search('.corp.') === -1) {
51 (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
52 (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
53 m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
54 })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
55 ga('create', 'UA-25993200-9', 'auto');
56 // If a specific component page is loaded directly we'll attribute the
57 // page view to the specific component's page
58 if (window.location.pathname.indexOf('/components/') !== -1 &&
59 window.location.hash.indexOf('-section') !== -1) {
60 ga('send', 'pageview', '/components/' +
61 window.location.hash.split('#')[1].split('/')[0]);
62 } else {
63 ga('send', 'pageview');
64 }
65 // }
66
67 // Setup error tracking before anything else runs.
68 window.onerror = function(message, file, lineNumber, columnNumber, error) {
69 try {
70 if (error !== undefined) {
71 message = error.stack;
72 }
73 ga('send', 'event', 'error', file + ':' + lineNumber, String(message));
74 } catch (e) {
75 // no-op
76 }
77 };
78 </script>
79 <div class="image-preloader"></div>
80 <div class="docs-layout mdl-layout mdl-js-layout">
81 <header class="docs-layout-header mdl-layout__header">
82 <div class="mdl-layout__header-row">
83 <span class="docs-layout-title mdl-layout-title"><a href="../">Material<br>Design<br>Lite</a></span>
84 </div>
85 <div class="docs-navigation__container">
86 <nav class="docs-navigation mdl-navigation">
87 <a href="../index.html" class="mdl-navigation__link about">About</a>
88 <a href="../started/index.html" class="mdl-navigation__link started">Getting Started</a>
89 <a href="../templates/index.html" class="mdl-navigation__link templates">Templates</a>
90 <a href="../components/index.html" class="mdl-navigation__link components">Components</a>
91 <a href="../styles/index.html" class="mdl-navigation__link styles">Styles</a>
92 <a href="../customize/index.html" class="mdl-navigation__link customize">Customize</a>
93 <a href="../showcase/index.html" class="mdl-navigation__link showcase">Showcase</a>
94 <a href="../faq/index.html" class="mdl-navigation__link faq">FAQ</a>
95 <div class="spacer"></div>
96 <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>
97 <a href="../started/index.html#download" class="mdl-navigation__link mdl-navigation__link--icon download">
98 <i class="material-icons">&#xE2C4;</i><span>Download</span>
99 <button class="mdl-button mdl-js-button mdl-js-ripple-effect mdl-button--fab mdl-button--mini-fab mdl-color--lime-A200">
100 <i class="material-icons">&#xE2C4;</i>
101 </button>
102 </a>
103 </nav>
104 </div>
105 <i class="material-icons scrollindicator scrollindicator--right">&#xE315;</i>
106 <i class="material-icons scrollindicator scrollindicator--left">&#xE314;</i>
107 </header>
108 <main class="docs-layout-content mdl-layout__content mdl-color-text--grey-600">
109 <div class="content mdl-grid mdl-grid--no-spacing" id="content">
110 <div class="subpageheader mdl-cell--12-col">FAQ</div>
111
112
113<div class="docs-text-styling">
114 <section id="include">
115 <p><div class="docs-text-styling">
116 <section class="docs-toc">
117 <h3>Contents</h3>
118 <nav class="section-content">
119 <ul>
120 <li><a href="#where-should-i-use">Where should I use Material Design Lite (MDL)?</a></li>
121 <li><a href="#css-naming-conventions">What CSS naming conventions does MDL use?</a></li>
122 <li><a href="#progressive-enhancement">Does MDL support progressive enhancement?</a></li>
123 <li><a href="#browser-support">Which browsers does MDL support?</a></li>
124 <li><a href="#polymer">Does MDL play nicely with Polymer?</a></li>
125 <li><a href="#bootstrap">Is MDL comparable to Bootstrap?</a></li>
126 <li><a href="#existing-implementations">How does it compare to existing Material CSS implementations?</a></li>
127 <li><a href="#options-available">Should I use the minified, CDN or Sass versions of MDL?</a></li>
128 <li><a href="#official-cdn">What service does the official CDN use?</a></li>
129 <li><a href="#web-starter-kit">How does MDL relate to Web Starter Kit?</a></li>
130 <li><a href="#mdl-in-production">Do any Google properties use MDL in production?</a></li>
131 <li><a href="#mdl-showcase">Is there a showcase available of sites using MDL?</a></li>
132 <li><a href="#individual-components">Can I build or use individual MDL components (e.g a button)?</a></li>
133 <li><a href="#report-an-issue">How do I report a problem with MDL?</a></li>
134 <li><a href="#getting-help">Where can I get help with questions about using MDL?</a>
135 <li><a href="#slide-decks">Are there any presentations or slide-decks available on MDL?</a></li>
136 <li><a href="#new-components">Can I request or contribute components to MDL?</a></li>
137 <li><a href="#alternate-preprocessor">Will MDL support non-Sass preprocessors?</a></li>
138 <li><a href="#issue-updates">How do I keep updated with issues I&#39;m interested in?</a></li>
139 </ul>
140 </nav>
141 </section></p>
142<h2 id="where-should-i-use">Where should I use Material Design Lite (MDL)?</h2>
143
144<p>If you’re interested in a <a href="https://www.google.com/design/spec/material-design/introduction.html">Material Design</a> 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.</p>
145<p>Whilst there exist several community-driven options for Material Design, 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.</p>
146<h2 id="css-naming-conventions">What CSS naming conventions does MDL use?</h2>
147
148<p>MDL was written using <a href="https://en.bem.info/method/">BEM</a>. 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:</p>
149<ul>
150<li><a href="http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/">CSSWizardry</a></li>
151<li><a href="https://css-tricks.com/bem-101/">CSS-Tricks</a></li>
152<li><a href="http://www.smashingmagazine.com/2012/04/16/a-new-front-end-methodology-bem/">Smashing Magazine</a></li>
153</ul>
154<p>These are great resources that simplify the data needed to understand BEM. If you want to read the methodology from the inventors, <a href="https://en.bem.info/">Yandex provides the resource</a>. This reference goes way beyond just the CSS and into the full JavaScript setup they use as well.</p>
155<p>Our <a href="https://github.com/google/material-design-lite/wiki/Understanding-BEM">wiki</a> includes a section on the namespacing used for MDL specifically.</p>
156<h2 id="progressive-enhancement">Does MDL support progressive enhancement?</h2>
157
158<p>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’.</p>
159<p>One example of this is our ‘Text only’ Material Design template. Switching JavaScript off in Chrome DevTools, the page still renders CSS fine:</p>
160<p><img src="../assets/template-preview.png" alt="A preview of a template rendering in an older version of IE"></p>
161<p>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.</p>
162<p>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 ‘Which browsers does MDL support?’.</p>
163<p>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.</p>
164<h2 id="browser-support">Which browsers does MDL support?</h2>
165
166<p>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 <a href="https://github.com/google/material-design-lite/blob/9e6c6ec9237715bfa04b307f786e9073f943e6be/src/mdlComponentHandler.js#L333">Cutting-the-mustard</a> test.</p>
167<p>Our <a href="https://github.com/google/material-design-lite/#browser-support">browser compatibility matrix</a> has the most up to date information on the browsers we officially support. For components, at minimum we require support for <a href="https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector">querySelector</a>, <a href="https://developer.mozilla.org/en-US/docs/Web/API/Element/classList">classList</a> and <a href="https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener">addEventListener</a>, which can be <a href="https://github.com/Modernizr/Modernizr/wiki/HTML5-Cross-Browser-Polyfills">polyfilled</a> as needed. Our Templates will work in IE10+, primarily due to our use of Flexbox.</p>
168<p>The polyfills that we’re currently using for the MDL site to improve support in oldIE are the following:</p>
169<pre><code class="language-markup">&lt;!--[if IE]&gt;
170&lt;script src=&quot;//cdnjs.cloudflare.com/ajax/libs/es5-shim/4.2.0/es5-shim.min.js&quot;&gt;&lt;/script&gt;
171&lt;script src=&quot;//cdnjs.cloudflare.com/ajax/libs/classlist/2014.01.31/classList.min.js&quot;&gt;&lt;/script&gt;
172&lt;script src=&quot;//cdnjs.cloudflare.com/ajax/libs/selectivizr/1.0.2/selectivizr-min.js&quot;&gt;&lt;/script&gt;
173&lt;![endif]--&gt;
174</code></pre>
175<p>IE10 standards mode <a href="http://bit.ly/1dypChT">removes</a> support for conditional comments, so the above will only get interpreted by older versions of IE, such as IE9.</p>
176<p>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:</p>
177<p><strong>Buttons</strong></p>
178<p><img alt="Buttons rendering in IE8" src="../assets/button_degradation.png"></p>
179<p><strong>Tables</strong></p>
180<p><img alt="Tables gracefully degrading in IE8" src="../assets/table_degradation.png"></p>
181<p><strong>Sliders (degrade to input fields)</strong></p>
182<p><img alt="Sliders degrading in IE8 to input fields" src="../assets/sliders_degradation.png"></p>
183<h2 id="polymer">Does MDL play nicely with Polymer? Is it a replacement for the Paper elements?</h2>
184
185<p>MDL focuses on delivering an experience that is optimised for static content sites, like blogs, marketing pages and more traditional text-based web pages.</p>
186<p>The <a href="https://elements.polymer-project.org/browse?package=paper-elements">Paper</a> elements built with <a href="http://polymer-project.org">Polymer</a> are fully encapsulated components that can be used individually or composed together to create a material design-style site, and support more advanced user interaction.</p>
187<p>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.</p>
188<h2 id="bootstrap">Is MDL comparable to Bootstrap?</h2>
189
190<p><em>If we&#39;re using it instead of Bootstrap, can we expect the same level of component styling?</em></p>
191<p>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.</p>
192<h2 id="existing-implementations">How does it compare to existing Material CSS implementations?</h2>
193
194<p><em>Materialize, Material Bootstrap, etc</em></p>
195<p>We think the community does a great job offering their own take on how Material Design should be implemented for CSS libraries.</p>
196<p>That said, the 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.</p>
197<h2 id="options-available">Should I use the minified, CDN or Sass versions of MDL?</h2>
198
199<p><em>Should I build my own version or download the minified version or simply refer to CDN objects?</em></p>
200<p><strong>Minified: </strong>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.</p>
201<p><strong>CDN: </strong>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.</p>
202<p><strong>Customiser: </strong>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.</p>
203<p><strong>Sass: </strong>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.</p>
204<h2 id="official-cdn">What service does the official CDN use?</h2>
205
206<p>The official CDN is hosted using <a href="https://cloud.google.com/storage/">Google Cloud Storage</a>.</p>
207<h2 id="web-starter-kit">How does MDL relate to Web Starter Kit?</h2>
208
209<p>MDL is an evolutionary step from the styleguide provided in Web Starter Kit. The more <a href="https://developers.google.com/web/tools/starter-kit/">Web Starter Kit</a> was used, the more it became clear that many developers simply wanted Material Design in their sites.</p>
210<p>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 faithful as possible to the specification.</p>
211<h2 id="mdl-in-production">Do any Google properties use MDL in production?</h2>
212
213<p>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:</p>
214<p>The <a href="https://developers.google.com/mobile/add">Google Services</a> site:</p>
215<p><img src="../assets/google-services.png" alt="Google Services site screenshot"></p>
216<p><a href="http://www.richmediagallery.com/">RichMediaGallery</a> by DoubleClick:</p>
217<p><img src="../assets/rich-media-gallery.png" alt="RichMediaGallery screenshot"></p>
218<p>and is being used by many other teams on upcoming projects, including Google Shopping.</p>
219<h2 id="mdl-showcase">Is there a showcase available of sites using MDL?</h2>
220
221<p>See the <a href="/showcase/">Showcase</a> for an early list of Google sites using MDL in production. </p>
222<p>To request your site be added, please file a <a href="https://github.com/Google/material-design-lite/issues/new?title=Site%20Showcase%20Request&amp;body=Please%20include:%0A*%20Description%0A*%20Primary%20Link%0A*%20Screenshot">new issue</a> on our GitHub issue tracker. The issue should include a link, a description of the site and a suggested screenshot.</p>
223<p>We hope to add a properly polished showcase to the site in the near future.</p>
224<h2 id="individual-components">Can I build or use individual MDL components (e.g a button)?</h2>
225
226<p>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.</p>
227<p>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 <a href="https://github.com/google/material-design-lite/blob/master/src/material-design-lite.scss">comment out</a> those components you don’t need in material-design-lite.scss, <a href="https://github.com/google/material-design-lite/blob/master/gulpfile.js#L191">comment out</a> the scripts you don’t need in the Gulpfile and then run <code>gulp</code> to create your build.</p>
228<p>We have talked about offering up components in a more modular fashion but will be exploring this in the post V1 timeline.</p>
229<h2 id="report-an-issue">How do I report an issue with MDL?</h2>
230
231<p>Please let us know about any problems by opening an issue on our <a href="https://github.com/google/material-design-lite/issues">GitHub repo</a>.</p>
232<h2 id="getting-help">Where can I get help with questions about using MDL?</h2>
233
234<p>We encourage the MDL user and developer community to ask questions, and help answer questions, on <a href="http://stackoverflow.com">Stack Overflow</a>, using the <code>Material-Design-Lite</code> tag.</p>
235<h2 id="slide-decks">Are there any presentations or slide-decks available on MDL?</h2>
236
237<p>We did a preview talk at Google I/O 2015 on MDL and the slides for that talk can be found on <a href="https://speakerdeck.com/gauntface/material-design-lite-preview">SpeakerDeck</a>.</p>
238<h2 id="new-components">Can I request or contribute components to MDL?</h2>
239
240<p>Sure! There may be components or templates you would like to see implemented in MDL that we don&#39;t yet provide. Please feel free to propose them on the <a href="https://github.com/Google/material-design-lite/issues/new?title=%5BComponent%20Request%5D%20%7BComponent%7D&body=Please%20include:%0A*%20Description%0A*%20Material%20Design%20Spec%20link%0A*%20Use%20Case%28s%29">Issue Tracker</a>. While we can&#39;t guarantee we&#39;ll be able to implement them all, we will consider requests and review them at regular intervals.</p>
241<h2 id="alternate-preprocessor">Will MDL support non-Sass preprocessors?</h2>
242
243<p><em>Stylus, Less, PostCSS, etc.</em></p>
244<p>MDL is implemented using Sass and there are no current plans to change this. If you wish to maintain a port to another preprocessor, you are more than welcome to.</p>
245<h2 id="issue-updates">How do I keep updated with issues I&#39;m interested in?</h2>
246
247<p>Watching the whole repository can introduce a lot of extra noise in your stream. To keep updated with just issues you are interested in you only need to subscribe to that issue. This is done on the issue page by clicking the &quot;Subscribe&quot; button in the right hand sidebar.</p>
248<p><img alt="Subscribing to a single issue" src="../assets/faq/subscribe-single-issue.png"></p>
249
250 </section>
251</div>
252
253
254 </div>
255 <section class="docs-text-styling download mdl-color--grey-800">
256 <a href="../started/index.html#download" class="mdl-color-text--grey-50">Download Kit</a>
257 </section>
258 <footer class="docs-text-styling docs-footer mdl-mini-footer mdl-color--grey-900">
259 <ul>
260 <li class="mdl-mini-footer--social-btn">
261 <a href="https://twitter.com/googledesign" class="social-btn social-btn__twitter" role="button" title="Twitter"></a>
262 </li>
263 <li class="mdl-mini-footer--social-btn">
264 <a href="https://github.com/google/material-design-lite" class="social-btn social-btn__github" role="button" title="GitHub"></a>
265 </li>
266 <li class="mdl-mini-footer--social-btn">
267 <a href="https://plus.google.com/+googledesign" class="social-btn social-btn__gplus" role="button" title="Google+"></a>
268 </li>
269 </ul>
270 <ul class="docs-link-list">
271 <li><a class="mdl-color-text--grey-600" href="https://developers.google.com/web/starter-kit/">Web Starter Kit</a></li>
272 <li><a class="mdl-color-text--grey-600" href="https://github.com/google/material-design-lite/issues">Help</a></li>
273 </ul>
274 </footer>
275 </main>
276 </div>
277
278 <!-- IE Compatibility shims -->
279 <!--[if lt IE 9]>
280 <script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.2/html5shiv.min.js""></script>
281 <![endif]-->
282
283 <!--[if IE]>
284 <script src="//cdnjs.cloudflare.com/ajax/libs/es5-shim/4.1.7/es5-shim.min.js"></script>
285 <script src="//cdnjs.cloudflare.com/ajax/libs/classlist/2014.01.31/classList.min.js"></script>
286 <script src="//cdnjs.cloudflare.com/ajax/libs/selectivizr/1.0.2/selectivizr-min.js"></script>
287 <script src="//cdnjs.cloudflare.com/ajax/libs/flexie/1.0.3/flexie.min.js"></script>
288 <link href="../assets/ie.css" rel="stylesheet">
289 <![endif]-->
290 <!-- end shims -->
291
292
293 <!-- Material Design Lite -->
294 <script src="../material.min.js"></script>
295 <!-- Add Copy-to-CodePen buttons to code blocks -->
296 <script src="../assets/codepen.js"></script>
297 <!-- Enable Prism syntax highlighting -->
298 <script src="../assets/prism.js"></script>
299 <script src="../assets/prism-markup.min.js"></script>
300 <script src="../assets/prism-javascript.min.js"></script>
301 <script src="../assets/prism-css.min.js"></script>
302 <script src="../assets/prism-bash.min.js"></script>
303 <script src="../assets/main.js"></script>
304 <!-- Built with love using Material Design Lite -->
305 </body>
306</html>