Ajford76 patch 1 (SharePoint#3108)

* Edits.

* Edits.

* Edits.

* Edit.

* Create semantic_slots.md

* Add files via upload

* Update semantic_slots.md

* Update semantic_slots.md

* Update semantic_slots.md

* Add files via upload

* Add files via upload

* Update semantic_slots.md

Edited article to simplify and follow cadence of other articles

Author: ajford76

docs/design/designing-a-web-part-icon.md

@@ -4,27 +4,27 @@ description: Learn how to design a web part icon that will look great in SharePo
 ms.date: 08/24/2018
 ---
 
-# Designing a web part icon
+# Designing a SharePoint web part icon
 
-Web Part icons are designed to be simple, representative, and symbolic. Every icon is reduced to a minimalistic style to represent the most essential attributes. Icons will display in the toolbox within SharePoint pages and optionally in the store.
+Web part icons are designed to be simple, representative, and symbolic. Every icon is reduced to a minimalist style that represents the most essential attributes. Icons will display in the toolbox within SharePoint pages and optionally in the store. Examples of icon shapes are square, circle, veritical, and horizontal.
 
 ![Icon examples](../images/01_Icons_examples.png)
 
 ## Grid keyline shapes
 
-Web parts icons are displayed at 32x32 px but designed at 2x the size or 64x64px. Create icons at 100% to ensure pixels are accurate. 
+Web part icons are displayed at 32x32 px but are designed at twice the size, or 64x64 px. Create icons at 100% to ensure that pixels are accurate. 
 
 ![Web part icon grid](../images/02_Icons_sizes.png)
 
 ## Layout
 
-Icons should be designed inside of the 64 x 64 pixel container area, to insure that the icons renders correctly. 
+Design icons within the 64x64 px container area. This ensures that the icon renders correctly. 
 
-![Example grid for web part icons at 64px](../images/03_Icons_Layout.png)
+![Grid example for web part icons at 64px](../images/03_Icons_Layout.png)
 
 ## Shapes
 
-Not all icons or logos are designed in a perfect square. Use this guide of basic shapes to understand how to unify different icon shapes within the grid and appear at a proportional size. Make sure that the icon fills either the full width or height of the grid depending on its shape.
+Not all icons or logos are designed in a perfect square. Use this guide of basic shapes to understand how to unify different icon shapes within the grid and have them appear at a proportional size. Make sure that the icon fills either the full width or full height of the grid, depending on its shape.
 
 ![Example of aligning icons that are differnt shapes within the grid](../images/04_Icons_shapes.png)
 
@@ -37,15 +37,15 @@ Try to avoid any icon distortion by snapping your edges to the X and Y coordinat
 
 ## Colors and backgrounds
 
-The icon is the visual expression of your web part and its function. They can help communicate the core idea of your web part simply and boldly.
+The icon is the visual expression of your web part and its function. Icons can help communicate the core idea of your web part simply and boldly.
 
-Web part icons can contain one color or be full color. Most icons work best when using extremely simplified shapes, thin two-pixel lines similar to the Office UI Fabric icons. In some cases there may be a need to use a company brand icon or logo mark in full color. If there is a one color version of the icon available consider using this version first.
+Web part icons can contain one color or be full color. Most icons work best when you use simplified shapes, thin two-pixel lines similar to the Office UI Fabric icons. In some cases, you might need to use a company brand icon or logo in full color. If a one-color version of the icon is available, consider using this version.
 
-![One color, two color and full color icon examples](../images/06_Icons_colors.png)
+![One color, two color, and full color icon examples](../images/06_Icons_colors.png)
 
 ## Exporting your icons
 
-Icons should be exported as SVGs at 64x64 px and should have transparent backgrounds.
+Export icons as SVGs at 64x64 px with transparent backgrounds.
 
 You can find the icon grid in the [SharePoint Design toolkit](https://developer.microsoft.com/en-us/fabric#/resources).
 

docs/design/layout-patterns.md

@@ -1,49 +1,49 @@
 ---
 title:  Layout patterns
-description: Common web part layout types and responsive patterns
+description: Find common SharePoint web part layout types and responsive patterns.
 ms.date: 08/24/2018
 ---
 
-# Web part layouts
+# SharPoint web part layouts
 
-SharePoint uses a number of different layout types for web parts. The most commonly used are grid, list, filmstrip, carousel and compact. Each one of these five layouts serves a different purpose depending on a page layout, breakpoints and content density. 
+SharePoint uses a number of different layout types for web parts. The most common are grid, list, filmstrip, carousel, and compact. Each one of these five layouts serves a different purpose, depending on the layout, breakpoints, and content density of a page. 
 
-When selecting a layout that works best for your web part consider the type of content you are displaying. Is it highly visual or rich in text and data. Determine how much space is needed on the page for enough content to be displayed. Consider trucating descriptions that may be lengthy to optimize for displaying more itmes to the end user. Remember that the [property pane](reactive-and-nonreactive-web-parts.md) can be leveraged to let authors have control of how much content is displayed.
+When selecting a layout that works best for your web part, consider the type of content you are displaying. Is it highly visual or rich in text and data? Determine how much space is needed on the page for enough content to be displayed. Consider shortening long descriptions to optimize for displaying more itmes to the user. Remember that you can use the [property pane](reactive-and-nonreactive-web-parts.md) to let authors have control over how much content is displayed.
 
 ![Carousel with icons representing the common layouts](../images/01_Layouts_webparts.png)
 
-## Grid and Filmstrip
+## Grid and filmstrip
 
-Grid and filmstrip layouts are very much alike, they both use cards to showcase content. However, other rectangular content also works well in these layouts such as images. The major difference between the two layouts are how they reflow based on varioius screen sizes or breakpoints.
+Grid and filmstrip layouts are similar. They both use cards to showcase content. However, other rectangular content also works well in these layouts, such as images. The main difference between the two layouts is how they reflow based on varioius screen sizes or breakpoints.
 
 ### Grid layout
 
-The Grid reflows in rows and columns from top to bottom and can contain a few to many items at a time.
+The grid reflows in rows and columns from top to bottom and can contain a few to many items at a time.
 
 ![Animated gif showing the Grid layout reflowing across breakpoints](../images/layouts_animation_grid.gif)
 
 ### Filmstrip layout
 
-The Filmstrip display multiple items in a single row and caroesels to a new set of items.
+The filmstrip displays multiple items in a single row and caoursels to a new set of items.
 
 ![Animated gif showing the Filmstrip layout reflowing across breakpoints](../images/layouts_animation_filmstrip.gif)
 
 
 ## List
 
-Using the List layout can be useful to display large amount of info in a compact manner. When resizing the lesser important columns will hide as the page width get smaller.
+The list layout is useful for displaying a large amount of information in a compact way. When resized, the less important columns will be hidden as the page width gets smaller.
 
 ![Animated gif showing the List layout reflowing across breakpoints](../images/layouts_animation_list.gif)
 
 ## Carousel
 
-Want to Showcase content featuring really nice visuals? Go with the Carousel layout. This layout is designed to display visual content such as images, PowerPoint files or simillar in a one by one item carousel.
+If you want to showcase content featuring attractive visuals, choose the carousel layout. This layout is designed to display visual content such as images or PowerPoint files in a one-by-one item carousel.
 
 ![Animated gif showing the Carousel layout reflowing across breakpoints](../images/layouts_animation_carousel.gif)
 
 ## Compact
 
-The Compact layout is designed to show content in a smaller format and works the best in a 1/3rd column. This layout can support a small image or icon and a few rows of text for a title, description and/or metadata.
+The compact layout is designed to show content in a smaller format and works the best in a one-third column. This layout can support a small image or icon and a few rows of text for a title, description, and/or metadata.
 
 ![Animated gif showing the Compact layout reflowing across breakpoints](../images/layouts_animation_compact.gif)
 

docs/design/semantic_slots.md

@@ -0,0 +1,80 @@
+---
+title:  Designing for section backgrounds using semantic slots
+description: Learn how to design your web part to take advantage of section backgrounds using semantic slots.
+ms.date: 12/06/2018
+---
+
+# Overview
+
+When designing web parts for section backgrounds, you can use Office UI Fabric’s semantic slot system to guarantee accessibility and to enforce consistency across SharePoint sites. Semantic slots target customizations of specific page elements in order to align color usage and interaction patterns. They also allow you the flexibility to add or assign multiple palette colors for your components so they look great on all section backgrounds. This article will provide examples for semantic slots and how to incorporate them into your web part designs. Before getting started, you should be familiar with [how to design a SharePoint web part](https://docs.microsoft.com/en-us/sharepoint/dev/design/design-a-web-part) in order to understand the basic structure of web parts. You should also be familiar with [themes and colors in SharePoint](https://docs.microsoft.com/en-us/sharepoint/dev/design/themes-colors).
+
+## Section background
+
+Section background is a feature that applies background color to a canvas section on a page. There are four background color options for light and dark themes: None, Neutral, Soft, Strong. Section backgrounds are defined by a Office UI Fabric palette color from a site's theme. With the introduction of the section background feature, semantic slots allow page elements to be accessible on various themes and section backgrounds.
+
+## Variant vs. Section background
+
+A variant describes different values of color generated from an existing theme. A variant will share the same set of colors as the original theme it was generated from, but will apply those colors differently. See [Office UI Fabric variant documentation](https://github.com/OfficeDev/office-ui-fabric-react/blob/master/packages/variants/README.md) for more detail.
+
+A Section Background allows the user to apply a variant color from the theme to a canvas section. Both concepts share "Neutral", "Soft", and "Strong" options and can be used interachangeably when describing color usage.
+
+## Semantic slots
+
+A semantic slot is a theming slot that targets specific page elements. A Office UI Fabric palette color can be assigned to a specific page element without affecting other page elements using the same palette color. When designing for section backgrounds, you can assign a semantic slot a different color for each variant. A semantic slot can have up to eight different values to adapt to each section background option. This helps deliver consistent design patterns throughout various themes and section backgrounds.
+
+For example, default text uses the "bodyText" semantic slot. On the None, Neutral, and Soft section backgrounds, bodyText is assigned neutralPrimary. On the Strong section background, the palette color of bodyText changes to white. Semantic slots can be assigned palette colors for all variants in dark themes as well.
+
+In the table below, you can see all eight palette colors defined for the bodyText slot. 
+
+![Example table showing semantic slots on light and dark theme variants](../images/doc-semantic-slot-940px-table.png)
+
+<br/> 
+<table>
+<tr>
+<td> </td>
+<td> Light themes</td>
+<td> Dark themes</td>
+</tr>
+<tr>
+<td>None</td>
+<td>neutralPrimary #333333</td>
+<td>neutralPrimary #ffffff</td>
+</tr>
+<tr>
+<td>Neutral</td>
+<td style="background-color:red">neutralPrimary #333333</td>
+<td>neutralPrimary #ffffff</td>
+</tr>
+<tr>
+<td>Soft</td>
+<td>neutralPrimary #333333</td>
+<td>neutralPrimary #ffffff</td>
+</tr>
+<tr>
+<td>Strong</td>
+<td>white #ffffff</td>
+<td>white #1f1f1f</td>
+</tr>
+</table>
+<br/>
+
+! Note
+The current semantic slot list is defined by commonly used design patterns in SharePoint. We want to avoid creating case-specific semantic slots. When designing a new web part, consider aligning to an existing design pattern. Office UI Fabric's policy is that semantic slots may never be removed from the list, so any additions are permanent.
+
+## Identifying semantic slots in your designs
+
+Semantic slots should be assigned based on the function of a page element. The name of a semantic slot can quickly tell you how it’s meant to be used. You can find all existing semantic slots and their use case examples in the [Fabric semantic colors documentation](https://github.com/OfficeDev/office-ui-fabric-react/blob/master/packages/styling/src/interfaces/ISemanticColors.ts).
+
+Fabric palette colors should be referenced from your site theme’s color ramp. If your site is using a SharePoint out of the box theme, you can reference [SharePoint theme color ramps](https://fluentfabric.azurewebsites.net/#/color/products). If your site is using a custom theme, you can generate a unique color ramp using the [Fabric theme generator](https://developer.microsoft.com/en-us/fabric#/styles/themegenerator).
+
+![Example of redlines for a web part in the None section background](../images/doc-semantic-slot-1.png)
+
+In this example, the semantic slots are referencing palette colors from the None variant. The palette color may change depending on which variant you are using. Typically the variant should correspond with the value of bodyBackground. For example, if the bodyBackground value is "neutralLighter,” your slots should pick up values from the Neutral variant. Fabric palette colors for each variant should correspond with the palette colors listed in the Fabric theme documentation.
+
+## Web part designs with multiple variants
+
+There are instances in which a web part design will use multiple variants. The most common design pattern that uses multiple variants is the card layout. In your designs, you should differentiate which page elements correspond to which variant.
+
+![Example of multiple variant redlines for a web part in the Neutral section background](../images/doc-semantic-slot-2.png)
+
+In this example, all semantic slot redlines in blue are using palette colors defined by the None variant since they sit on the card background. All other content that isn’t on a card uses palette colors from the Neutral variant.

docs/design/themes-colors.md

@@ -6,7 +6,7 @@ ms.date: 05/21/2018
 
 # SharePoint themes and colors
 
-Like the Microsoft brand palette, the SharePoint themes are designed to build on the Microsoft brand, while at the same time allow for flexibility to enliven our partnerships without dominating them. They reveal our shared goals and personality, and they reflect our diversity and ability to optimize the SharePoint experience.
+Like the Microsoft brand palette, the SharePoint themes are designed to build on the Microsoft brand, while at the same time allowing for flexibility to enliven our partnerships without dominating them. They reveal our shared goals and personality, and they reflect our diversity and ability to optimize the SharePoint experience.
 
 ## Main colors
 

docs/design/web-part-levels.md

@@ -30,23 +30,23 @@ Second-level toolbars within a web part have three core commands: Edit, Move, an
 
 The second-level toolbar should only display when the author selects (clicks/taps) an individual item. Do not show all the second-level toolbars for every items at once, as this can overwhelm the user. Additionally, do not have the toolbar appear on hover, as this might cause usability issues with devices that support touch.
 
-The bounding box and/or outline of each second-level item should change from its default state to the primary color on hover and remain the primary color on selection. It is important that the bounding box and icons keep their active states so the user understands what item is selected when using the property pane or while re-arranging items.
+The bounding box and/or outline of each second-level item should change from its default state to the primary color on hover and remain the primary color on selection. It is important that the bounding box and icons keep their active states so the user understands what item is selected when they're using the property pane or while they're rearranging items.
 
-Below is an example from an individual 2nd level item in the Image gallery web part:
+The following is an example from an individual second-level item in the Image gallery web part:
 
-Edit Item Level – opens the property pane with specific item level configuration options. Note that the bounding box stays in the active/selected state.
+**Edit Item Level** – opens the property pane with specific item-level configuration options. Note that the bounding box stays in the active/selected state.
 
-Move – The transparency of the item drops to 65% and a drop shadow surrounds the item.
+**Move** – The transparency of the item drops to 65% and a drop shadow surrounds the item.
 
-Remove – When the X Remove icon is selected the toolbar hides and the item fades out making room for the specific layout to reflow.
+**Remove** – When the X Remove icon is selected, the toolbar hides and the item fades out, making room for the specific layout to reflow.
 
 ![Selection states of a second level item, example individual image in the Image Gallery web part](../images/03_WebpartLevels_InteractionStates.png)
 
 ## Property panes
 
-Property panes work the same on the 2nd item level of a web part as they do when first selecting the entire web part. The focus on the 1st level shifts to the second level selection and allows the author to configure and individual item.
+Property panes work the same way on the second item level of a web part that they do when first selecting the entire web part. The focus on the first level shifts to the second level selection and allows the author to configure an individual item.
 
-In the example below the 1st level is the Image source and Layout configuration for the Image gallery web part. When the user selects an individual image they can configure the Title, Caption and Alternative text on the 2nd level property pane.
+In the following example, the first level is the Image source and Layout configuration for the Image gallery web part. When the user selects an individual image, they can configure the Title, Caption, and Alternative text on the second-level property pane.
 
 ![Property pane comparision between 1st and 2nd level](../images/04_WebpartLevels_PropertyPanes.png)