diff --git a/README.md b/README.md
index 50ff904ee83..9880a695356 100644
--- a/README.md
+++ b/README.md
@@ -17,6 +17,12 @@
This is the FAST monorepo, containing web component packages, tools, examples, and documentation. FAST tech can be used à la carte or as a suite to build enterprise-grade websites, applications, components, design systems, and more.
+:star: We appreciate your star, it helps!
+
+## Introduction
+
+FAST is a collection of technologies built on Web Components and modern Web Standards, designed to help you efficiently tackle some of the most common challenges in website and application design and development.
+
**TL;DR**
* Create reusable UI components based on web component standards.
@@ -25,32 +31,18 @@ This is the FAST monorepo, containing web component packages, tools, examples, a
* Build your own design system without re-implementing component logic.
* Integrate with any front-end framework or build system.
-:star: We appreciate your star, it helps!
-
-## Introduction
-
-FAST is a collection of JavaScript packages centered around web standards, designed to help you efficiently tackle some of the most common challenges in website and application design and development.
+For an in-depth explanation of FAST [see our docs introduction](https://www.fast.design/docs/introduction/).
-Have you ever needed a reusable set of UI components that you could drop into your app and have an amazing experience? _**That's FAST.**_
+## Packages
-Have you ever needed to create your own components, and share them across your company, including across groups that use different, incompatible front-end frameworks? _**That's FAST.**_
-
-Have you ever needed to implement a branded experience or a design language like Microsoft's Fluent UI or Google's Material Design? _**That's FAST.**_
-
-Have you ever wanted to improve your app's startup time, render speed, or memory consumption? _**That's FAST.**_
-
-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 gives us today.
-
-### fast-element
+### `@microsoft/fast-element`
[](https://opensource.org/licenses/MIT)
[](https://badge.fury.io/js/%40microsoft%2Ffast-element)
-The `@microsoft/fast-element` library is a lightweight means to easily building performant, memory-efficient, standards-compliant Web Components. FAST Elements work in every major browser and can be used in combination with any front-end framework or even without a framework. To get up and running with `@microsoft/fast-element` see [the Getting Started guide](http://fast.design/docs/fast-element/getting-started).
+The `@microsoft/fast-element` library is a lightweight means to easily build performant, memory-efficient, standards-compliant Web Components. FAST Elements work in every major browser and can be used in combination with any front-end framework or even without a framework. To get up and running with `@microsoft/fast-element` see [the Getting Started guide](http://fast.design/docs/fast-element/getting-started).
-### fast-foundation
+### `@microsoft/fast-foundation`
[](https://opensource.org/licenses/MIT)
[](https://badge.fury.io/js/%40microsoft%2Ffast-foundation)
@@ -59,27 +51,38 @@ The `@microsoft/fast-foundation` package is a library of Web Component classes,
This package does not export Web Components registered as [custom elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) - it exports parts and pieces intended to be *composed* into Web Components, allowing you to implement your own design language by simply applying CSS styles and behaviors without having to write all the JavaScript that's involved in building production-quality component implementations.
-### fast-components
+### `@microsoft/fast-components`
[](https://opensource.org/licenses/MIT)
[](https://badge.fury.io/js/%40microsoft%2Ffast-components)
-`@microsoft/fast-components` is a library of Web Components that *composes* the exports of `@microsoft/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.
+`@microsoft/fast-components` is a library of Web Components that *composes* the exports of `@microsoft/fast-foundation` with stylesheets aligning to the FAST Frame design system. This composition step registers a custom element. See the [quick start](http://fast.design/components/getting-started) to get started using the components.
+
+### `@fluentui/web-components`
-### fast-components-msft
-**This package has been moved to [FluentUI](https://github.com/microsoft/fluentui/) and has been renamed to `@fluentui/web-components`**
[](https://opensource.org/licenses/MIT)
-[](https://badge.fury.io/js/%40microsoft%2Ffast-components-msft)
+[](https://badge.fury.io/js/%40fluentui%2Fweb-components)
`@fluentui/web-components` is a library of Web Components that *composes* `@microsoft/fast-foundation`. `@fluentui/web-components` makes use of different stylesheets and may include components that specifically support Microsoft's Fluent design language.
+The source for `@fluentui/web-components` is hosted in [the Fluent UI monorepo](https://github.com/microsoft/fluentui/tree/master/packages/web-components).
+
### 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
-If you're looking to get started using our components right away, take a look at [the components quick start](http://fast.design/docs/components/getting-started). You'll also want to check out [our integrations](http://fast.design/docs/integrations/introduction) 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](http://fast.design/docs/components/getting-started), you'll want to read through [our styling docs](http://fast.design/docs/design/introduction). Finally, if your goal is to build your own components or apps with `@microsoft/fast-element`, you can learn all about that in our [guide to building web components with FASTElement](http://fast.design/docs/fast-element/getting-started).
+We hope you're excited by the possibilities that FAST presents. But, you may be wondering where to start. Here are a few statements that describe various members of our community. We recommend that you pick the statement you most identify with and follow the links where they lead. You can always come back and explore another topic at any time.
+
+* "I just want ready-made components!"
+ * [Jump to the component docs.](http://fast.design/docs/components/getting-started)
+* "I want to build my own design system."
+ * [Jump to the design system docs.](http://fast.design/docs/design/introduction)
+* "I want to build my own components."
+ * [Jump to the fast-element docs.](http://fast.design/docs/fast-element/getting-started)
+* "I need to integrate FAST with another framework or build system."
+ * [Jump to the integration docs.](http://fast.design/docs/integrations/introduction)
## Joining the Community
diff --git a/packages/web-components/fast-element/README.md b/packages/web-components/fast-element/README.md
index dd7d13a0c58..f6b07fd29f5 100644
--- a/packages/web-components/fast-element/README.md
+++ b/packages/web-components/fast-element/README.md
@@ -3,7 +3,7 @@
[](https://opensource.org/licenses/MIT)
[](https://badge.fury.io/js/%40microsoft%2Ffast-element)
-The `fast-element` library is a lightweight means to easily building performant, memory-efficient, standards-compliant Web Components. FAST Elements work in every major browser and can be used in combination with any front-end framework or even without a framework.
+The `fast-element` library is a lightweight means to easily build performant, memory-efficient, standards-compliant Web Components. FAST Elements work in every major browser and can be used in combination with any front-end framework or even without a framework.
## Installation
diff --git a/packages/web-components/fast-element/docs/guide/defining-elements.md b/packages/web-components/fast-element/docs/guide/defining-elements.md
index 8b7afd65594..bd65ce796f9 100644
--- a/packages/web-components/fast-element/docs/guide/defining-elements.md
+++ b/packages/web-components/fast-element/docs/guide/defining-elements.md
@@ -32,6 +32,10 @@ With this in place, you can now use your `name-tag` element anywhere in HTML wit
Web Component names must contain a `-` in order to prevent future conflicts with built-in elements and to namespace components from different libraries. For more information on the basics of Web Components [see this set of articles](https://developers.google.com/web/fundamentals/web-components).
:::
+:::note
+HTML has a few special tags known as "self-closing tags". Common examples include `` and ``. However, most HTML elements and **all** web components must have an explicit closing tag.
+:::
+
We've got a basic Web Component in place, but it doesn't do much. So, let's add an attribute and make it render something.
**Example: Adding Attributes to a `FASTElement`**
diff --git a/sites/website/src/docs/introduction.md b/sites/website/src/docs/introduction.md
index 1800d4317f3..7deb2514e15 100644
--- a/sites/website/src/docs/introduction.md
+++ b/sites/website/src/docs/introduction.md
@@ -5,64 +5,45 @@ sidebar_label: Introduction
custom_edit_url: https://github.com/microsoft/fast/edit/master/sites/website/src/docs/introduction.md
---
-Welcome to the FAST documentation! We're glad you're here. We can't wait to show you around.
+Welcome to the FAST documentation! We're glad you're here and can't wait to show you around.
## What is FAST?
-FAST is a collection of JavaScript packages centered around web standards, designed to help you efficiently tackle some of the most common challenges in website and application design and development.
+FAST is a collection of technologies built on Web Components and modern Web Standards, designed to help you efficiently tackle some of the most common challenges in website and application design and development.
-Have you ever needed a reusable set of UI components that you could drop into your app and have an amazing experience? _**That's FAST.**_
+### What are Web Components?
-Have you ever needed to create your own components, and share them across your company, including across groups that use different, incompatible front-end frameworks? _**That's FAST.**_
+"Web Components" is an umbrella term that refers to a collection of web standards focused on enabling the creation of custom HTML elements. Some of the standards that are under the umbrella include the ability to define new HTML tags, plug into a standard component lifecycle, encapsulate HTML rendering and CSS, parameterize CSS, skin components, and more. Each of these platform features is defined by the W3C and has shipped in every major browser today.
-Have you ever needed to implement a branded experience or a design language like Microsoft's Fluent UI or Google's Material Design? _**That's FAST.**_
+### How does FAST leverage Web Components?
-Have you ever wanted to improve your app's startup time, render speed, or memory consumption? _**That's FAST.**_
+One of FAST's driving principals is "strive to adopt open, web standards-based approaches as much as possible." To that end, FAST is built directly on the W3C Web Component standards mentioned above, and does not create its own component model. This allows components built with FAST to function the same as built-in, native HTML elements. You do not need a framework to use FAST components but you can use them in combination with any framework or library of your choice.
-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.**_
+### How can FAST help me?
-Let's take a look at what each of FAST's core packages gives us today.
+To understand how FAST can help you, let's take a look at the FAST tech stack from top to bottom.
-### fast-element
+At the top of the stack FAST provides two sets of Web Components: `@fluentui/web-components` and `@microsoft/fast-components`. Both of these libraries include a common set of components found in many websites and apps. Example components include button, menu, tree-view, tab, card, modal, and more. So, what is the difference between these two libraries? The answer is that each library implements a different *design system*. `@fluentui/web-components` implements Microsoft's Fluent Design System. They look and feel like the components found in products like Windows, Office, Teams, and Edge. If you like the Fluent Design System or are building experiences designed to fit naturally into the Microsoft ecosystem, this is the component set you'll want to use. Alternatively, `@microsoft/fast-components` provides an industry-focused design system with more customization options. We call this system "FAST Frame". If you're looking to integrate FAST components into an existing site or app, or if you need more control over the theme of the components, this is the option you'll want to start with.
-[](https://opensource.org/licenses/MIT)
-[](https://badge.fury.io/js/%40microsoft%2Ffast-element)
+What if you're not just looking for a set of components to use, but you also need to implement a custom *design system*? This is where the second level of the stack comes into play. `@microsoft/fast-foundation` provides foundational building blocks that can be assembled to create new design systems and component libraries. For example, if you wanted to implement Google's Material Design, you could do that using `@microsoft/fast-foundation`. You could also implement something like Twitter Bootstrap. Both `@fluentui/web-components` and `@microsoft/fast-components` assemble the building blocks of `@microsoft/fast-foundation` to create their component sets. What types of building blocks are we talking about though? Perhaps the most valuable feature of the foundation is that it provides base component behaviors and templates for the standard components. So, if you want to implement a tree-view in your design system, for example, you would use the foundation base component behavior and template, but combine it with your own styles. The foundation components implement the state management, accessibility, keyboard navigation, and extensibility/composition model so you don't have to write that code. Additionally, foundation provides facilities for dynamic style behaviors, CSS property management, algorithmic color, RTL, high contract, and more. You don't have to write any of that. Just assemble the building blocks and add your styles to create your own component library, expressing your own design system.
-The `@microsoft/fast-element` library is a lightweight means to easily building performant, memory-efficient, standards-compliant Web Components. FAST Elements work in every major browser and can be used in combination with any front-end framework or even without a framework. To get up and running with `@microsoft/fast-element` see [the Getting Started guide](/docs/fast-element/getting-started).
+So far we've talked about using existing components and creating new design systems and component libraries from existing pieces. But FAST enables you to create completely new web components as well. Enter `@microsoft/fast-element`, the lowest level part of the FAST tech stack. `@microsoft/fast-element` provides a thin layer of opinions on top of Web Components, lifting the level of abstraction just enough to make it easier and FASTer to build components. `@microsoft/fast-element` helps by providing attribute/property syncing, rich Model-View-ViewModel (MVVM), efficient template rendering/update, style composition, and much more. The entire `@microsoft/fast-element` library, *without* tree-shaking, is around 10kb minified and GZipped. It was designed for tree-shaking from the beginning, so any feature you don't use when building a component will be removed during build, allowing for highly efficient optimized payloads.
-### fast-foundation
+## Where should I start?
-[](https://opensource.org/licenses/MIT)
-[](https://badge.fury.io/js/%40microsoft%2Ffast-foundation)
+We hope you're excited by the possibilities that FAST presents. But, you may be wondering where to start. Here are a few statements that describe various members of our community. We recommend that you pick the statement you most identify with and follow the links where they lead. You can always come back and explore another topic at any time.
-The `@microsoft/fast-foundation` package is a library of Web Component classes, templates, and other utilities intended to be composed into registered Web Components by design systems (e.g. Fluent Design, Material Design, etc.). The exports of this package can generally be thought of as un-styled base components that implement semantic and accessible markup and behavior.
-
-This package does not export Web Components registered as [custom elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) - it exports parts and pieces intended to be *composed* into Web Components, allowing you to implement your own design language by simply applying CSS styles and behaviors without having to write all the JavaScript that's involved in building production-quality component implementations.
-
-### fast-components
-
-[](https://opensource.org/licenses/MIT)
-[](https://badge.fury.io/js/%40microsoft%2Ffast-components)
-
-`@microsoft/fast-components` is a library of Web Components that *composes* the exports of `@microsoft/fast-foundation` with stylesheets aligning to the FAST design language. This composition step registers a custom element. See the [quick start](/docs/components/getting-started) to get started using the components.
-
-### fast-components-msft
-**This package has been moved to [FluentUI](https://github.com/microsoft/fluentui/) and has been renamed to `@fluentui/web-components`**
-[](https://opensource.org/licenses/MIT)
-[](https://badge.fury.io/js/%40microsoft%2Ffast-components-msft)
-
-`@fluentui/web-components` is a library of Web Components that *composes* `@microsoft/fast-foundation`. `@fluentui/web-components` makes use of different stylesheets and may include components that specifically 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
-
-If you're looking to get started using our components right away, take a look at [the components quick start](/docs/components/getting-started). You'll also want to check out [our integrations](/docs/integrations/introduction) 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](/docs/components/getting-started), you'll want to read through [our styling docs](/docs/design/introduction). Finally, if your goal is to build your own components or apps with `@microsoft/fast-element`, you can learn all about that in our [guide to building web components with FASTElement](/docs/fast-element/getting-started).
+* "I just want ready-made components!"
+ * [Jump to the component docs.](/docs/components/getting-started)
+* "I want to build my own design system."
+ * [Jump to the design system docs.](/docs/design/introduction)
+* "I want to build my own components."
+ * [Jump to the fast-element docs.](/docs/fast-element/getting-started)
+* "I need to integrate FAST with another framework or build system."
+ * [Jump to the integration docs.](/docs/integrations/introduction)
## 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). Submit requests and issues on [GitHub](https://github.com/Microsoft/fast/issues/new/choose), or join us by contributing on [some good first issues via GitHub](https://github.com/Microsoft/fast/labels/community:good-first-issue).
-We look forward to building an amazing open source community with you!
\ No newline at end of file
+We look forward to building an amazing open source community with you!
diff --git a/sites/website/src/docs/resources/faq.md b/sites/website/src/docs/resources/faq.md
index 5391010c5c9..dda75eb7264 100644
--- a/sites/website/src/docs/resources/faq.md
+++ b/sites/website/src/docs/resources/faq.md
@@ -7,7 +7,7 @@ custom_edit_url: https://github.com/microsoft/fast/edit/master/sites/website/src
### Who is behind FAST?
-The Microsoft FAST team builds and maintains all the `@microsoft/fast-*` packages. We are a collection of UX Engineers and Designers who are passionate about solving real-world UX challenges using web standard technologies. You can find us on GitHub [here](https://github.com/microsoft/fast).
+The Microsoft FAST team builds and maintains all the `@microsoft/fast-*` packages as well as the `@fluentui/web-components` package. We are a collection of UX Engineers and Designers who are passionate about solving real-world UX challenges using web standard technologies. You can find us on [GitHub](https://github.com/microsoft/fast).
### What does FAST stand for?
@@ -17,10 +17,14 @@ When the project was originally founded, it went by the name FAST-DNA, which sto
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 `@fluentui/web-components`, located in the [Fluent UI repo](https://github.com/microsoft/fluentui/), 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 `@fluentui/web-components` to meet that need today.
-### What's the difference between FAST and Fluent UI?
+### How does `fast-element` compare to "Framework X"?
-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 `@fluentui/web-components` package, it can be used for other design systems and non-Microsoft related projects.
+At this time, `fast-element` has a focus that's a bit different from the typical front-end framework. Rather than focusing on being a "mega SPA framework", `fast-element` endeavors to enable the creation of web components. As a result, you can use `fast-element` or any component built on `fast-element` in tandem with your favorite front-end framework.
-### How does `fast-element` compare to "Framework X"?
+### What are Web Components?
+
+"Web Components" is an umbrella term that refers to a collection of web standards focused on enabling the creation of custom HTML elements. Some of the standards that are under the umbrella include the ability to define new HTML tags, plug into a standard component lifecycle, encapsulate HTML rendering and CSS, parameterize CSS, skin components, and more. Each of these platform features is defined by the W3C and has shipped in every major browsers today.
+
+### Are Web Components "done"?
-At this time, `fast-element` has a focus that's a bit different from the typical front-end framework. Rather than focusing on being a "mega SPA framework", `fast-element` endeavors to enable the creation of web components. As a result, you can use `fast-element` or any component built on `fast-element` in tandem with your favorite front-end framework.
\ No newline at end of file
+The work on Web Component standards, like the rest of the web, is ongoing. New APIs continue to be designed and released. Some recent APIs include Form Associated Custom Element APIs and CSS Shadow Parts. The W3C is currently working on standards for things like Constructible Style Sheets, Declarative Shadow DOM, Scoped Element Registries, Custom Pseudo Selectors, and more.
\ No newline at end of file