MAGETWO-37920: Add documentation for Styles Library components

- CR changes

Author: Bogdan Plieshka

lib/web/css/docs/components.html

@@ -4,9 +4,8 @@
 //  */
 
 //  # Components
-//  It's ready made parts that can be reused in Storefront or Admin area.
-//  Instead of lib mixins, they are generates CSS code and not included in code by default.
-//  To use them, just include it as simply imports.
+// Components are complete ready-for-use parts both for Storefront or Admin area.
+// They are not mixins, but classes. To use them, include this file with @import.
 //
 //  ``` less
 //  @import 'components/_component.less';
@@ -16,11 +15,11 @@
 
 // ## Modals
 //
-//  This component contains two kinds of modals, popups and slide panels.
-//  ### Modal popups
-//  Calling with class <code>.modal-popup</code>
-//<textarea class="preview-code" spellcheck="false">
-//<div class="modals-wrapper">
+// This component contains two kinds of modals: popups and slide panels.
+// ### Modal popups
+// To have a modal popup use <code>.modal-popup</code> class.
+// <textarea class="preview-code" spellcheck="false">
+// <div class="modals-wrapper">
 //    <aside
 //        class="modal-popup _show"
 //        data-role="modal"
@@ -44,13 +43,13 @@
 //        </div>
 //    </aside>
 //    <div class="modals-overlay"></div>
-//</div>
-//</textarea>
+// </div>
+// </textarea>
 //
-//  ### Modal slide panels
-//  Calling with class <code>.modal-slide</code>
-//<textarea class="preview-code" spellcheck="false">
-//<div class="modals-wrapper">
+// ### Modal slide panels
+// To have a modal slide panel use <code>.modal-slide</code> class.
+// <textarea class="preview-code" spellcheck="false">
+// <div class="modals-wrapper">
 //    <aside
 //        class="modal-slide _show"
 //        data-role="modal"
@@ -74,8 +73,8 @@
 //        </div>
 //    </aside>
 //    <div class="modals-overlay"></div>
-//</div>
-//</textarea>
+// </div>
+// </textarea>
 
 // ###  Variables
 // <pre>

lib/web/css/docs/source/components.less

@@ -827,6 +827,7 @@
 //  </pre>
 //
 //  ## Structure
+//  #### Predefined variables for handle global Z-axis positioning
 //  <pre>
 //    <table>
 //        <tr>
@@ -835,9 +836,6 @@
 //            <th class="vars_head">Allowed values</th></th>
 //        </tr>
 //      <tr>
-//          <th colspan="3" class="vars_section">Predefined variables for handle global Z-axis positioning</th>
-//      </tr>
-//      <tr>
 //        <th>@z-index-1</th>
 //        <td class="vars_value">100</td>
 //        <td class="vars_value">constant</td>

lib/web/css/docs/source/variables.less

@@ -830,16 +830,14 @@ <h4 id="the-codetypographyallcode-mixin-variables">The <code>.typography-all()</
   </pre>
 
 <h2 id="structure">Structure</h2>
+<h4 id="predefined-variables-for-handle-global-zaxis-positioning">Predefined variables for handle global Z-axis positioning</h4>
   <pre>
     <table>
         <tr>
             <th class="vars_head">Variable</th>
             <th class="vars_head">Default value</th>
             <th class="vars_head">Allowed values</th></th>
         </tr>
-      <tr>
-          <th colspan="3" class="vars_section">Predefined variables for handle global Z-axis positioning</th>
-      </tr>
       <tr>
         <th>@z-index-1</th>
         <td class="vars_value">100</td>