@@ -178,7 +178,7 @@ Here are a couple of quick notes on slots:
```
* You do not need to provide content for every declared slot. In the above example, just because the `name-tag` has an "avatar" slot does not mean we must provide content for that slot. If no content is provided for a slot, then nothing will be rendered at that location, unless the slot declared fallback content...
-## Fallback Content
+## Fallback content
There are several scenarios for using slots in your elements. So far, we've been showing how to use slots for content projection. However, another major use case is to enable various parts of your element's rendering to be replaced by the software using your element. To enable this, you can provide *fallback content* for any slot. This content will render if the element consumer provides no content for that slot, but if they do, their own content will override the fallback content.
@@ -201,7 +201,7 @@ In addition to the declarative means of using slots described so far, the browse
| API | Description |
| ------------- |-------------|
| `slotchange` | By adding an event listener for the `slotchange` event on a `slot` element, you can receive notifications any time the slotted nodes of a particular slot change. |
-| `assignedNodes()` | The `slot` element provides an `assignedNodes()` method that can be called to get a list of all nodes that a particular slot currently renders. You can pass an option object with `{ flatten: true }` if you wish to also see fallback content nodes. |
+| `assignedNodes()` | The `slot` element provides an `assignedNodes()` method that can be called to get a list of all nodes that a particular slot currently renders. You can pass an options object with `{ flatten: true }` if you wish to also see fallback content nodes. |
| `assignedSlot` | The `assignedSlot` property is present on any element that has been projected to a slot so that you can determine where it is projected. |
:::tip
@@ -229,7 +229,7 @@ Here are some events which do not compose and are only visible from within the S
To get the fully composed event path from an event object, invoke the `composedPath()` method on the event itself. This will return an array of targets representing the path through which the event bubbled. If your custom element uses `closed` Shadow DOM mode, targets within the Shadow DOM will not be present in the composed path, and it will appear as if the custom element itself was the first target.
-### Custom Events
+### Custom events
In various scenarios, it may be appropriate for a custom element to publish its own element-specific events. To do this, you can use the `$emit` helper on `FASTElement`. It's a convenience method that creates an instance of `CustomEvent` and uses the `dispatchEvent` API on `FASTElement` with the `bubbles: true` and `composed: true` options. It also ensures that the event is only emitted if the custom element is fully connected to the DOM. Here's an example:
@@ -250,7 +250,7 @@ export class MyInput extends FASTElement {
When emitting custom events, ensure that your event name is always lower-case, so that your Web Components stay compatible with various front-end frameworks that attach events through DOM binding patterns (the DOM is case insensitive).
:::
-## Shadow DOM Configuration
+## Shadow DOM configuration
In all the examples we've seen so far `FASTElement` automatically creates a Shadow Root for your element and attaches it in `open` mode. However, if desired, you can specify `closed` mode or make the element render into the Light DOM instead. These choices can be made by using the `shadowOptions` setting with your `@customElement` decorator.
@@ -285,7 +285,7 @@ export class NameTag extends FASTElement {
```
:::important
-If you choose to render to the Light DOM, you will not be able to compose content, use slots, or leverage encapsulated styles. Light DOM rendering is not recommended for re-usable components. It may have some limited use as the root component of a small app.
+If you choose to render to the Light DOM, you will not be able to compose the content, use slots, or leverage encapsulated styles. Light DOM rendering is not recommended for reusable components. It may have some limited use as the root component of a small app.
:::
In addition to the Shadow DOM mode, `shadowOptions` exposes all the options that can be set through the standard `attachShadow` API. This means that you can also use it to specify new options such as `delegatesFocus: true`. You only need to specify options that are different from the defaults mentioned above.
\ No newline at end of file
diff --git a/packages/web-components/fast-foundation/docs/integrations/aspnet.md b/packages/web-components/fast-foundation/docs/integrations/aspnet.md
index 6d6d15e9f79..28b9f878e34 100644
--- a/packages/web-components/fast-foundation/docs/integrations/aspnet.md
+++ b/packages/web-components/fast-foundation/docs/integrations/aspnet.md
@@ -7,11 +7,11 @@ custom_edit_url: https://github.com/microsoft/fast-dna/edit/master/packages/web-
FAST works naturally with ASP.NET server-side development, by simply adding a script tag and using the custom HTML elements. Let's take a look at how to set things up.
-## Setting up the ASP.NET Project
+## Setting up the ASP.NET project
First, you'll need to make sure that you have the .NET SDK installed. You can learn more and download that [on the official site](https://dotnet.microsoft.com/download).
-With the SDK installed, you have access to the `dotnet` command line interface. This can be used to create a new ASP.NET project. For example, to create a new ASP.NET Core MVC Web App named "fast-aspnet", you would use the following command:
+With the SDK installed, you have access to the `dotnet` command-line interface. This can be used to create a new ASP.NET project. For example, to create a new ASP.NET Core MVC Web App named "fast-aspnet", you would use the following command:
```shell
dotnet new mvc -o fast-aspnet
@@ -19,7 +19,7 @@ dotnet new mvc -o fast-aspnet
Create a project using the command above if you don't already have one. When the CLI completes, you should have a basic runnable ASP.NET Core MVC application.
-## Configuring Scripts
+## Configuring scripts
Now that we've got our basic project setup, we need to add our web components script and update ASP.NET accordingly. You can either add the script from our CDN directly, or you can install it with NPM and then add that.
@@ -53,7 +53,7 @@ npm install --save @microsoft/fast-components @microsoft/fast-element lodash-es
In this case, because Webpack can tree-shake unused components, you'll also want to be sure to explicitly import the components you want to use somewhere in your own JavaScript code. See [our Webpack guide](./webpack) for an example.
-## Using the Components
+## Using the components
Regardless of which path you've chosen above, you should be all set to start using the components. The first component we want to set up is the `` component. This configures the design system that will govern the appearance of all of the components. The best place to put this is at the root of your app, wrapping all your HTML. Here's an example of what your `_Layout.cshtml` might look like:
@@ -118,4 +118,4 @@ h2 {
}
```
-Congratulations! You're now setup to use FAST with ASP.NET. You can use more components, build your own components, and when you are ready, build and deploy your website or app to production.
+Congratulations! You're now set up to use FAST with ASP.NET. You can use more components, build your own components, and when you are ready, build and deploy your website or app to production.
diff --git a/packages/web-components/fast-foundation/docs/integrations/aurelia.md b/packages/web-components/fast-foundation/docs/integrations/aurelia.md
index 2843a37f5e2..62e95fa2152 100644
--- a/packages/web-components/fast-foundation/docs/integrations/aurelia.md
+++ b/packages/web-components/fast-foundation/docs/integrations/aurelia.md
@@ -9,7 +9,7 @@ FAST works flawlessly with both Aurelia 1 and Aurelia 2, with full integration i
## Aurelia 2
-### Setting up the Aurelia 2 Project
+### Setting up the Aurelia 2 project
First, you'll need to make sure that you have Node.js installed. You can learn more and download that [on the official site](https://nodejs.org/).
@@ -19,11 +19,11 @@ With Node.js installed, you can run the following command to create a new Aureli
npx makes Aurelia
```
-Follow the prompts, answering each question in turn. It is recommended that you select the "Default TypeScript Aurelia 2 App" when prompted, unless you have previous experience with the CLI. Be sure to choose to install dependencies when asked.
+Follow the prompts, answering each question in turn. It is recommended that you select the "Default TypeScript Aurelia 2 App" when prompted unless you have previous experience with the CLI. Be sure to choose to install dependencies when asked.
When the CLI completes, you should have a basic runnable Aurelia 2 application.
-### Configuring Packages
+### Configuring packages
Next, we'll install the FAST packages, along with supporting libraries. To do that, run this command from your new project folder:
@@ -31,7 +31,7 @@ Next, we'll install the FAST packages, along with supporting libraries. To do th
npm install --save @microsoft/fast-components @microsoft/fast-element lodash-es
```
-### Using the Components
+### Using the components
With all the basic pieces in place, let's run our app in dev mode with `npm start`. Webpack should build your project and open your default browser with your `index.html` page. Right now, it should only have a hello message, since we haven't added any code or interesting HTML. Let's change that.
@@ -99,11 +99,11 @@ fast-card > fast-button {
}
```
-Congratulations! You're now setup to use FAST and Aurelia 2!
+Congratulations! You're now set up to use FAST and Aurelia 2!
## Aurelia 1
-### Setting up the Aurelia 1 Project
+### Setting up the Aurelia 1 project
First, you'll need to make sure that you have Node.js installed. You can learn more and download that [on the official site](https://nodejs.org/).
@@ -119,11 +119,11 @@ And then use the CLI like this:
au new fast-aurelia
```
-Follow the prompts, answering each question in turn. It is recommended that you select the "Default TypeScript App" when prompted, unless you have previous experience with the CLI. Be sure to choose to install dependencies when asked.
+Follow the prompts, answering each question in turn. It is recommended that you select the "Default TypeScript App" when prompted unless you have previous experience with the CLI. Be sure to choose to install dependencies when asked.
When the CLI completes, you should have a basic runnable Aurelia 1 application.
-### Configuring Packages
+### Configuring packages
Next, we'll install the FAST packages, along with supporting libraries. To do that, run this command from your new project folder:
@@ -131,7 +131,7 @@ Next, we'll install the FAST packages, along with supporting libraries. To do th
npm install --save @microsoft/fast-components @microsoft/fast-element lodash-es
```
-### Using the Components
+### Using the components
With all the basic pieces in place, let's run our app in dev mode with `npm start`. Webpack should build your project and make it available at `http://localhost:8080/`. If you visit this address it should only have a hello message, since we haven't added any code or interesting HTML. Let's change that.
@@ -204,4 +204,4 @@ To add a splash of style, add the following to your `app.html` template:
```
-Congratulations! You're now setup to use FAST and Aurelia 1!
\ No newline at end of file
+Congratulations! You're now set up to use FAST and Aurelia 1!
\ No newline at end of file
diff --git a/packages/web-components/fast-foundation/docs/integrations/blazor.md b/packages/web-components/fast-foundation/docs/integrations/blazor.md
index 3bf21f2a020..fc87f2f516a 100644
--- a/packages/web-components/fast-foundation/docs/integrations/blazor.md
+++ b/packages/web-components/fast-foundation/docs/integrations/blazor.md
@@ -7,11 +7,11 @@ custom_edit_url: https://github.com/microsoft/fast-dna/edit/master/packages/web-
FAST works seamlessly with Blazor, including integration with Blazor's binding engine and components. Let's take a look at how to set things up.
-## Setting up the Blazor Project
+## Setting up the Blazor project
First, you'll need to make sure that you have the .NET SDK installed. You can learn more and download that [on the official site](https://dotnet.microsoft.com/download).
-With the SDK installed, you have access to the `dotnet` command line interface. This can be used to create a new Blazor project. For example, to create a new Blazor App named "fast-blazor", you would use the following command:
+With the SDK installed, you have access to the `dotnet` command-line interface. This can be used to create a new Blazor project. For example, to create a new Blazor App named "fast-blazor", you would use the following command:
```shell
dotnet new blazorwasm -o fast-blazor
@@ -19,7 +19,7 @@ dotnet new blazorwasm -o fast-blazor
Create a project using the command above if you don't already have one. When the CLI completes, you should have a basic runnable Blazor application. For more information on setting up and using Blazor, [see the official Blazor Getting Started guide](https://docs.microsoft.com/en-us/aspnet/core/blazor/get-started).
-## Configuring Scripts
+## Configuring scripts
Now that we've got our basic project setup, we need to add our web components script and update Blazor accordingly. You can either add the script from our CDN directly, or you can install it with NPM and then add that.
@@ -45,7 +45,7 @@ node_modules/@microsoft/fast-components/dist/fast-components.min.js
Copy this to your `wwwroot/script` folder and reference it with a script tag as described above.
-## Using the Components
+## Using the components
Regardless of which path you've chosen above, you should be all set to start using the components. The first component we want to set up is the `` component. This configures the design system that will govern the appearance of all of the components. The best place to put this is at the root of your app, wrapping all your HTML. Here's an example of what your `index.html` `` might look like:
@@ -100,4 +100,4 @@ fast-card > fast-button {
}
```
-Congratulations! You're now setup to use FAST with Blazor!
+Congratulations! You're now set up to use FAST with Blazor!
diff --git a/packages/web-components/fast-foundation/docs/integrations/webpack.md b/packages/web-components/fast-foundation/docs/integrations/webpack.md
index 82299a41153..6fdc8ea297d 100644
--- a/packages/web-components/fast-foundation/docs/integrations/webpack.md
+++ b/packages/web-components/fast-foundation/docs/integrations/webpack.md
@@ -7,7 +7,7 @@ custom_edit_url: https://github.com/microsoft/fast-dna/edit/master/packages/web-
FAST works great with TypeScript and Webpack, using a fairly standard setup. Let's take a look at how you can set up a TypeScript+Webpack project, starting from scratch.
-## Setting up the Package
+## Setting up the package
First, let's make a directory for our new project. From the terminal:
@@ -41,9 +41,9 @@ We also need to install the Webpack build tooling:
npm install --save-dev clean-webpack-plugin ts-loader typescript webpack webpack-cli webpack-dev-server
```
-## Adding Configuration and Source
+## Adding configuration and source
-Now that we've got our basic package and dependencies setup, let's create some source files and get things configured. Since we're going to be writing a bit of code, now is a great time to involve a code editor in the process. If you're looking for a great editor for TypeScript and front-end in general, we highly recommend [VS Code](https://code.visualstudio.com/).
+Now that we've got our basic package and dependencies set up, let's create some source files and get things configured. Since we're going to be writing a bit of code, now is a great time to involve a code editor in the process. If you're looking for a great editor for TypeScript and front-end in general, we highly recommend [VS Code](https://code.visualstudio.com/).
Open the `fast-webpack` folder in your favorite editor. You should see your `package.json` along with a `package-lock.json` and a `node_modules` folder.
@@ -157,7 +157,7 @@ To complete our setup, we need to add an `index.html` file to the root of our pr
There's nothing special about the HTML yet other than the `script` tag in the `body` that references the `bundle.js` file that our Webpack build will produce.
-## Using the Components
+## Using the components
With all the basic pieces in place, let's run our app in dev mode with `npm run dev`. Webpack should build your project and open your default browser with your `index.html` page. Right now, it should be blank, since we haven't added any code or interesting HTML. Let's change that.
@@ -219,4 +219,4 @@ This code imports the `` component as well as the `
After saving your `index.html` file, refresh your browser and you should see a card with text and a button.
-Congratulations! You're now setup to use FAST, TypeScript, and Webpack. You can import and use more components, build your own components, and when you are ready, build and deploy your website or app to production.
\ No newline at end of file
+Congratulations! You're now set up to use FAST, TypeScript, and Webpack. You can import and use more components, build your own components, and when you are ready, build and deploy your website or app to production.
\ No newline at end of file
diff --git a/packages/web-components/fast-foundation/src/accordion/README.md b/packages/web-components/fast-foundation/src/accordion/README.md
index e59fef664ab..9423123c61f 100644
--- a/packages/web-components/fast-foundation/src/accordion/README.md
+++ b/packages/web-components/fast-foundation/src/accordion/README.md
@@ -26,7 +26,7 @@ custom_edit_url: https://github.com/microsoft/fast-dna/edit/master/packages/web-
```
-## Applying Custom Styles
+## Applying custom styles
```ts
import { customElement } from "@microsoft/fast-element";
diff --git a/packages/web-components/fast-foundation/src/anchor/README.md b/packages/web-components/fast-foundation/src/anchor/README.md
index 55f97868072..a8009f16ec0 100644
--- a/packages/web-components/fast-foundation/src/anchor/README.md
+++ b/packages/web-components/fast-foundation/src/anchor/README.md
@@ -15,7 +15,7 @@ custom_edit_url: https://github.com/microsoft/fast-dna/edit/master/packages/web-
```
-## Applying Custom Styles
+## Applying custom styles
```ts
import { customElement } from "@microsoft/fast-element";
diff --git a/packages/web-components/fast-foundation/src/anchored-region/README.md b/packages/web-components/fast-foundation/src/anchored-region/README.md
index 030d43e3dea..4ca8cae0579 100644
--- a/packages/web-components/fast-foundation/src/anchored-region/README.md
+++ b/packages/web-components/fast-foundation/src/anchored-region/README.md
@@ -5,7 +5,7 @@ sidebar_label: fast-anchored-region
custom_edit_url: https://github.com/microsoft/fast-dna/edit/master/packages/web-components/fast-foundation/src/anchored-region/README.md
---
-## Applying Custom Styles
+## Applying custom styles
```ts
import { customElement } from "@microsoft/fast-element";
diff --git a/packages/web-components/fast-foundation/src/badge/README.md b/packages/web-components/fast-foundation/src/badge/README.md
index 034ac52f633..532317cebd1 100644
--- a/packages/web-components/fast-foundation/src/badge/README.md
+++ b/packages/web-components/fast-foundation/src/badge/README.md
@@ -31,7 +31,7 @@ fast-badge {
In addition to the color map support detailed above, the `fast-badge` from the Microsoft component implementation (`@microsoft/fast-components-msft`) includes an attribute to set default appearances which ensure WCAG 2.1 AA contrast requirements.
:::
-## Applying Custom Styles
+## Applying custom styles
```ts
import { customElement } from "@microsoft/fast-element";
diff --git a/packages/web-components/fast-foundation/src/button/README.md b/packages/web-components/fast-foundation/src/button/README.md
index fdd115befee..b9fb99810be 100644
--- a/packages/web-components/fast-foundation/src/button/README.md
+++ b/packages/web-components/fast-foundation/src/button/README.md
@@ -5,7 +5,7 @@ sidebar_label: button
custom_edit_url: https://github.com/microsoft/fast-dna/edit/master/packages/web-components/fast-foundation/src/button/README.md
---
-`fast-button` is a web component implementation of an [HTML button element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button). The component supports several visual apperances (accent, lightweight, neutral, outline, stealth).
+`fast-button` is a web component implementation of an [HTML button element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button). The component supports several visual appearances (accent, lightweight, neutral, outline, stealth).
## Usage
@@ -15,7 +15,7 @@ custom_edit_url: https://github.com/microsoft/fast-dna/edit/master/packages/web-
```
-## Applying Custom Styles
+## Applying custom styles
```ts
import { customElement } from "@microsoft/fast-element";
diff --git a/packages/web-components/fast-foundation/src/card/README.md b/packages/web-components/fast-foundation/src/card/README.md
index 9dcc0635b9c..e3b463c1cf6 100644
--- a/packages/web-components/fast-foundation/src/card/README.md
+++ b/packages/web-components/fast-foundation/src/card/README.md
@@ -20,7 +20,7 @@ The `fast-card` component is a visual container without semantics that takes chi
```
-## Applying Custom Styles
+## Applying custom styles
```ts
import { customElement } from "@microsoft/fast-element";
diff --git a/packages/web-components/fast-foundation/src/checkbox/README.md b/packages/web-components/fast-foundation/src/checkbox/README.md
index 0dad0eef82a..ccc71ca1cbd 100644
--- a/packages/web-components/fast-foundation/src/checkbox/README.md
+++ b/packages/web-components/fast-foundation/src/checkbox/README.md
@@ -21,7 +21,7 @@ An implementation of a [checkbox](https://developer.mozilla.org/en-US/docs/Web/H
```
-## Applying Custom Styles
+## Applying custom styles
```ts
import { customElement } from "@microsoft/fast-element";
diff --git a/packages/web-components/fast-foundation/src/design-system-provider/README.md b/packages/web-components/fast-foundation/src/design-system-provider/README.md
index 4488fb02769..294bcc4907a 100644
--- a/packages/web-components/fast-foundation/src/design-system-provider/README.md
+++ b/packages/web-components/fast-foundation/src/design-system-provider/README.md
@@ -5,13 +5,13 @@ sidebar_label: design-system-provider
custom_edit_url: https://github.com/microsoft/fast-dna/edit/master/packages/web-components/fast-foundation/src/design-system-provider/README.md
---
-## What is a Design System
+## What is a design system?
The _design system_ can generally be thought of as a collection of named values that inform visual rendering. It quantifies concepts such as type-ramp, color palettes, design units, etc to be used in UI components. Other common names for this concept are _design variables_, _design tokens_ or _theme_.
These values are mutable throughout a UI tree. Where UI tree _A_ may see their contextual _design-unit_ as `4px`, tree _B_ may have its scale increased by providing a _design-unit_ of `6px`. Or, tree _C_ may see a contextual _background color_ of `#FFF` where tree _D_ may see a contextual _background color_ as `#000`.
-## Design System Provider
+## Design system provider
A _design system_ isn't much use without convenient mechanisms to surface the _design system_ values to UI components and change values where desired. This is where the _Design System Provider_ comes in. `@microsoft/fast-components` exports the `FASTDesignSystemProvider` and `DesignSystemProvider` Web Components to help with:
@@ -21,7 +21,7 @@ A _design system_ isn't much use without convenient mechanisms to surface the _d
4. Facilitate _design system_ composition in _document order_.
5. Registering CSS Custom Property definitions to create arbitrary CSS Custom Properties as a function of the _design system_.
-### FAST Design System Provider
+### FAST design system provider
The easiest way to get up-and-running is to use the `FASTDesignSystemProvider`. This Web Component is an implementation of the `DesignSystemProvider` that is configured with _design system_ properties used by the Web Components in the `@microsoft/fast-components` library.
@@ -65,7 +65,8 @@ class ExampleClass {
The `use-defaults` boolean attribute exposes a mechanism to apply the default values to an element while still allowing nested design system elements to intentionally override specific values. For details on how to set default values, see [Declaring Design System Properties](#Declaring-Design-System-Properties)
-### Composing Design System Providers
+### Composing design system providers
+
*Design System Providers* are designed to compose their values with ancestor *Design System Providers* to facilitate changing values for decedents of the provider.
```html
@@ -118,7 +119,7 @@ const styles = css`
)
```
-### Creating a Design System Provider
+### Creating a design system provider
To create a new _Design System Provider_, extend the `DesignSystemProvider` class and decorate it with the `@designSystemProvider` decorator, providing the decorator the element _tag name_ you wish to use:
@@ -138,7 +139,7 @@ class FancyDesignSystemProvider extends DesignSystemProvider {}
```
-#### Declaring Design System Properties
+#### Declaring design system properties
Building off the above, _design system_ properties can be declared using the `@designSystemProperty` decorator.
diff --git a/packages/web-components/fast-foundation/src/dialog/README.md b/packages/web-components/fast-foundation/src/dialog/README.md
index f864ee6d678..bca6d99b702 100644
--- a/packages/web-components/fast-foundation/src/dialog/README.md
+++ b/packages/web-components/fast-foundation/src/dialog/README.md
@@ -22,7 +22,7 @@ A web component implementation of a [dialog](https://w3c.github.io/aria-practice
```
-## Applying Custom Styles
+## Applying custom styles
```ts
import { customElement } from "@microsoft/fast-element";
diff --git a/packages/web-components/fast-foundation/src/divider/README.md b/packages/web-components/fast-foundation/src/divider/README.md
index 1bdd17bb639..ff410d0a1a6 100644
--- a/packages/web-components/fast-foundation/src/divider/README.md
+++ b/packages/web-components/fast-foundation/src/divider/README.md
@@ -15,7 +15,7 @@ A web component implementation of a [horizontal rule](https://developer.mozilla.
```
-## Applying Custom Styles
+## Applying custom styles
```ts
import { customElement } from "@microsoft/fast-element";
diff --git a/packages/web-components/fast-foundation/src/flipper/README.md b/packages/web-components/fast-foundation/src/flipper/README.md
index ab3021301cc..915017d2d80 100644
--- a/packages/web-components/fast-foundation/src/flipper/README.md
+++ b/packages/web-components/fast-foundation/src/flipper/README.md
@@ -15,7 +15,7 @@ The flipper component is most often used to page through blocks of content or co
```
-## Applying Custom Styles
+## Applying custom styles
```ts
import { customElement } from "@microsoft/fast-element";
diff --git a/packages/web-components/fast-foundation/src/menu-item/README.md b/packages/web-components/fast-foundation/src/menu-item/README.md
index 3c687a35b27..02281e40961 100644
--- a/packages/web-components/fast-foundation/src/menu-item/README.md
+++ b/packages/web-components/fast-foundation/src/menu-item/README.md
@@ -15,7 +15,7 @@ The `fast-menu-item` is a custom element meant to be used with `fast-menu` and s
```
-## Applying Custom Styles
+## Applying custom styles
```ts
import { customElement } from "@microsoft/fast-element";
diff --git a/packages/web-components/fast-foundation/src/menu/README.md b/packages/web-components/fast-foundation/src/menu/README.md
index 32dcdf1167d..ff519085007 100644
--- a/packages/web-components/fast-foundation/src/menu/README.md
+++ b/packages/web-components/fast-foundation/src/menu/README.md
@@ -5,7 +5,7 @@ sidebar_label: menu
custom_edit_url: https://github.com/microsoft/fast-dna/edit/master/packages/web-components/fast-foundation/src/menu/README.md
---
-The menu is a widget that offers a list of choices to the user, such as a set of actions or functions. While any DOM content is permissible as a child of the menu, only `fast-menu-item`'s and slotted content with a role of `menuitem`, `menuitemcheckbox`, or `menuitemradio` will recieve keyboard support.
+The menu is a widget that offers a list of choices to the user, such as a set of actions or functions. While any DOM content is permissible as a child of the menu, only `fast-menu-item`'s and slotted content with a role of `menuitem`, `menuitemcheckbox`, or `menuitemradio` will receive keyboard support.
## Usage
@@ -22,7 +22,7 @@ The menu is a widget that offers a list of choices to the user, such as a set of
```
-## Applying Custom Styles
+## Applying custom styles
```ts
import { customElement } from "@microsoft/fast-element";
diff --git a/packages/web-components/fast-foundation/src/progress/README.md b/packages/web-components/fast-foundation/src/progress/README.md
index 9372db7ea40..e6ad019bf79 100644
--- a/packages/web-components/fast-foundation/src/progress/README.md
+++ b/packages/web-components/fast-foundation/src/progress/README.md
@@ -5,7 +5,7 @@ sidebar_label: progress
custom_edit_url: https://github.com/microsoft/fast-dna/edit/master/packages/web-components/fast-foundation/src/progress/README.md
---
-Progress components are used to indicate the length of time a process will take. This may either be as a determinate state in which the progress is a percentage of the total time needed to complete the task, or as an indeterminate state where the wait time is unspecified. For progress components which have a linear visual appearance, use `fast-progress`. For progress implementations which are circular, use `fast-progress-ring`.
+Progress components are used to indicate the length of time a process will take. This may either be as a determinate state in which the progress is a percentage of the total time needed to complete the task or as an indeterminate state where the wait time is unspecified. For progress components which have a linear visual appearance, use `fast-progress`. For progress implementations which are circular, use `fast-progress-ring`.
## Usage
@@ -25,7 +25,7 @@ Progress components are used to indicate the length of time a process will take.
```
-## Applying Custom Styles
+## Applying custom styles
### fast-progress
diff --git a/packages/web-components/fast-foundation/src/radio-group/README.md b/packages/web-components/fast-foundation/src/radio-group/README.md
index cd8cf29865d..7b59f206f0f 100644
--- a/packages/web-components/fast-foundation/src/radio-group/README.md
+++ b/packages/web-components/fast-foundation/src/radio-group/README.md
@@ -5,7 +5,7 @@ sidebar_label: radio-group
custom_edit_url: https://github.com/microsoft/fast-dna/edit/master/packages/web-components/fast-foundation/src/radio-group/README.md
---
-An implementation of a [radio-group](https://w3c.github.io/aria-practices/#radiobutton). While any DOM content is permissible as a child of the radiogroup, only `fast-radio`'s and slotted content with a role of `radio` will recieve keyboard support.
+An implementation of a [radio-group](https://w3c.github.io/aria-practices/#radiobutton). While any DOM content is permissible as a child of the radiogroup, only `fast-radio`'s and slotted content with a role of `radio` will receive keyboard support.
## Usage
@@ -21,7 +21,7 @@ An implementation of a [radio-group](https://w3c.github.io/aria-practices/#radio
```
-## Applying Custom Styles
+## Applying custom styles
```ts
import { customElement } from "@microsoft/fast-element";
diff --git a/packages/web-components/fast-foundation/src/radio/README.md b/packages/web-components/fast-foundation/src/radio/README.md
index 8cbeaeeca55..2715446c5fc 100644
--- a/packages/web-components/fast-foundation/src/radio/README.md
+++ b/packages/web-components/fast-foundation/src/radio/README.md
@@ -15,7 +15,7 @@ An implementation of a [radio](https://developer.mozilla.org/en-US/docs/Web/HTML
```
-## Applying Custom Styles
+## Applying custom styles
```ts
import { customElement } from "@microsoft/fast-element";
diff --git a/packages/web-components/fast-foundation/src/slider-label/README.md b/packages/web-components/fast-foundation/src/slider-label/README.md
index 5b63c9f9c1f..97d16600d06 100644
--- a/packages/web-components/fast-foundation/src/slider-label/README.md
+++ b/packages/web-components/fast-foundation/src/slider-label/README.md
@@ -15,7 +15,7 @@ The `fast-slider-label` component provides a default styled label to be placed i
```
-## Applying Custom Styles
+## Applying custom styles
```ts
import { customElement } from "@microsoft/fast-element";
diff --git a/packages/web-components/fast-foundation/src/slider/README.md b/packages/web-components/fast-foundation/src/slider/README.md
index 5b47bae4f2e..7400dde99d1 100644
--- a/packages/web-components/fast-foundation/src/slider/README.md
+++ b/packages/web-components/fast-foundation/src/slider/README.md
@@ -36,7 +36,7 @@ An implementation of a [range slider](https://developer.mozilla.org/en-US/docs/W
```
-## Applying Custom Styles
+## Applying custom styles
```ts
import { customElement } from "@microsoft/fast-element";
diff --git a/packages/web-components/fast-foundation/src/switch/README.md b/packages/web-components/fast-foundation/src/switch/README.md
index f2471fadd9e..3cbe829e4d2 100644
--- a/packages/web-components/fast-foundation/src/switch/README.md
+++ b/packages/web-components/fast-foundation/src/switch/README.md
@@ -19,7 +19,7 @@ An implementation of a [switch](https://w3c.github.io/aria/#switch) as a form-co
```
-## Applying Custom Styles
+## Applying custom styles
```ts
import { customElement } from "@microsoft/fast-element";
diff --git a/packages/web-components/fast-foundation/src/tabs/README.md b/packages/web-components/fast-foundation/src/tabs/README.md
index 8606014c0d2..416dc6989cb 100644
--- a/packages/web-components/fast-foundation/src/tabs/README.md
+++ b/packages/web-components/fast-foundation/src/tabs/README.md
@@ -42,7 +42,7 @@ custom_edit_url: https://github.com/microsoft/fast-dna/edit/master/packages/web-
```
-## Applying Custom Styles
+## Applying custom styles
### fast-tabs
```ts
diff --git a/packages/web-components/fast-foundation/src/text-area/README.md b/packages/web-components/fast-foundation/src/text-area/README.md
index 51f1f88f0ee..07e69b1ed9c 100644
--- a/packages/web-components/fast-foundation/src/text-area/README.md
+++ b/packages/web-components/fast-foundation/src/text-area/README.md
@@ -15,7 +15,7 @@ An implementation of an [HTML textarea element](https://developer.mozilla.org/en
```
-## Applying Custom Styles
+## Applying custom styles
```ts
import { customElement } from "@microsoft/fast-element";
diff --git a/packages/web-components/fast-foundation/src/text-field/README.md b/packages/web-components/fast-foundation/src/text-field/README.md
index 99288c59232..fd08ec3fe09 100644
--- a/packages/web-components/fast-foundation/src/text-field/README.md
+++ b/packages/web-components/fast-foundation/src/text-field/README.md
@@ -15,7 +15,7 @@ An implementation of a [text field](https://developer.mozilla.org/en-US/docs/Web
```
-## Applying Custom Styles
+## Applying custom styles
```ts
import { customElement } from "@microsoft/fast-element";
diff --git a/sites/website/src/docs/community/writing-documentation.md b/sites/website/src/docs/community/writing-documentation.md
index be170c41d46..fa0866911fa 100644
--- a/sites/website/src/docs/community/writing-documentation.md
+++ b/sites/website/src/docs/community/writing-documentation.md
@@ -9,7 +9,7 @@ Thank you for your interest in contributing to our documentation. We put togethe
## Documentation types
-There are two type of documentation: articles and API reference. Articles are documents written using [GitHub-flavored Markdown syntax](https://github.github.com/gfm/) and located throughout our packages, while API reference details classes, methods, etc. and is written inline within the code itself.
+There are two types of documentation: articles and API reference. Articles are documents written using [GitHub-flavored Markdown syntax](https://github.github.com/gfm/) and located throughout our packages, while API reference details classes, methods, etc. and is written inline within the code itself.
## Writing articles
@@ -31,7 +31,7 @@ The required fields are as follows:
* **sidebar_label**: The label that will be displayed in the left-side table of contents.
* **custom_edit_url**: A URL where the document source can be edited by contributors.
-Beneath the Yaml metadata block, the body of the article is written primarily with [GitHub-flavored Markdown syntax](https://github.github.com/gfm/). Since our documentation system will turn the `title` metadata into an appropriate article header, your content should begin immediately with a short introductory paragraph, followed by h2 headers for each section of the document. You may use use h3 headers beneath the h2s but try to avoid further sub-sections.
+Beneath the Yaml metadata block, the body of the article is written primarily with [GitHub-flavored Markdown syntax](https://github.github.com/gfm/). Since our documentation system will turn the `title` metadata into an appropriate article header, your content should begin immediately with a short introductory paragraph, followed by h2 headers for each section of the document. You may use h3 headers beneath the h2s but try to avoid further sub-sections.
In addition to [GitHub-flavored Markdown syntax](https://github.github.com/gfm/), you may also use the admonitions `note`, `tip`, `important`, `caution`, and `warning`. Here's an example of the syntax of a `note`:
@@ -77,7 +77,7 @@ export class Statistics {
## Building and testing the docs
-To test your documentation changes, first begin by cloning and building the documentation as described in [the contributor guide](./contributor-guide). Next, open a terminal and navigate to `sites/website`. From here, you can run the documentation site in developer mode with the following command: `yarn dev`. This will allow you to preview the site and validate that your documentation changes are rendering as expected.
+To test your documentation changes, first, begin by cloning and building the documentation as described in [the contributor guide](./contributor-guide). Next, open a terminal and navigate to `sites/website`. From here, you can run the documentation site in developer mode with the following command: `yarn dev`. This will allow you to preview the site and validate that your documentation changes are rendering as expected.
## Style guide
@@ -238,7 +238,7 @@ You can find a list of supported languages [here](https://github.com/github/ling
**Testing examples**: Test your code examples to verify they are working as expected.
-**Code guidelines**: Verify that code examples follow the projects coding guidelines. For example, four spaces for indenting.
+**Code guidelines**: Verify that code examples follow the project's coding guidelines. For example, four spaces for indenting.
#### Code comments
@@ -251,7 +251,7 @@ Code comments in **sentence** format:
Code comments in **fragment** format:
-* Are formatted as single line syntax.
+* Are formatted as single-line syntax.
* Do *not* have periods or question marks at the end.
[CMoS]: https://www.amazon.com/Chicago-Manual-Style-16th/dp/0226104206/ref=pd_lpo_sbs_14_t_0?_encoding=UTF8&psc=1&refRID=2QG7JEGM9PVNQJR5V00Y
diff --git a/sites/website/src/docs/components/getting-started.md b/sites/website/src/docs/components/getting-started.md
index c7a6aa928cd..8b242e7899d 100644
--- a/sites/website/src/docs/components/getting-started.md
+++ b/sites/website/src/docs/components/getting-started.md
@@ -6,13 +6,13 @@ custom_edit_url: https://github.com/microsoft/fast-dna/edit/master/sites/website
[](https://opensource.org/licenses/MIT)
[](https://badge.fury.io/js/%40microsoft%2Ffast-components)
-The `fast-components` and `fast-components-msft` libraries contain Web Components built on top of our standard component and design system foundation. `fast-components` express the FAST design language while `fast-components-msft` express the Microsoft design language, currently known as Fluent.
+The `fast-components` and `fast-components-msft` libraries contain Web Components built on top of our standard component and design system foundation. `fast-components` express the FAST design language while `fast-components-msft` expresses Microsoft's Fluent design language.
## Installation
### From NPM
-To install the components, first choose between `fast-components` and `fast-components-msft`. Assuming a selection of `fast-components`, you would use either `npm` or `yarn` as follows:
+To install the components, first, choose between `fast-components` and `fast-components-msft`. Assuming a selection of `fast-components`, you would use either `npm` or `yarn` as follows:
```shell
npm install --save @microsoft/fast-components
@@ -61,7 +61,7 @@ The above CDN location points to the latest release of `fast-components`. It is
For simplicity, examples throughout the documentation will assume the library has been installed from NPM, but you can always replace the import location with the CDN URL.
:::
-## Add the Design System Provider
+## Add the design system provider
The [Design System Provider](./design-system-provider) provides design information to child components. So, we must always wrap the portion of our site or app that uses the components with a provider element:
@@ -74,9 +74,9 @@ The [Design System Provider](./design-system-provider) provides design informati
```
-## Add Components
+## Add components
-With the provide in place, add any components as a child of the `fast-design-system-provider`. That's it! For a comprehensive list of all elements, see the Components section.
+With the provider in place, add any components as a child of the `fast-design-system-provider`. That's it! For a comprehensive list of all elements, see the Components section.
```html
diff --git a/sites/website/src/docs/introduction.md b/sites/website/src/docs/introduction.md
index 9cb4f4ac43a..d1eeed90c18 100644
--- a/sites/website/src/docs/introduction.md
+++ b/sites/website/src/docs/introduction.md
@@ -21,7 +21,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
@@ -44,24 +44,24 @@ This package does not export Web Components registered as [custom elements](http
[](https://opensource.org/licenses/MIT)
[](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](./fast-foundation/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](./fast-foundation/getting-started) to get started using the components.
### fast-components-msft
[](https://opensource.org/licenses/MIT)
[](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
Launch our [Component Explorer](https://explore.fast.design) to experience our [FAST Components](https://www.npmjs.com/package/@microsoft/fast-components) and development tools.
-## Getting Started
+## Getting started
If you're looking to get started using our components right away, take a look at [the components quick start](./fast-foundation/getting-started). You'll also want to check out [our integrations](./fast-foundation/webpack) if you're looking to add the components into a Webpack build or incorporate them with another front-end framework. For those interested in implementing their own design system or customizing the styles of the components, after you [have a look at the components](./fast-foundation/getting-started), you'll want to read through [our styling docs](./fast-components/intro). Finally, if your goal is to build your own components or apps with `fast-element`, you can learn all about that in our [guide to building web components with FASTElement](./fast-element/getting-started).
-## Joining the Community
+## Joining the community
Looking to get answers to questions or engage with us in realtime? Our community is most active [on Discord](https://discord.gg/FcSNfg4). You can also ask for help 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), or join us by contributing on [some good first issues via Github](https://github.com/Microsoft/fast-dna/labels/good%20first%20issue).
diff --git a/sites/website/src/docs/resources/faq.md b/sites/website/src/docs/resources/faq.md
index 8bf6f9c510d..7a9c96f2816 100644
--- a/sites/website/src/docs/resources/faq.md
+++ b/sites/website/src/docs/resources/faq.md
@@ -13,9 +13,13 @@ The Microsoft FAST team, part of the Edge organization, builds and maintains all
When the project was originally founded, it went by the name FAST-DNA, which stood for "Functional, Adaptive, Secure, and Timeless Design Network Architecture". Over time we began to refer to the project as "FAST" which reflects our desire to create libraries and tools that enable leading designer and developer productivity.
+### What's the difference between FAST and Fluent?
+
+Fluent is Microsoft's design language, independent of any particular implementation technology. FAST is an agnostic tech stack that enables implementing web components, design systems, and apps. `fast-element` is the lowest level of FAST, providing core features for building performant web components. `fast-foundation` is layered on top of `fast-element` and provides primarily two things: core features for building design systems, and a core set of components that are design-system-independent. With `fast-foundation` you can implement any design system. For example, you could implement Fluent Design, Material Design, Lightning Design, Bootstrap, etc. Once the design system is implemented, it can connect with any component built with `fast-element` or `fast-foundation` to enable a particular component to present itself using the visual language of the chosen design system. The FAST team ships two design systems: `fast-components`, which provide our team's own FAST Design system, and `fast-components-msft`, which provides Microsoft's Fluent Design system. If you want to build an app or site with Fluent Design, and you want to use web components as a technology solution, you can use `fast-components-msft` to meet that need today.
+
### What's the difference between FAST and Fluent UI?
-Fluent UI is a design language, independent of any particular implementation technology. FAST is a tech stack the enables implementing components, design systems, and apps. `fast-element` is the lowest level of FAST, providing core features for building performant web components. `fast-foundation` is layered on top of `fast-element` and provides primarily two things: core features for building design systems, and a core set of components that are design-system-independent. With `fast-foundation` you can implement any design system. For example, you could implement Fluent Design, Material Design, Lightning Design, Bootstrap, etc. Once the design system is implemented, it can connect with any component built with `fast-element` or `fast-foundation` to enable a particular component to present itself using the visual language of the chosen design system. The FAST team ships two design systems: `fast-components`, which provide our team's own design system, and `fast-components-msft`, which provides Microsoft's design system, currently known as Fluent. So, if you want to build an app or site with Fluent Design, and you want to use web components as a technology solution, you can use `fast-components-msft` to meet that need today.
+Fluent UI refers to an implementation of the Fluent Design language that focuses on Microsoft scenarios, implemented in React. FAST is an agnostic tech stack that enables implementing web components, design systems, and apps (see "What's the difference between FAST and Fluent?"). While FAST provides an implementation of Fluent for web components, via its `fast-components-msft` package, it can be used for other design systems and non-Microsoft related projects.
#### How does `fast-element` compare to "Framework X"?
diff --git a/sites/website/src/docs/resources/glossary.md b/sites/website/src/docs/resources/glossary.md
index 943c18c73fe..920f6841c15 100644
--- a/sites/website/src/docs/resources/glossary.md
+++ b/sites/website/src/docs/resources/glossary.md
@@ -27,7 +27,7 @@ The amount of time it takes a web page to become interactive. The smaller the TT
#### Transpiler
-Similar to a compiler, but rather than transforming a high-level language to machine instructions, it transforms one high-level language to another high-level language. E.g. TypeScript to JavaScript or ES2015 to ES5. On the web, this allows new JavaScript syntax to be used even if not supported by all target browsers, as the new syntax can sometimes be converted to a more verbose version of the old syntax. However, transpilers often produce output that is not only less performant than the native language feature, but often exhibiting spec-compliance issues in particularly nuanced ways.
+Similar to a compiler, but rather than transforming a high-level language to machine instructions, it transforms one high-level language to another high-level language. E.g. TypeScript to JavaScript or ES2015 to ES5. On the web, this allows new JavaScript syntax to be used even if not supported by all target browsers, as the new syntax can sometimes be converted to a more verbose version of the old syntax. However, transpilers often produce output that is not only less performant than the native language feature but often exhibiting spec-compliance issues in particularly nuanced ways.
#### Web Components