Navigation components

src/README.md

@@ -44,9 +44,10 @@ These components aid visitors who have reached the end of the page content.
 
 ## Navigation components
 
-* The [main navigation](./il-main-nav/README.md) contains the primary navigation for the site.
+These components contains links that direct the visitor to specific pages on the site.
+
+* The [main navigation](./il-main-nav/README.md) contains the primary collection of links. It is located in the page header and does not change from page to page.
+* The [sidebar navigation](./il-sidebar-nav/README.md) appears next to the page content and may change from section to section.
 * [Breadcrumbs](./il-breadcrumbs/README.md)
 * [Pagination](./il-pagination/README.md)
 * [Social navigation](il-social-icons/README.md)
-* [Navigation menus](./il-nav/README.md) are lists of links, sometimes with multiple levels, that can be displayed in a variety of ways depending on their context.
-* [Navigation sections](./il-nav-section/README.md) are used with menus to group subsections of the navigation, often so they can be hidden or shown based on user interaction.

src/il-feature/README.md

@@ -0,0 +1,163 @@
+# Features
+
+
+
+## Changing the section color scheme
+
+On a page with multiple sections, it can be helpful to distinguish the individual sections by using different colors schemes for each section.
+
+```html
+<il-page>
+  <il-section color="white">
+    <p>Section one uses the white color scheme</p>
+  </il-section>
+  <il-section class="gray">
+    <p>Section two uses the gray color scheme</p>
+  </il-section>
+</il-page>
+```
+```
+         :                                                           :
++-----------------------------------------------------------------------------+
+|        :                                                           :        |
+|        :Section one uses the white color scheme                    :        |
+|        :                                                           :        |
++-----------------------------------------------------------------------------+
+|        :                                                           :        |
+|        :Section two uses the gray color scheme                     :        |
+|        :                                                           :        |
++-----------------------------------------------------------------------------+
+         :                                                           :
+```
+
+The available color schemes are:
+
+* white (default)
+* gray
+* orange
+* blue
+* blue-gradient
+* orange-gradient
+
+## Adding a background image
+
+To add a background image to a page section, use the `background` content slot.
+
+```html
+<il-section>
+  <img src="background.jpg" alt="" slot="background">
+  <p>This section has a background image</p>
+</il-section>
+```
+
+```
+         :                                                           :
++-----------------------------------------------------------------------------+
+|\ \ \ \ : \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ : \ \ \ \|
+| \ \ \ \:This section has a background image \ \ \ \ \ \ \ \ \ \ \ \:\ \ \ \ |
+|\ \ \ \ : \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ : \ \ \ \|
++-----------------------------------------------------------------------------+
+         :                                                           :
+```
+
+For complex background images or images without sufficient color contrast, the `il-inset` class is used to create an overlay using the color scheme of the parent section.
+
+```html
+<il-section color="blue">
+  <img src="background-with-poor-contrast.jpg" alt="" slot="background">
+  <div class="il-inset">
+    <p>This content will be inset from the background and use the blue color scheme.</p>
+  </div>
+</il-section>
+```
+
+```
+         :                                                           :
++-----------------------------------------------------------------------------+
+|########:###########################################################:########|
+|########:##                                                       ##:########|
+|########:##  This content will be inset from the background and   ##:########|
+|########:##  use the blue color scheme.                           ##:########|
+|########:##                                                       ##:########|
+|########:###########################################################:########|
++-----------------------------------------------------------------------------+
+         :                                                           :
+```
+
+## Using grids inside sections
+
+When a grid is placed inside a section, the grid is contained within the content boundaries, including the backgrounds of any grid items.
+
+```html
+<il-section>
+  <il-grid columns="3">
+    <div class="il-blue">Blue</div>
+    <div class="il-white">White</div>
+    <div class="il-orange">Orange</div>
+  </il-grid>
+</il-section>
+```
+
+```
+- - - - -+-------------------+-------------------+-------------------+- - - - -
+         | \ \ \ \ \ \ \ \ \ |                   | / / / / / / / / / |         
+         |\ \ \ \ \ \ \ \ \ \|                   |/ / / / / / / / / /|        
+         | \ \ \ Blue  \ \ \ |       White       | / / / Orange  / / |        
+         |\ \ \ \ \ \ \ \ \ \|                   |/ / / / / / / / / /|        
+         | \ \ \ \ \ \ \ \ \ |                   | / / / / / / / / / |        
+- - - - -+-------------------+-------------------+-------------------+- - - - -
+         :                                                           :
+         : left content                                right content :
+         : boundary                                         boundary :
+```
+
+To extend the backgrounds of grid items to the edge of the page, use the `background` attribute with a value of `grid`. Add the `il-background` class to grid items to extend the background of that item when it is the left-most or right-most item in a grid row.
+
+```html
+<il-section background="grid">
+  <il-grid columns="3">
+    <div class="il-blue il-background">The background of this item will extend to the left edge of the page.</div>
+    <div class="il-white">This item is not at the end of a row, so it cannot extend its background.</div>
+    <div class="il-orange">This item is at the end of a row but does not have the il-background class, so its background will not extend.</div>
+  </il-grid>
+</il-section>
+```
+
+```
++----------------------------+-------------------+-------------------+- - - - -
+|\ \ \ \ : \ \ \ \ \ \ \ \ \ |                   | / / / / / / / / / |          
+| \ \ \ \:The background of \| This item is not  | This item is at/ /|         
+|\ \ \ \ :this item will \ \ | at the end of a   | the end a the row |         
+| \ \ \ \:extend to the left | row, so it cannot | but does not have/|         
+|\ \ \ \ :edge of the page. \| extend its        | the il-background |         
+| \ \ \ \: \ \ \ \ \ \ \ \ \ | background.       | class, so its/ / /|         
+| \ \ \ \: \ \ \ \ \ \ \ \ \ |                   | background will / |         
+| \ \ \ \: \ \ \ \ \ \ \ \ \ |                   | not extend./ / / /|         
++----------------------------+-------------------+-------------------+- - - - -
+         :                                                           :
+         : left content                                right content :
+         : boundary                                         boundary :
+```
+
+When the grid item is an image, the `il-background` will extend it to the edge of the page when appropriate. **Please note** that this has the potential to crop the image in unpredictable ways and is intended for images whose purpose is primary decorative.
+
+
+```html
+<il-section background="grid" color="blue">
+  <il-grid columns="2">
+    <img src="background.jpg" alt="" class="il-background">
+    <div>This content is on the blue background of the section.</div>
+  </il-grid>
+</il-section>
+```
+```
++--------------------------------------+-----------------------------+--------+
+|\ \ \ \ : \ \ \ \ \ \ \ \ \ \ \ \ \ \ |                             :        |
+| \ \ \ \:\ \ \ \ \ \ \ \ \ \ \ \ \ \ \| This content is on the blue :        |
+|\ \ \ \ : \ \ \ \ \ \ \ \ \ \ \ \ \ \ | background of the section.  :        |
+| \ \ \ \:\ \ \ \ \ \ \ \ \ \ \ \ \ \ \|                             :        |
++--------------------------------------+-----------------------------+--------+
+         :                                                           :
+         : left content                                right content :
+         : boundary                                         boundary :
+```

src/il-main-nav/README.md

@@ -1,6 +1,14 @@
 # Main navigation
 
-This component is part of the standard header and represents the main set of navigation links for a website. On larger screens it appears as a horizontal bar with dropdowns for secondary levels of links. On small screens, it is contained within the header menu widget, and appears as a vertical column of links with expandable secondary levels.
+The main navigation provides a reliable way for visitors to locate key pages in the site. It presents links in a hierarchy that allows visitors to expand sections to reveal additional layers of links.
+
+This component is part of the standard header and is not designed for use outside that component.
+
+## Appearance
+
+On larger screens it appears as a horizontal bar with dropdowns for secondary levels of links. On small screens, it is contained within the header menu widget, and appears as a vertical column of links with expandable secondary levels.
+
+## Structure
 
 A simple main navigation component might contain a single list of links, representing important locations within the site. This component is placed in the `navigation` slot of the header component.