documentation improvements

docs/pages/components/nested-list.md

@@ -12,7 +12,9 @@ summary:
 {: .docs-intro}
 Nested List represents a nested structure with up to 10 levels.
 
-# Nested List Without Icons
+## Nested List Without Icons
+Use the `fd-nested-list--text-only` modifier class for a nested list with items that have only title.
+
 {% capture example-1 %}
 <ul class="fd-nested-list fd-nested-list--text-only">
     <li class="fd-nested-list__item">
@@ -135,7 +137,10 @@ Nested List represents a nested structure with up to 10 levels.
 
 <br /><br />
 
-# Nested List With Icons
+## Nested List With Icons and Borderless Design
+For a nested list with icon (default) you don't need to add a modifier class. 
+For a Borderless Design use the `fd-nested-list--no-border` modifier class.
+
 {% capture example-2 %}
 <ul class="fd-nested-list fd-nested-list--no-border">
     <li class="fd-nested-list__item">
@@ -240,7 +245,7 @@ Nested List represents a nested structure with up to 10 levels.
 
 <br /><br /> 
 
-# Nested List With Icons Only in First-Level Items
+## Nested List With Icons Only in First-Level Items
 {% capture example-3 %}
 <ul class="fd-nested-list">
     <li class="fd-nested-list__item">
@@ -337,7 +342,7 @@ Nested List represents a nested structure with up to 10 levels.
 
 <br /><br />
 
-# Nested List With Group Headers
+## Nested List With Group Headers
 {% capture example-4 %}
 <ul class="fd-nested-list">
     <li class="fd-nested-list__group-header">
@@ -440,7 +445,9 @@ Nested List represents a nested structure with up to 10 levels.
 
 <br /><br />
 
-# Nested List With Group Headers Compact Mode
+## Nested List With Group Headers Compact Mode
+For compact mode use the `fd-nested-list--compact` modifier class.
+
 {% capture example-5 %}
 <ul class="fd-nested-list fd-nested-list--compact">
     <li class="fd-nested-list__group-header">
@@ -543,7 +550,9 @@ Nested List represents a nested structure with up to 10 levels.
 
 <br /><br />
 
-# Nested List Without Links
+## Nested List Without Links
+For a nested list with items without links, the icon and the title are wrapped in a container with `fd-nested-list__content` class.
+
 {% capture example-6 %}
 <ul class="fd-nested-list fd-nested-list--compact">
     <li class="fd-nested-list__group-header">
@@ -646,7 +655,7 @@ Nested List represents a nested structure with up to 10 levels.
 
 <br /><br />
 
-# Right To Left Support
+## Right To Left Support
 {% capture example-7 %}
 <ul class="fd-nested-list fd-nested-list--no-border" dir="rtl">
     <li class="fd-nested-list__item">

docs/pages/components/side-navigation.md

@@ -9,16 +9,16 @@ folder: components
 summary:
 ---
 
-The left navigation area can be used to display navigation structures with links that change the content in the main area. 
-
-The side navigation consists of two container section:  the Main Navigation Section (top-aligned) with links used to navigate within the user’s current work context, and Utility Section (bottom-aligned) that contains links to additional information.
-
+The left navigation area can be used to display navigation structures with links that change the content in the main area. The side navigation consists of two container section:  the Main Navigation Section (top-aligned) with links used to navigate within the user’s current work context, and Utility Section (bottom-aligned) that contains links to additional information.
+Each of the sections uses a Nested List to display the navigation items.
 {: .docs-intro}
 
 > {{ site.data.strings.headerDisclaimer }}
 
 ## Side Navigation with one level - text-only, cozy mode
 There is only one level of navigation; all further navigation is shown in the content area.
+<br>
+The lists in both sections (Main and Utility) should have the `fd-nested-list--text-only` modifier class.
 
 {% capture default %}
 <nav class="fd-side-nav">
@@ -298,7 +298,8 @@ Use this when there is more than one level of hierarchy in the left navigation.
 <br>
 
 ## Side navigation with multiple levels - compact mode
-In compact mode the dimensions of the controls are reduced, allowing more information to be displayed. This mode is suggested for devices operated by mouse and keyboard.
+In compact mode the dimensions of the controls are reduced, allowing more information to be displayed. This mode is suggested for devices operated by mouse and keyboard. <br>
+The lists in both sections (Main and Utility) should have the `fd-nested-list--compact` modifier class.
 
 {% capture default %}
 <nav class="fd-side-nav">
@@ -405,7 +406,7 @@ In compact mode the dimensions of the controls are reduced, allowing more inform
 <br>
 
 ## Side navigation with icons - condensed state
-
+Use the `fd-side-nav--condensed` modifier class for `condensed` state.
 {% capture default %}
 <nav class="fd-side-nav fd-side-nav--condensed">
     <div class="fd-side-nav__main-navigation">