updates to skeleton guidelines

packages/v4/patternfly-docs/content/design-guidelines/components/skeleton/skeleton.md

@@ -4,16 +4,24 @@ section: components
 ---
 
 ## Usage 
-Skeleton loading should be progressive –– it should load static text first, followed by variable elements of the UI.
+A skeleton is a type of loading state that allows you to expose content incrementally, once the structure of the page has been loaded in. A skeleton should match the exact structure of the element you’re loading in and can be used in components on top of the page, such as in a drop down menu, or a card. Skeleton loading should be progressive –– it should load static text first, followed by variable elements of the UI.
 
 ### When to use a skeleton vs. a loading spinner
+Use a skeleton when:
+- The structure of a page has loaded in but the content has not.
+- Some content of a page has loaded, but not all. For example, in a dashboard, you may have some loaded cards, while others are still loading. 
+- You want to show loading content inside of a card, table, data list or more.
 
 **Show a skeleton when:**
 - You know what the populated data is going to look like (even if it results in an empty state).
 
+**Do not show a skeleton when:**
+- You don’t know what the structure of the component is going to look like.
+
 **Show a [spinner](/components/spinner/react) when:**
-- You do not know what the populated data may look like. For example, if you are loading a form (as they are not all structured the same).
-- When it is likely it will fail or show an empty state while waiting for actions to complete.
+- You have multiple elements on the page that are loading at different speeds, use a spinner once the structure of at least one element is loaded on the page.
+- You are attempting to load in a component that sits on top of a page with an expected structure.
+- It is likely it will fail or show an empty state while waiting for actions to complete.
 
 ## Accessibility
 For information regarding accessibility, visit the [skeleton accessibility](/components/skeleton/accessibility) tab. 

packages/v4/patternfly-docs/content/design-guidelines/components/spinner/spinner.md

@@ -7,40 +7,47 @@ section: components
 
 Spinners are used to demonstrate data loading. Spinners are offered in different sizes that follow the sizing of our icons. These sizes include extra small, small, medium and large. Depending on the size of information you are loading and the space you are dealing with, we recommend using the spinner size that generally matches.
 
+
 <img src="./img/spinner-sizes.png" alt="Visual of different spinner sizes" width="436"/>
 
+## Placement
+
+Position the spinner in the center of the element that is loading. To ensure proper background contrast, use a white or light background.
+
+<img src="./img/spinner-full-page.png" alt="Example of spinner in full page" width="990"/>
+
 ### When to use
 Use a spinner:
-- when the data you are dealing with is unknown in both quantity and shape.
-- when in progress of loading a screen that may not have any data, for example an [empty state screen or failed outcome](/components/empty-state). 
-- within a table view, where the spinner can take up the area of the table before it loads.
-- when the expected wait time is between 1-5 seconds. 
+- When the user is advancing to a new page or step where the structure has not been loaded in yet.
+- When the data you are dealing with is unknown in both quantity and shape. 
+- When the expected wait time is between 1-5 seconds. 
 
 ### When not to use
 Don't use a spinner:
-- to replace a [progress bar](/components/progress). 
-
-- if the loading process is less than 1 second. For experiences longer than 5 seconds, use a progress bar.
+- To replace a [progress bar](/components/progress). 
+- If the loading process is less than 1 second. For experiences longer than 5 seconds, use a progress bar.
+- In components that load on top of the page, for example in cards or dropdowns. In this case use a [skeleton](/components/skeleton) to reflect the structure of the data.
+- When a loading screen does not have any data, use an [empty state screen or failed outcome](/components/empty-state) instead.
 
 ### Spinner in context
 
-Spinners are centered within the container AND the viewport by default in all use cases. Although this is the standard position of it, the spinner may be repositioned if necessary for particular screens and screen sizes.
+Spinners are centered within the container AND the viewport by default in all use cases.
 
-### Spinner in select list (small)
+### Spinner in a wizard
 
-<img src="./img/spinner-in-select.png" alt="Example of spinner in select menu" width="990"/>
+<img src="./img/wizard-with-spinner.png" alt="Example of spinner in a wizard" width="990"/>
 
-### Spinner in cards within a dashboard (medium)
+### Spinner in a full page
 
-<img src="./img/spinner-in-cards.png" alt="Example of spinner in cards" width="990"/>
+<img src="./img/spinner-full-page.png" alt="Example of spinner in full page" width="990"/>
 
-### Spinner in a data list or table (large)
+### Spinner in a modal window
 
-<img src="./img/spinner-in-table.png" alt="Example of spinner in table" width="990"/>
+<img src="./img/spinner-in-modal.png" alt="Example of spinner in a modal window" width="990"/>
 
-### Spinner in a full page (large)
+### Spinner in a data list or table (large)
 
-<img src="./img/spinner-full-page.png" alt="Example of spinner in full page" width="990"/>
+<img src="./img/spinner-in-table.png" alt="Example of spinner in table" width="990"/>
 
 ### When to use a loading spinner vs. a skeleton
 
@@ -50,3 +57,4 @@ Spinners are centered within the container AND the viewport by default in all us
 
 **Use a [skeleton](/components/skeleton/react) when:**
 - You know what the populated data is going to look like (even if it results in an empty state).
+- The structure of the data has fully loaded and can be displayed.