Merge pull request #5586 from magento/kh_restore-5392

dobooth · web-flow · commit 7dd339a3b5a5 · 2019-10-07T11:38:24.000-05:00
Restore PR-5392 to develop
diff --git a/_data/toc/frontend-developer-guide.yml b/_data/toc/frontend-developer-guide.yml
@@ -124,6 +124,9 @@ pages:
         - label: Using custom fonts
           url: /frontend-dev-guide/css-topics/using-fonts.html
 
+        - label: CSS critical path
+          url: /frontend-dev-guide/css-topics/css-critical-path.html
+
         - label: Using custom CSS preprocessor
           children:
 
diff --git a/guides/v2.2/frontend-dev-guide/css-topics/css-critical-path.md b/guides/v2.2/frontend-dev-guide/css-topics/css-critical-path.md
@@ -0,0 +1,62 @@
+---
+group: frontend-developer-guide
+title: CSS critical path
+functional_areas:
+  - Frontend
+---
+
+All CSS styles loaded from external files are considered as render-blocking. This means that a web page will not be displayed until these files are loaded.
+By using 'CSS critical path', we deliver minified critical CSS inline in `<head>` and defer all non-critical styles that are loaded asynchronously.
+Thus we can significantly improve the time to first render of our pages.
+
+## Enable CSS critical path
+
+{: .bs-callout-info }
+CSS critical path configuration is located on the **Stores** > Settings > **Configuration** > **ADVANCED** > **Developer** tab. However, the **Developer** tab is hidden in [production mode]({{page.baseurl}}/config-guide/bootstrap/magento-modes.html). Once in production mode, CSS critical path can only be enabled using the CLI.
+
+To enable the CSS critical path:
+
+```bash
+bin/magento config:set dev/css/use_css_critical_path 1
+```
+
+Make sure that there is a `critical.css` file for your theme. Other non-critical CSS files will be loaded asynchronously.
+
+## Overview of Magento's critical CSS
+
+The 'critical' CSS file should be located in `app/design/frontend/<your_vendor_name>/<your_theme_name>/web/css/critical.css`
+The default Luma theme critical CSS file is located in `app/design/frontend/Magento/luma/web/css/critical.css`
+If there is not a `critical.css` file for the custom theme, but there is one for the Luma theme, Luma's `critical.css` will be used.
+THe critical css file path can also be configured in `di.xml` as a constructor `filePath` argument in the `Magento\Theme\Block\Html\Header\CriticalCss` block.
+
+To generate a critical CSS for your theme, critical path CSS generators like [Penthouse](https://www.npmjs.com/package/penthouse) or [Critical](https://www.npmjs.com/package/critical) can be used, or you can create it yourself. While creating critical CSS, adhere to the following principles:
+
+-  Minify your `critical.css` to reduce its size.
+-  Do not duplicate styles in `critical.css` and non-critical style sheets.
+-  Do not introduce new styles in `critical.css` that are not present in non-critical style sheets. CSS rules from non-critical style sheets should overwrite critical CSS rules. Otherwise your styles can be broken.
+
+### Critical CSS loader
+
+If 'CSS critical path' is enabled in the configuration, a preloading spinner will be used. It is added in `Magento/Theme/view/frontend/layout/default.xml`.
+After non-critical CSS is loaded and applied, the spinner disappears. The spinner will disappear automatically only if you have CSS styles from the 'Blank' theme CSS. If you have your own CSS rules, you should hide the preloader by using the `data-role='main-css-loader'` attribute.
+
+## Critical CSS performance improvements
+
+Introducing a critical path CSS to Magento leads to performance improvements:
+
+-  Eliminated render-blocking CSS resources. As a result, the time for loading render-blocking resources decreases substantially.
+
+   ![CSS resources eliminated as render-blocking]({{ site.baseurl }}/common/images/critical_css_improvements1.png)
+
+-  The first meaningful paint time improved from 3.5 seconds to 2.3 seconds.
+
+   ![First meaningful paint time improved]({{ site.baseurl }}/common/images/critical_css_improvements2.png)
+
+-  The speed index increased by 0.8 seconds.
+
+   ![Speed index increased]({{ site.baseurl }}/common/images/critical_css_improvements3.png)
+
+As a result, the Google PageSpeed Insights score improved by **5** points.
+
+{: .bs-callout-info }
+These are results for mobile devices with slow connection from [Google PageSpeed Insights](https://developers.google.com/speed/pagespeed/insights/).
diff --git a/guides/v2.2/frontend-dev-guide/css-topics/css-overview.md b/guides/v2.2/frontend-dev-guide/css-topics/css-overview.md
@@ -32,7 +32,9 @@ There are a couple options to help with CSS and site performance.
 
 * Minification of CSS files reduces the file size being sent. It does this by stripping white space within the file.
 
-To enable or disable these settings, go to _Admin_ panel, click **Stores** > Settings > **Configuration** > **Advanced** > **Developer** > **CSS Settings**.
+* Use CSS critical path to eliminate render-blocking CSS resources.
+
+To enable / disable these settings, go into Admin > **Stores** > Setting > **Configuration** > **Advanced** > **Developer** > **CSS Settings**.
 
 ## Change styles: walkthrough {#css_walk}
 
@@ -68,6 +70,7 @@ Other topics of this chapter describe the following:
 * [CSS Preprocessing]({{ page.baseurl }}/frontend-dev-guide/css-topics/css-preprocess.html): how stylesheets are preprocessed and compiled
 * [Magento UI Library]({{ page.baseurl }}/frontend-dev-guide/css-topics/theme-ui-lib.html): how to use the Magento styles [library](https://glossary.magento.com/library) in your custom themes
 * [Using Custom Fonts]({{ page.baseurl }}/frontend-dev-guide/css-topics/using-fonts.html): how to add custom fonts
+* [CSS critical path]({{ page.baseurl }}/frontend-dev-guide/css-topics/css-critical-path.html): how to use CSS critical path
 * [Customizing styles illustration]({{ page.baseurl }}/frontend-dev-guide/css-topics/css-practice.html): how to change a theme's color scheme using Magento UI library.
 
 [The default view of a product page, with the orange Add to Cart button]: {{site.baseurl}}/common/images/css_over1.png
diff --git a/guides/v2.2/frontend-dev-guide/theme-best-practice.md b/guides/v2.2/frontend-dev-guide/theme-best-practice.md
@@ -23,5 +23,6 @@ We recommend using the following best practices when developing themes:
 1. Reuse the markup and design patterns from the default Magento files by referencing the existing `.phtml` templates ([templates hints can help]({{ page.baseurl }}/frontend-dev-guide/themes/debug-theme.html#debug-theme-templ)) or copy-pasting HTML markup to your custom templates.
 1. Use `<theme_dir>/etc/view.xml` to change image types or sizes, or add your own types. See [Configure images properties]({{ page.baseurl }}/frontend-dev-guide/themes/theme-images.html) for details. Use this file to also [customize the product gallery widget]({{ page.baseurl }}/javascript-dev-guide/widgets/widget_gallery.html).
 1. If you need to change the wording in the user interface, [add custom CSV dictionary files]({{ page.baseurl }}/frontend-dev-guide/translations/theme_dictionary.html) instead of overriding `.phtml` templates.
+1. Use [the CSS critical path]({{ page.baseurl }}/frontend-dev-guide/css-topics/css-critical-path.html) to render the page much faster.
 
 After updating or upgrading Magento instances, check for changes in any files that are overridden by your theme. If there were changes to default templates, layouts, or styles, copy those changes to your templates, layouts, and styles.
diff --git a/guides/v2.3/frontend-dev-guide/css-topics/css-critical-path.md b/guides/v2.3/frontend-dev-guide/css-topics/css-critical-path.md
@@ -0,0 +1 @@
+../../../v2.2/frontend-dev-guide/css-topics/css-critical-path.md

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+../../../v2.2/frontend-dev-guide/css-topics/css-critical-path.md`