docs: grammar and style corrections (#3354)

* docs: grammar fixes in fast-components and fast-element

* docs: grammar fixes to fast-foundation docs

* docs: grammar fixes in readmes

* docs: grammar fixes to other docs

* docs: apply guidance from style guide

* Update packages/web-components/fast-components-msft/README.md

Co-authored-by: Chris Holt <chhol@microsoft.com>

* docs: fix up some design language wording to make fluent clearer

* docs: adjust explanation in faq for fluent, fluent ui, and fast

* docs(faq): fix typo

* docs(faq): messaging clarity after discussion

Co-authored-by: Chris Holt <chhol@microsoft.com>

README.md

@@ -33,7 +33,7 @@ Have you ever wanted to improve your app's startup time, render speed, or memory
 
 Have you ever wanted to adopt more web standards and build your site or app on a native web foundation that's immune to the shifting sands of the modern JavaScript front-end landscape? _**That's FAST.**_
 
-Let's take a look at what each of FAST's core packages give us today.
+Let's take a look at what each of FAST's core packages gives us today.
 
 ### fast-element
 
@@ -56,14 +56,14 @@ This package does not export Web Components registered as [custom elements](http
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![npm version](https://badge.fury.io/js/%40microsoft%2Ffast-components.svg)](https://badge.fury.io/js/%40microsoft%2Ffast-components)
 
-`fast-components` is a library of Web Components that *composes* the exports of `fast-foundation` with stylesheets aligning to the FAST design language. This composition step registers a custom element. See the [quick start](http://fast.design/components/getting-started) to get stared using the components.
+`fast-components` is a library of Web Components that *composes* the exports of `fast-foundation` with stylesheets aligning to the FAST design language. This composition step registers a custom element. See the [quick start](http://fast.design/components/getting-started) to get started using the components.
 
 ### fast-components-msft
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![npm version](https://badge.fury.io/js/%40microsoft%2Ffast-components-msft.svg)](https://badge.fury.io/js/%40microsoft%2Ffast-components-msft)
 
-`fast-components-msft` is another library of Web Components that *composes* `fast-foundation`. `fast-components-msft` uses the same custom element names as `fast-components`, but makes use of different stylesheets that align to the Microsoft design language.
+`fast-components-msft` is a library of Web Components that *composes* `fast-foundation`. `fast-components-msft` uses the same custom element names as `fast-components`, but makes use of different stylesheets that support Microsoft's Fluent design language.
 
 ### Component Explorer
 
@@ -88,7 +88,7 @@ There are a million and one great ways to build your next website or application
 This principle of being unopinionated manifests in several important ways including:
 
 * A flat component architecture that lets you compose what you need without struggling with rigid patterns and complex objects.
-* Separating base components from styles and design systems to support multiple implementations without re-writing or duplicating styles. Use the design system to customize existing styled components, or build your own styles, with your design system, without having to re-build or duplicate the base components.
+* Separating base components from styles and design systems to support multiple implementations without re-writing or duplicating styles. Use the design system to customize existing styled components, or build your own styles, with your design system, without having to rebuild or duplicate the base components.
 * Framework agnostic tooling that lets you use our development tools with any view framework.
 * The ability to replace almost any FAST package with your package of choice. Get started with our animation package and add more as you need them. Alternatively, use our suite of packages to build your next project from the ground up; it's your call.
 
@@ -108,9 +108,9 @@ Because FAST has abstracted base components from their style, you get a head sta
 
 ## Contact
 
-* Join the community and chat with us in realtime on [Discord](https://discord.gg/FcSNfg4).
-* Ask questions on [Stack Overflow](https://stackoverflow.com/questions/tagged/fast-dna).	
-* Submit requests and issues on [Github](https://github.com/Microsoft/fast-dna/issues/new/choose).	
+* Join the community and chat with us in real-time on [Discord](https://discord.gg/FcSNfg4).
+* Ask questions on [Stack Overflow](https://stackoverflow.com/questions/tagged/fast-dna). 
+* Submit requests and issues on [Github](https://github.com/Microsoft/fast-dna/issues/new/choose).  
 * Contribute by helping out on some of our recommended first issues on [Github](https://github.com/Microsoft/fast-dna/labels/good%20first%20issue).
 
 ## Status

packages/README.md

@@ -3,6 +3,6 @@
 FAST is organized as a monorepo and this is where you'll find the packages we publish.
 
 * `web-components` - Packages that are directly related to web component technologies. This includes tech for building components, our components library, and our design system implementations.
-* `utilities` - General purpose packages useful in creating web apps and sites. This includes tech for colors, animation, linting,e tc.
+* `utilities` - General purpose packages useful in creating web apps and sites. This includes tech for colors, animation, linting, etc.
 * `tooling` - Packages that contain design and prototyping tools.
-* `react` - Legacy React component which predate the modern web component work.
+* `react` - Legacy React components that predate the modern web component work.

packages/web-components/README.md

@@ -23,11 +23,11 @@ This package does not export Web Components registered as [custom elements](http
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![npm version](https://badge.fury.io/js/%40microsoft%2Ffast-components.svg)](https://badge.fury.io/js/%40microsoft%2Ffast-components)
 
-`fast-components` is a library of Web Components that *composes* the exports of `fast-foundation` with stylesheets aligning to the FAST design language. This composition step registers a custom element. See the [quick start](http://fast.design/components/getting-started) to get stared using the components.
+`fast-components` is a library of Web Components that *composes* the exports of `fast-foundation` with stylesheets aligning to the FAST design language. This composition step registers a custom element. See the [quick start](http://fast.design/components/getting-started) to get started using the components.
 
 ## fast-components-msft
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![npm version](https://badge.fury.io/js/%40microsoft%2Ffast-components-msft.svg)](https://badge.fury.io/js/%40microsoft%2Ffast-components-msft)
 
-`fast-components-msft` is another library of Web Components that *composes* `fast-foundation`. `fast-components-msft` uses the same custom element names as `fast-components`, but makes use of different stylesheets that align to the Microsoft design language.
+`fast-components-msft` is a library of Web Components that *composes* `fast-foundation`. `fast-components-msft` uses the same custom element names as `fast-components`, but makes use of different stylesheets that support Microsoft's Fluent design language.

packages/web-components/fast-components-msft/README.md

@@ -3,7 +3,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![npm version](https://badge.fury.io/js/%40microsoft%2Ffast-components-msft.svg)](https://badge.fury.io/js/%40microsoft%2Ffast-components-msft)
 
-`fast-components-msft` is another library of Web Components that *composes* `fast-foundation`. `fast-components-msft` uses the same custom element names as `fast-components`, but makes use of different stylesheets that align to the Microsoft design language.
+`fast-components-msft` is a library of Web Components that *composes* `fast-foundation`. `fast-components-msft` uses the same custom element names as `fast-components`, but makes use of different stylesheets that support Microsoft's Fluent design language.
 
 ## Installation
 

packages/web-components/fast-components/docs/design/color.md

@@ -10,21 +10,26 @@ FAST utilizes an adaptive color system that provides some unique advantages:
 - Color themeing through palette tinting.
 - Perceptually uniform UI across different background colors.
 
-## Algorithmic Colors (Recipes)
+## Algorithmic colors (recipes)
+
 FAST makes heavy use of algorithmic colors; named colors are a product of the *designSystem* object in which they are calculated. In the documentation below, these algorithmic colors will be referred to as *recipes*.
 
 ### Inputs
+
 Each color recipe expects as its sole argument the FAST *DesignSystem* object, but there are a few core pieces of data from that object that impact color resolution.
 
 ### Palettes
+
 Each color recipe operates on a palette. A palette in an array of hexadecimal colors ordered from light to dark. By default, FAST components leverage the `neutralPalette` and the `accentPalette`.
 
 See [accentPalette](api/fast-components.fastdesignsystemprovider.accentpalette.md) and [neutralPalette](api/fast-components.fastdesignsystemprovider.neutralpalette.md) for more details.
 
-#### Replacing Palettes
+#### Replacing palettes
+
 `@microsoft/fast-components` exposes a convenient function to generate a color palette from an arbitrary source color, and this function is how the default `neutralPalette` and `accentPalette` are generated. You can generate a new palette by choosing a palette source color and invoking the palette generation function:
 
-##### Replacing the Neutral Palette
+##### Replacing the neutral palette
+
 ```js
 import { parseColorHexRGB } from "@microsoft/fast-colors";
 import { createColorPalette } from "@microsoft/fast-components";
@@ -41,7 +46,8 @@ const provider = document.querySelector("fast-design-system-provider");
 provider.neutralPalette = palette;
 ```
 
-##### Replacing the Accent Palette
+##### Replacing the accent palette
+
 The same approach can be taken for the `accentPalette`, but when doing so the `accentPaletteBaseColor` should *also* be replaced:
 
 ```js
@@ -57,15 +63,18 @@ provider.accentPalette = palette;
 ```
 
 ### Background color
-This is the contextual color that the recipe uses to determine what color it is rendering on. The foreground, outline, and divider recipes will use this color to ensure that the color created is accessible and meets contrast requirements. In fill recipes it is sometimes used as the starting location in the appropriate palette to begin resolution.
+
+This is the contextual color that the recipe uses to determine what color it is rendering on. The foreground, outline, and divider recipes will use this color to ensure that the color created is accessible and meets contrast requirements. In fill recipes, it is sometimes used as the starting location in the appropriate palette to begin resolution.
 
 See [backgroundColor](api/fast-components.fastdesignsystemprovider.backgroundcolor.md) for more details.
 
 ### Offsets
 Some recipes also leverage offset values, typically for *states* (rest, hovered, active, selected). These offsets are used to retrieve a color at the sum of the offset and some reference index (usually the index of the rest color or the background color in the palette).
 
-## Color Recipes
-### Using Color Recipes
+## Color recipes
+
+### Using color recipes
+
 First, ensure the UI element has a *FASTDesignSystemProvider* ancestor element - this element will *resolve* the recipe for a component within it that declares a dependency on the recipe.
 
 ```html
@@ -92,8 +101,10 @@ const styles = css`
 );
 ```
 
-### Neutral Recipes
-#### Layer Recipes
+### Neutral recipes
+
+#### Layer recipes
+
 Layer recipes represent the UI layers and surfaces that individual UI elements are contained within. They are applied to primary regions such as toolbars, sidebars, canvas regions, fly-outs, dialogs, and cards.
 
 | Behavior Name | CSS Custom Property | Description |
@@ -108,6 +119,7 @@ Layer recipes represent the UI layers and surfaces that individual UI elements a
 | `neutralLayerL4Behavior` | `--neutral-layer-l4`| Used as the background for the lowest command surface or title bar, logically below L3. |
 
 #### Text
+
 Neutral text recipes address *most* cases of text used in a UI, from interactive element text, headings, and body text.
 
 | Behavior Name | CSS Custom Property | Description |
@@ -118,7 +130,8 @@ Neutral text recipes address *most* cases of text used in a UI, from interactive
 | `neutralForegroundHintBehavior` | `--neutral-foreground-hint`| Secondary *hinting* text to be used with [non-large text](https://www.w3.org/TR/WCAG/#contrast-minimum) to meet a 4.5:1 contrast ratioBehavior to the background. |
 | `neutralForegroundHintLargeBehavior` | `--neutral-foreground-hint-large`| Secondary *hinting* text to be used with [large text](https://www.w3.org/TR/WCAG/#contrast-minimum) to meet a 3:1 contrast ratio to the background. |
 
-#### Fills (Backgrounds)
+#### Fills (backgrounds)
+
 Neutral fills are indented to be used as fill colors (background) to UI elements to distinguish them from the background. 
 
 | Behavior Name | CSS Custom Property | Description |
@@ -132,7 +145,8 @@ Neutral fills are indented to be used as fill colors (background) to UI elements
 | `neutralFillStealthActiveBehavior`| `--neutral-fill-stealth-active` | Used as the fill of a `neutralFillStealth` element when active. |
 | `neutralFillStealthSelectedBehavior`| `--neutral-fill-stealth-selected` | Used as the fill of a `neutralFillStealth` element when selected. |
 
-#### Outlines and Dividers
+#### Outlines and dividers
+
 Neutral outlines are used to construct outline controls and dividers.
 
 | Behavior Name | CSS Custom Property | Description |
@@ -143,6 +157,7 @@ Neutral outlines are used to construct outline controls and dividers.
 | `neutralDividerRestBehavior` | `--neutral-divider-rest` | Used as the color for divider elements. |
 
 #### Toggles
+
 Toggle elements such as checkboxes and switches use a specific set of recipes.
 
 | Behavior Name | CSS Custom Property | Description |
@@ -154,6 +169,7 @@ Toggle elements such as checkboxes and switches use a specific set of recipes.
 | `neutralFillToggleActiveBehavior` | `--neutral-foreground-active` | Used as the fill of a `neutralFillToggle` element when active. |
 
 #### Inputs
+
 Text input elements also have a set of recipes specifically tailored.
 
 | Behavior Name | CSS Custom Property | Description |
@@ -163,13 +179,15 @@ Text input elements also have a set of recipes specifically tailored.
 | `neutralFillInputActiveBehavior` | `--neutral-fill-input-active` | Used as the fill of the text input when active. |
 | `neutralFillInputSelectedBehavior` | `--neutral-fill-input-selected` | Used as the fill of the text input when selected. |
 
-#### Document Focus
+#### Document focus
+
 | Behavior Name | CSS Custom Property | Description |
 |---------------|---------------------|-------------|
 | `neutralFocusBehavior` | `--neutral-focus` | The color of the focus indicator when the element has document focus. |
 | `neutralFocusInnerAccentBehavior` | `--neutral-focus-inner-accent` | The color of the inner focus-indicator when an *accent fill* element has document focus. |
 
-### Accent Recipes
+### Accent recipes
+
 Accent recipes use the accent palette and are intended to bring attention or otherwise distinguish the element on the page. 
 
 | Behavior Name | CSS Custom Property | Description |

packages/web-components/fast-components/docs/design/design-system.md

@@ -8,7 +8,8 @@ In FAST, the *design system* is a collection of properties and values that infor
 
 For the purposes of this section, just know the *DesignSystemProvider* is a Custom Element that will create CSS Custom Properties that can be consumed by component stylesheets and provide mechanisms to synchronize, update, and consume those properties programmatically.
 
-### Design System Properties
+### Design system properties
+
 The following properties are provided by the `FASTDesignSystemProvider` and should be used as appropriate.
 
 | Name                                   | Type | Description   |

packages/web-components/fast-components/docs/design/introduction.md

@@ -6,7 +6,8 @@ custom_edit_url: https://github.com/microsoft/fast-dna/edit/master/packages/web-
 
 `@microsoft/fast-components` leverages `@microsoft/fast-element` to style components. For details on how to apply CSS, see [leveraging CSS](fast-element/leveraging-css.md).
 
-## Hiding Undefined Elements
+## Hiding undefined elements
+
 Custom Elements that have not been [upgraded](https://developers.google.com/web/fundamentals/web-components/customelements#upgrades) and don't have styles attached can still be rendered by the browser but they likely do not look how they are supposed to. To avoid a *flash of un-styled content* (FOUC), visually hide Custom Elements if they have not been *defined*:
 
 ```CSS

packages/web-components/fast-components/docs/design/match-media-stylesheets.md

@@ -6,7 +6,8 @@ custom_edit_url: https://github.com/microsoft/fast-dna/edit/master/packages/web-
 
 FAST exposes a mechanism to attach stylesheets conditionally based on a [MatchMedia](https://developer.mozilla.org/en-US/docs/Web/API/Window/matchMedia) query.
 
-### MatchMedia Stylesheets
+### MatchMedia stylesheets
+
 `matchMediaStylesheetBehaviorFactory` can be used to construct a Behavior that will conditionally attach stylesheets based on the `matches` property of a [MediaQueryList](https://developer.mozilla.org/en-US/docs/Web/API/MediaQueryList).
 
 __Example: Using the `matchMediaStylesheetBehaviorFactory`__
@@ -25,7 +26,8 @@ const styles = css`
 )
 ```
 
-### Forced-colors Stylesheets
+### Forced-colors stylesheets
+
 FAST has a commitment to facilitating accessible web experiences and [forced-colors](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/forced-colors) support is a core tenant of that commitment. `@microsoft/fast-components` exports the `forcedColorsStylesheetBehavior` utility to provide a simple mechanism to apply forced-color stylesheets without bloating the component stylesheet in non-forced-color environments. This Behavior is built using [MatchMedia Stylesheets](#matchmedia-stylesheets).
 
 __Example: Forced-colors stylesheets__

packages/web-components/fast-element/docs/ACKNOWLEDGEMENTS.md

@@ -1,10 +1,10 @@
 # Acknowledgements
 
-There are many great open source projects that have inspired us and enabled us to build the FAST. Below are a few that stand out.
+There are many great open source projects that have inspired us and enabled us to build FAST. Below are a few that stand out.
 
 * [Aurelia 1 and Aurelia 2](https://aurelia.io/) - Various details of Aurelia 2's decorator and metadata model inspired us in the design of `fast-element`. Additionally, Aurelia 1's mechanisms for array observation, binding, and template compilation also guided us in our work.
 * [faastjs](https://github.com/faastjs) - A project with a similar name but a very different purpose. Their API documentation approach leveraging [api-extractor](https://api-extractor.com/) was a huge help to us.
 * [Knockout](https://knockoutjs.com/) - One of the first JavaScript libraries (if not the first) to implement an observer system. The original techniques for observables and computed observables have influenced many libraries over the years. Re-interpreting these ideas in terms of modern JavaScript and DOM has helped us to build a powerful and robust system.
 * [lit-html](https://lit-html.polymer-project.org/) - One of the first libraries to leverage standard JavaScript tagged template literals for HTML templates. We were inspired by this technique and wanted to explore whether it could be combined with our idea of arrow function binding expressions.
 * [Polymer](https://www.polymer-project.org/) - One of the first libraries (if not the first) to embrace Web Components.
-* [Vue](https://vuejs.org/) - We liked the terseness of the `:` and `@` syntax in templates, so we adapted it with some modifications in our own templates.
+* [Vue](https://vuejs.org/) - We liked the terseness of the `:` and `@` syntax in templates, so we adapted it along with some modifications in our templates.