From 835d60dfe614b55b8602fa0932943e813b133921 Mon Sep 17 00:00:00 2001 From: Rob Eisenberg Date: Mon, 22 Jun 2020 17:13:54 -0400 Subject: [PATCH 01/10] docs: grammar fixes in fast-components and fast-element --- .../fast-components/docs/design/color.md | 2 +- .../fast-element/docs/ACKNOWLEDGEMENTS.md | 4 ++-- .../docs/guide/declaring-templates.md | 8 +++---- .../docs/guide/defining-elements.md | 4 ++-- .../fast-element/docs/guide/leveraging-css.md | 6 ++--- .../fast-element/docs/guide/next-steps.md | 2 +- .../docs/guide/using-directives.md | 22 +++++++++---------- .../docs/guide/working-with-shadow-dom.md | 8 +++---- 8 files changed, 28 insertions(+), 28 deletions(-) diff --git a/packages/web-components/fast-components/docs/design/color.md b/packages/web-components/fast-components/docs/design/color.md index 0c157c409e3..8a22966cff5 100644 --- a/packages/web-components/fast-components/docs/design/color.md +++ b/packages/web-components/fast-components/docs/design/color.md @@ -57,7 +57,7 @@ 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. diff --git a/packages/web-components/fast-element/docs/ACKNOWLEDGEMENTS.md b/packages/web-components/fast-element/docs/ACKNOWLEDGEMENTS.md index 0fbdeeb2571..3d0d71a32db 100644 --- a/packages/web-components/fast-element/docs/ACKNOWLEDGEMENTS.md +++ b/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. \ No newline at end of file +* [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. \ No newline at end of file diff --git a/packages/web-components/fast-element/docs/guide/declaring-templates.md b/packages/web-components/fast-element/docs/guide/declaring-templates.md index a642d076807..cfe4ec14625 100644 --- a/packages/web-components/fast-element/docs/guide/declaring-templates.md +++ b/packages/web-components/fast-element/docs/guide/declaring-templates.md @@ -52,7 +52,7 @@ We've seen how arrow functions can be used to declare dynamic parts of templates ### Content -To bind the content of an element, simply provide the expression within the start and end tags of the element. It can be the sole content of the element, or interwoven with other elements and text. +To bind the content of an element, simply provide the expression within the start and end tags of the element. It can be the sole content of the element or interwoven with other elements and text. **Example: Basic Text Content** @@ -81,7 +81,7 @@ Dynamic content is set via the `textContent` HTML property for security reasons. ### Attributes -You can also use an expression to set an attribute value on an HTML Element. Simply place the expression where the value of the HTML attribute would go. The template engine will then use your expression to set the value using `setAttribute(...)`, whenever it needs to be updated. Additionally, some attributes are known as [boolean attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes#Boolean_Attributes) (e.g. required, readonly, disabled). These attributes behave differently from normal attributes, and need special value handling. The templating engine will handle this for you if you prepend the attribute name with a `?`. +You can also use an expression to set an attribute value on an HTML Element. Simply place the expression where the value of the HTML attribute would go. The template engine will then use your expression to set the value using `setAttribute(...)`, whenever it needs to be updated. Additionally, some attributes are known as [boolean attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes#Boolean_Attributes) (e.g. required, readonly, disabled). These attributes behave differently from normal attributes and need special value handling. The templating engine will handle this for you if you prepend the attribute name with a `?`. **Example: Basic Attribute Values** @@ -104,7 +104,7 @@ You can also use an expression to set an attribute value on an HTML Element. Sim ``` :::tip -When binding to `class`, the underlying engine will not over-write classes added to the element via other mechanisms. It only adds and removes classes that result directly from the binding. This "safe by default" behavior does come at a slight performance cost. To opt out of this feature and squeeze out every ounce of performance by always overwriting all classes, use a property binding (see below) on the `className` property. e.g. `:className="list-item ${x => x.type}"`. +When binding to `class`, the underlying engine will not over-write classes added to the element via other mechanisms. It only adds and removes classes that result directly from the binding. This "safe by default" behavior does come at a slight performance cost. To opt-out of this feature and squeeze out every ounce of performance by always overwriting all classes, use a property binding (see below) on the `className` property. e.g. `:className="list-item ${x => x.type}"`. ::: ```html @@ -187,7 +187,7 @@ Besides rendering content, attributes, and properties, you'll often want to add ``` :::important -In both examples above, after your event handler is executed, `preventDefault()` will be called on the event object by default. You can return `true` from your handler to opt out of this behavior. +In both examples above, after your event handler is executed, `preventDefault()` will be called on the event object by default. You can return `true` from your handler to opt-out of this behavior. ::: The second example demonstrates an important characteristic of the templating engine: it only supports *unidirectional data flow* (model => view). It does not support *two-way data binding* (model <=> view). As shown above, pushing data from the view back to the model should be handled with explicit events that call into your model's API. \ No newline at end of file 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 f5b889083be..0b38503a2e1 100644 --- a/packages/web-components/fast-element/docs/guide/defining-elements.md +++ b/packages/web-components/fast-element/docs/guide/defining-elements.md @@ -88,7 +88,7 @@ Here's how it works: * When the property value changes, the converter's `fromView` method will also be called, ensuring that the type is correct. After this, the `mode` will be determined. If the mode is set to `reflect` then the converter's `toView` method will be called to allow the type to be formatted before writing to the attribute using `setAttribute`. :::important -When the `mode` is set to `boolean`, a built-in `booleanConverter` is automatically used to ensure type correctness so that manual configuration of the converter is not needed in this common scenario. +When the `mode` is set to `boolean`, a built-in `booleanConverter` is automatically used to ensure type correctness so that the manual configuration of the converter is not needed in this common scenario. ::: **Example: An Attribute in Reflect Mode with No Special Conversion** @@ -158,7 +158,7 @@ export class NameTag extends FASTElement { } ``` -The full list of available lifecyle callbacks is: +The full list of available lifecycle callbacks is: | Callback | Description | | ------------- |-------------| diff --git a/packages/web-components/fast-element/docs/guide/leveraging-css.md b/packages/web-components/fast-element/docs/guide/leveraging-css.md index 5c402481ec1..d03ddbc53b5 100644 --- a/packages/web-components/fast-element/docs/guide/leveraging-css.md +++ b/packages/web-components/fast-element/docs/guide/leveraging-css.md @@ -55,14 +55,14 @@ const styles = css` letter-spacing: 4px; font-size: 32px; margin: 0; - padding: 0; + padding: 0; } h4 { font-family: sans-serif; font-size: 18px; margin: 0; - padding: 0; + padding: 0; } .body { @@ -161,7 +161,7 @@ const styles = css` ``` :::note -Both slotted and host styles can be overriden by the element user. Think of these as the *default* styles that you are providing, so that your elements look and function correctly out-of-the-box. +Both slotted and host styles can be overridden by the element user. Think of these as the *default* styles that you are providing, so that your elements look and function correctly out-of-the-box. ::: ## Hiding Undefined Elements diff --git a/packages/web-components/fast-element/docs/guide/next-steps.md b/packages/web-components/fast-element/docs/guide/next-steps.md index abfacc2aae8..a8178111d45 100644 --- a/packages/web-components/fast-element/docs/guide/next-steps.md +++ b/packages/web-components/fast-element/docs/guide/next-steps.md @@ -7,6 +7,6 @@ custom_edit_url: https://github.com/microsoft/fast-dna/edit/master/packages/web- We've seen how to use `FASTElement` to declaratively build Web Components. In addition to the basics of element and attribute definition, `FASTElement` also provides a way to declare templates capable of high-performance rendering, and efficient, incremental batched updates. Finally, CSS can easily be associated with an element in a way that leverages core platform optimizations for performance and low memory allocation. -Now that you're familiar with the robust and powerful features of `FASTElement`, you're ready to build your own components and apps. But you don't have to start from scratch there either! If you haven't already explored them, check out our [FAST Components](../components/getting-started), which provide all the basic UI building-blocks you'd expect in a modern component library. You can also leverage the same adaptive design system that our own components use to enable robust theming throughout all you create. Read more on that in [Styling Components](../design/introduction). Finally, you'll want to take advantages of a modern toolset by installing [a powerful editor and plugins](../tools/vscode). +Now that you're familiar with the robust and powerful features of `FASTElement`, you're ready to build your own components and apps. But you don't have to start from scratch there either! If you haven't already explored them, check out our [FAST Components](../components/getting-started), which provide all the basic UI building-blocks you'd expect in a modern component library. You can also leverage the same adaptive design system that our own components use to enable robust theming throughout all you create. Read more on that in [Styling Components](../design/introduction). Finally, you'll want to take advantage of a modern toolset by installing [a powerful editor and plugins](../tools/vscode). Happy componenting! \ No newline at end of file diff --git a/packages/web-components/fast-element/docs/guide/using-directives.md b/packages/web-components/fast-element/docs/guide/using-directives.md index 3a7312cc6f5..40a09ff344b 100644 --- a/packages/web-components/fast-element/docs/guide/using-directives.md +++ b/packages/web-components/fast-element/docs/guide/using-directives.md @@ -119,13 +119,13 @@ Similar to event handlers, within a `repeat` block you have access to a special * `event` - The event object when inside an event handler. * `parent` - The parent scope when inside a `repeat` block. -* `index` - The index of the current item when inside a `repeat` block (opt in). -* `length` - The length of the array when inside a `repeat` block (opt in). -* `isEven` - True if the index of the current item is even when inside a `repeat` block (opt in). -* `isOdd` - True if the index of the current item is odd when inside a `repeat` block (opt in). -* `isFirst` - True if the current item is first in the array inside a `repeat` block (opt in). -* `isInMiddle` - True if the current item is somewhere in the middle of the the array inside a `repeat` block (opt in). -* `isLast` - True if the current item is last in the array inside a `repeat` block (opt in). +* `index` - The index of the current item when inside a `repeat` block (opt-in). +* `length` - The length of the array when inside a `repeat` block (opt-in). +* `isEven` - True if the index of the current item is even when inside a `repeat` block (opt-in). +* `isOdd` - True if the index of the current item is odd when inside a `repeat` block (opt-in). +* `isFirst` - True if the current item is first in the array inside a `repeat` block (opt-in). +* `isInMiddle` - True if the current item is somewhere in the middle of the array inside a `repeat` block (opt-in). +* `isLast` - True if the current item is last in the array inside a `repeat` block (opt-in). Some context properties are opt-in because they are more costly to update. So, for performance reasons, they are not available by default. To opt into the positioning properties, pass options to the repeat directive, with the setting `positioning: true`. For example, here's how we would use the `index` in our friends template from above: @@ -212,7 +212,7 @@ export class FriendList extends FASTElement { In the above example, we create an independent `nameTemplate` and then use it in two different places. First inside of a `when` template and then later inside of a `repeat` template. -But content composition is actually more powerful than that, because you aren't limited to *static composition* of templates. You can also provide any expression that returns a template. As a result, when the `@observable` dependencies of the expression change, you can dynamically change which template is selected for rendering. If you don't want to render anything, you can also handle that by returning `null` or `undefined`. Here are a few examples of what you can do with content composition: +But content composition is actually more powerful than that because you aren't limited to *static composition* of templates. You can also provide any expression that returns a template. As a result, when the `@observable` dependencies of the expression change, you can dynamically change which template is selected for rendering. If you don't want to render anything, you can also handle that by returning `null` or `undefined`. Here are a few examples of what you can do with content composition: **Example: Dynamic Composition** @@ -402,7 +402,7 @@ Referential directives allow you to easily get references to DOM nodes in variou ### The Ref Directive -Sometimes you need a direct reference to a single DOM node from your template. This might be because you want to control playback of a `video` element, use the drawing context of a `canvas` element, or pass an element to a 3rd party library. Whatever the reason, you can get a reference to the DOM node by using the `ref` directive. +Sometimes you need a direct reference to a single DOM node from your template. This might be because you want to control the playback of a `video` element, use the drawing context of a `canvas` element, or pass an element to a 3rd party library. Whatever the reason, you can get a reference to the DOM node by using the `ref` directive. **Example: Referencing an Element** @@ -468,7 +468,7 @@ export class FriendList extends FASTElement { } ``` -In the example above, the `listItems` property will be populated with all child nodes of the `ul` element. If `listItems` is decorated with `@observable` then it will be updated dynamically as the child nodes change. Like any observable, you can optionally implement a *propertyName*Changed method to be notified when the nodes change. Additionally, you can provide an `options` object to the `children` directive to specify customized configuration for the underlying [MutationObserver](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver). +In the example above, the `listItems` property will be populated with all child nodes of the `ul` element. If `listItems` is decorated with `@observable` then it will be updated dynamically as the child nodes change. Like any observable, you can optionally implement a *propertyName*Changed method to be notified when the nodes change. Additionally, you can provide an `options` object to the `children` directive to specify a customized configuration for the underlying [MutationObserver](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver). :::important Like `ref`, the child nodes are not available until the `connectedCallback` lifecycle event. @@ -517,7 +517,7 @@ export class MyElement extends FASTElement { } ``` -Similar to the `children` directive, the `slotted` directive will populate the `slottedNodes` property with nodes assigned to the slot. If `slottedNodes` is decorated with `@observable` then it will be updated dynamically as the assigned nodes change. Like any observable, you can optionally implement a *propertyName*Changed method to be notified when the nodes change. Additionally, you can provide an `options` object to the `slotted` directive to specify customized configuration for the underlying [assignedNodes() API call](https://developer.mozilla.org/en-US/docs/Web/API/HTMLSlotElement/assignedNodes) or specify a `filter`. +Similar to the `children` directive, the `slotted` directive will populate the `slottedNodes` property with nodes assigned to the slot. If `slottedNodes` is decorated with `@observable` then it will be updated dynamically as the assigned nodes change. Like any observable, you can optionally implement a *propertyName*Changed method to be notified when the nodes change. Additionally, you can provide an `options` object to the `slotted` directive to specify a customized configuration for the underlying [assignedNodes() API call](https://developer.mozilla.org/en-US/docs/Web/API/HTMLSlotElement/assignedNodes) or specify a `filter`. ## Host Directives diff --git a/packages/web-components/fast-element/docs/guide/working-with-shadow-dom.md b/packages/web-components/fast-element/docs/guide/working-with-shadow-dom.md index 385dfae2f86..372a399f69f 100644 --- a/packages/web-components/fast-element/docs/guide/working-with-shadow-dom.md +++ b/packages/web-components/fast-element/docs/guide/working-with-shadow-dom.md @@ -74,7 +74,7 @@ To make this clear, let's look at how the `name-tag` element would be used with The text "John Doe" exists in the "Light DOM", but it gets *projected* into the location of the `slot` within the "Shadow DOM". :::note -If you find the terms "Light DOM" and "Shadow DOM" unintuitive, you're not alone. Another way to think of "Light DOM" is as the "Semantic DOM". It represents your semantic content model, without any concern for rendering. Another way to think of "Shadow DOM" is as the "Render DOM". It represents how your element is rendered, independent of content or semantics. +If you find the terms "Light DOM" and "Shadow DOM" unintuitive, you're not alone. Another way to think of "Light DOM" is as the "Semantic DOM". It represents your semantic content model, without any concern for rendering. Another way to think of "Shadow DOM" is as the "Render DOM". It represents how your element is rendered, independent of content, or semantics. ::: With slots at our disposal, we now unlock the full compositional model of HTML for use in our own elements. However, there's even more that slots can do. @@ -150,7 +150,7 @@ If an element declares named slots, its content can then leverage the `slot` *at Here are a couple of quick notes on slots: * You can have any number of content nodes project into the same slot. -* You can only place `slot` attributes on direct content of the containing element. +* You can only place `slot` attributes on the direct content of the containing element. ```html
@@ -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 @@ -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 From 1f15868829987ac0e7ff8a2d681c221e7780e159 Mon Sep 17 00:00:00 2001 From: Rob Eisenberg Date: Mon, 22 Jun 2020 17:19:05 -0400 Subject: [PATCH 02/10] docs: grammar fixes to fast-foundation docs --- .../fast-foundation/docs/integrations/aspnet.md | 4 ++-- .../fast-foundation/docs/integrations/aurelia.md | 8 ++++---- .../fast-foundation/docs/integrations/blazor.md | 4 ++-- .../fast-foundation/docs/integrations/webpack.md | 4 ++-- 4 files changed, 10 insertions(+), 10 deletions(-) diff --git a/packages/web-components/fast-foundation/docs/integrations/aspnet.md b/packages/web-components/fast-foundation/docs/integrations/aspnet.md index 6d6d15e9f79..5f6af1a3909 100644 --- a/packages/web-components/fast-foundation/docs/integrations/aspnet.md +++ b/packages/web-components/fast-foundation/docs/integrations/aspnet.md @@ -11,7 +11,7 @@ FAST works naturally with ASP.NET server-side development, by simply adding a sc 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 @@ -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..24b3ed982ea 100644 --- a/packages/web-components/fast-foundation/docs/integrations/aurelia.md +++ b/packages/web-components/fast-foundation/docs/integrations/aurelia.md @@ -19,7 +19,7 @@ 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. @@ -99,7 +99,7 @@ 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 @@ -119,7 +119,7 @@ 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. @@ -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..b06cb07fcf7 100644 --- a/packages/web-components/fast-foundation/docs/integrations/blazor.md +++ b/packages/web-components/fast-foundation/docs/integrations/blazor.md @@ -11,7 +11,7 @@ FAST works seamlessly with Blazor, including integration with Blazor's binding e 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 @@ -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..34778b01e23 100644 --- a/packages/web-components/fast-foundation/docs/integrations/webpack.md +++ b/packages/web-components/fast-foundation/docs/integrations/webpack.md @@ -43,7 +43,7 @@ npm install --save-dev clean-webpack-plugin ts-loader typescript webpack webpack ## 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. @@ -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 From 32f1447a5412e4b09a44f35051d1f3edd0d078e1 Mon Sep 17 00:00:00 2001 From: Rob Eisenberg Date: Mon, 22 Jun 2020 17:32:51 -0400 Subject: [PATCH 03/10] docs: grammar fixes in readmes --- README.md | 12 ++++++------ packages/README.md | 4 ++-- packages/web-components/README.md | 2 +- .../web-components/fast-components-msft/README.md | 2 +- .../fast-foundation/src/button/README.md | 2 +- .../fast-foundation/src/menu/README.md | 2 +- .../fast-foundation/src/progress/README.md | 2 +- .../fast-foundation/src/radio-group/README.md | 2 +- 8 files changed, 14 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 3d6af2ad75f..50199f3ef49 100644 --- a/README.md +++ b/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,7 +56,7 @@ 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 @@ -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 diff --git a/packages/README.md b/packages/README.md index c22b72cd188..524997bc7ae 100644 --- a/packages/README.md +++ b/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. \ No newline at end of file +* `react` - Legacy React components that predate the modern web component work. \ No newline at end of file diff --git a/packages/web-components/README.md b/packages/web-components/README.md index 60148d40782..6df8cbf8c6f 100644 --- a/packages/web-components/README.md +++ b/packages/web-components/README.md @@ -23,7 +23,7 @@ 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 diff --git a/packages/web-components/fast-components-msft/README.md b/packages/web-components/fast-components-msft/README.md index fa34a959846..59d93c91324 100644 --- a/packages/web-components/fast-components-msft/README.md +++ b/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 align to the Microsoft design language. ## Installation diff --git a/packages/web-components/fast-foundation/src/button/README.md b/packages/web-components/fast-foundation/src/button/README.md index fdd115befee..9bbfa85b873 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 diff --git a/packages/web-components/fast-foundation/src/menu/README.md b/packages/web-components/fast-foundation/src/menu/README.md index 32dcdf1167d..8233c0a9072 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 diff --git a/packages/web-components/fast-foundation/src/progress/README.md b/packages/web-components/fast-foundation/src/progress/README.md index 9372db7ea40..e61c8a3ab60 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 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..2c37a2d8751 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 From f8019daa0419eafc2d58797e0bf9be628020414c Mon Sep 17 00:00:00 2001 From: Rob Eisenberg Date: Mon, 22 Jun 2020 19:39:07 -0400 Subject: [PATCH 04/10] docs: grammar fixes to other docs --- .../src/docs/community/writing-documentation.md | 10 +++++----- sites/website/src/docs/components/getting-started.md | 4 ++-- sites/website/src/docs/introduction.md | 4 ++-- sites/website/src/docs/resources/glossary.md | 2 +- 4 files changed, 10 insertions(+), 10 deletions(-) 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..ec7210cefb8 100644 --- a/sites/website/src/docs/components/getting-started.md +++ b/sites/website/src/docs/components/getting-started.md @@ -12,7 +12,7 @@ The `fast-components` and `fast-components-msft` libraries contain Web Component ### 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 @@ -76,7 +76,7 @@ The [Design System Provider](./design-system-provider) provides design informati ## 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..afbbc503c1b 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,7 +44,7 @@ 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](./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 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 From 1441ba7eb94b6315952e57e4097bfdac5c6c829f Mon Sep 17 00:00:00 2001 From: Rob Eisenberg Date: Mon, 22 Jun 2020 20:59:27 -0400 Subject: [PATCH 05/10] docs: apply guidance from style guide --- .../fast-components/docs/design/color.md | 42 +++++++++++++------ .../docs/design/design-system.md | 3 +- .../docs/design/introduction.md | 3 +- .../docs/design/match-media-stylesheets.md | 6 ++- .../docs/guide/declaring-templates.md | 4 +- .../docs/guide/defining-elements.md | 8 ++-- .../fast-element/docs/guide/leveraging-css.md | 10 ++--- .../docs/guide/observables-and-state.md | 6 +-- .../docs/guide/using-directives.md | 18 ++++---- .../docs/guide/working-with-shadow-dom.md | 10 ++--- .../docs/integrations/aspnet.md | 6 +-- .../docs/integrations/aurelia.md | 12 +++--- .../docs/integrations/blazor.md | 6 +-- .../docs/integrations/webpack.md | 6 +-- .../fast-foundation/src/accordion/README.md | 2 +- .../fast-foundation/src/anchor/README.md | 2 +- .../src/anchored-region/README.md | 2 +- .../fast-foundation/src/badge/README.md | 2 +- .../fast-foundation/src/button/README.md | 2 +- .../fast-foundation/src/card/README.md | 2 +- .../fast-foundation/src/checkbox/README.md | 2 +- .../src/design-system-provider/README.md | 13 +++--- .../fast-foundation/src/dialog/README.md | 2 +- .../fast-foundation/src/divider/README.md | 2 +- .../fast-foundation/src/flipper/README.md | 2 +- .../fast-foundation/src/menu-item/README.md | 2 +- .../fast-foundation/src/menu/README.md | 2 +- .../fast-foundation/src/progress/README.md | 2 +- .../fast-foundation/src/radio-group/README.md | 2 +- .../fast-foundation/src/radio/README.md | 2 +- .../src/slider-label/README.md | 2 +- .../fast-foundation/src/slider/README.md | 2 +- .../fast-foundation/src/switch/README.md | 2 +- .../fast-foundation/src/tabs/README.md | 2 +- .../fast-foundation/src/text-area/README.md | 2 +- .../fast-foundation/src/text-field/README.md | 2 +- .../src/docs/components/getting-started.md | 4 +- sites/website/src/docs/introduction.md | 4 +- 38 files changed, 113 insertions(+), 90 deletions(-) diff --git a/packages/web-components/fast-components/docs/design/color.md b/packages/web-components/fast-components/docs/design/color.md index 8a22966cff5..7cc2ec3d9c9 100644 --- a/packages/web-components/fast-components/docs/design/color.md +++ b/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,6 +63,7 @@ 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. See [backgroundColor](api/fast-components.fastdesignsystemprovider.backgroundcolor.md) for more details. @@ -64,8 +71,10 @@ See [backgroundColor](api/fast-components.fastdesignsystemprovider.backgroundcol ### 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 | diff --git a/packages/web-components/fast-components/docs/design/design-system.md b/packages/web-components/fast-components/docs/design/design-system.md index 05778753d03..f1a32eb5c0f 100644 --- a/packages/web-components/fast-components/docs/design/design-system.md +++ b/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 | diff --git a/packages/web-components/fast-components/docs/design/introduction.md b/packages/web-components/fast-components/docs/design/introduction.md index 1246b37c586..bca191d5e14 100644 --- a/packages/web-components/fast-components/docs/design/introduction.md +++ b/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 diff --git a/packages/web-components/fast-components/docs/design/match-media-stylesheets.md b/packages/web-components/fast-components/docs/design/match-media-stylesheets.md index c526c1d8646..8c3deeb5c63 100644 --- a/packages/web-components/fast-components/docs/design/match-media-stylesheets.md +++ b/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__ diff --git a/packages/web-components/fast-element/docs/guide/declaring-templates.md b/packages/web-components/fast-element/docs/guide/declaring-templates.md index cfe4ec14625..f1386c00987 100644 --- a/packages/web-components/fast-element/docs/guide/declaring-templates.md +++ b/packages/web-components/fast-element/docs/guide/declaring-templates.md @@ -5,7 +5,7 @@ sidebar_label: Declaring Templates custom_edit_url: https://github.com/microsoft/fast-dna/edit/master/packages/web-components/fast-element/docs/guide/declaring-templates.md --- -## Basic Templates +## Basic templates While you can create and update nodes in the Shadow DOM manually, `FASTElement` provides a streamlined templating system for the most common rendering scenarios. To create an HTML template for an element, import and use the `html` tagged template helper and pass the template to the `@customElement` decorator. @@ -46,7 +46,7 @@ Finally, we associate the template with our custom element by using a new form o With this in place, we now have a `name-tag` element that will render its template into the Shadow DOM and automatically update the `h3` content whenever the name tag's `greeting` attribute changes. Give it a try! -## Understanding Bindings +## Understanding bindings We've seen how arrow functions can be used to declare dynamic parts of templates. Let's look at a few more examples to see the breadth of what is available to you. 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 0b38503a2e1..8b40bb17061 100644 --- a/packages/web-components/fast-element/docs/guide/defining-elements.md +++ b/packages/web-components/fast-element/docs/guide/defining-elements.md @@ -5,7 +5,7 @@ sidebar_label: Defining Elements custom_edit_url: https://github.com/microsoft/fast-dna/edit/master/packages/web-components/fast-element/docs/guide/defining-elements.md --- -## Basic Elements +## Basic elements To define a custom element, begin by creating a class that extends `FASTElement` and decorate it with the `@customElement` decorator, providing the element name. @@ -65,7 +65,7 @@ To see it in action, you can use the same HTML as above, or change the default ` ``` -## Customizing Attributes +## Customizing attributes By default, any attribute created with `@attr` will perform no explicit type coercion other than when it reflects its value to the HTML DOM via the `setAttribute` API. However, you can convert DOM attribute string values to and from arbitrary types as well as control the `mode` that is used to reflect property values to the DOM. There are three modes available through the `mode` property of the attribute configuration: @@ -134,7 +134,7 @@ export class MyCounter extends FASTElement { } ``` -## The Element Lifecycle +## The element lifecycle All Web Components support a series of lifecycle events that you can tap into to execute custom code at specific points in time. `FASTElement` implements several of these callbacks automatically in order to enable features of its templating engine (described in [declaring templates](./declaring-templates)). However, you can override them to provide your own code. Here's an example of how you would execute custom code when your element is inserted into the DOM. @@ -168,7 +168,7 @@ The full list of available lifecycle callbacks is: | attributeChangedCallback(attrName, oldVal, newVal) | Runs any time one of the element's custom attributes changes. `FASTElement` uses this to sync the attribute with its property. When the property updates, a render update is also queued, if there was a template dependency. | | adoptedCallback | Runs if the element was moved from its current `document` into a new `document` via a call to the `adoptNode(...)` API. | -## Working without Decorators +## Working without decorators The examples above and those throughout our documentation leverage TypeScript, and in particular, the decorators feature of the language. Decorators are an upcoming feature planned for a future version of JavaScript, but their design is not yet finished. While the syntax for decorator usage is not likely to change in the final version of the feature, some of our community members may feel uncomfortable using this feature at this stage. Fortunately, FAST Elements can be completely defined in Vanilla JS, without using decorators, by leveraging a static `definition` field on your class. The `definition` filed only needs to present the same configuration as the `@customElement` decorator. Here's an example that shows the use of the `definition` field along with a manual call to `define` the element: diff --git a/packages/web-components/fast-element/docs/guide/leveraging-css.md b/packages/web-components/fast-element/docs/guide/leveraging-css.md index d03ddbc53b5..859fccbeb2a 100644 --- a/packages/web-components/fast-element/docs/guide/leveraging-css.md +++ b/packages/web-components/fast-element/docs/guide/leveraging-css.md @@ -5,7 +5,7 @@ sidebar_label: Leveraging CSS custom_edit_url: https://github.com/microsoft/fast-dna/edit/master/packages/web-components/fast-element/docs/guide/leveraging-css.md --- -## Basic Styles +## Basic styles The final piece of our component story is CSS. Similar to HTML, `FASTElement` provides a `css` tagged template helper to allow creating and re-using CSS. Let's add some CSS for our `name-tag` component. @@ -96,7 +96,7 @@ Using the `css` helper, we're able to create `ElementStyles`. We configure this We've used [CSS Custom Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*) throughout our CSS as well as [CSS Calc](https://developer.mozilla.org/en-US/docs/Web/CSS/calc) in order to enable our component to be styled in basic ways by consumers. Additionally, consider adding [CSS Shadow Parts](https://developer.mozilla.org/en-US/docs/Web/CSS/::part) to your template, to enable even more powerful customization. ::: -## Composing Styles +## Composing styles One of the nice features of `ElementStyles` is that it can be composed with other styles. Imagine that we had a CSS normalize that we wanted to use in our `name-tag` component. We could compose that into our styles like this: @@ -128,7 +128,7 @@ Rather than simply concatenating CSS strings, the `css` helper understands that You can also pass a CSS string or a [CSSStyleSheet](https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleSheet) instance directly to the element definition, without needing to use the `css` helper and it will automatically be converted into `ElementStyles`. The advantage of using the `css` helper is that it enables the rich composition and reuse of styles described above, with automatic runtime caching for memory efficiency and performance. ::: -## Shadow DOM Styling +## Shadow DOM styling You may have noticed the `:host` selector we used in our `name-tag` styles. This selector allows us to apply styles directly to our custom element. Here are a few things to consider always configuring for your host element: @@ -136,7 +136,7 @@ You may have noticed the `:host` selector we used in our `name-tag` styles. This * **contain** - If your element's painting is contained within its bounds, consider setting the CSS `contain` property to `content`. The right containment model can positively affect your element's performance. [See the MDN docs](https://developer.mozilla.org/en-US/docs/web/css/contain) for more information on the various values of `contain` and what they do. * **hidden** - In addition to a default `display` style, add support for `hidden` so that your default `display` does not override this state. This can be done with `:host([hidden]) { display: none }`. -## Slotted Content +## Slotted content In addition to providing host styles, you can also provide default styles for content that gets slotted. For example, if we wanted to style all `img` elements that were slotted into our `name-tag`, we could do it like this: @@ -164,7 +164,7 @@ const styles = css` Both slotted and host styles can be overridden by the element user. Think of these as the *default* styles that you are providing, so that your elements look and function correctly out-of-the-box. ::: -## 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*: diff --git a/packages/web-components/fast-element/docs/guide/observables-and-state.md b/packages/web-components/fast-element/docs/guide/observables-and-state.md index 8cedcf5bbcc..c79b11c6b48 100644 --- a/packages/web-components/fast-element/docs/guide/observables-and-state.md +++ b/packages/web-components/fast-element/docs/guide/observables-and-state.md @@ -27,11 +27,11 @@ Properties with only a getter, that function as a computed property over other o ### Features -#### Access Tracking +#### Access tracking When decorated properties are accessed during template rendering, they are tracked, allowing the engine to deeply understand the relationship between your model and view. -#### Internal Observation +#### Internal observation On the class where the attr/observable is defined, you can optionally implement a *propertyName*Changed method to easily respond to changes in your own state. @@ -47,7 +47,7 @@ export class Person { } ``` -#### External Observation +#### External observation Decorated properties can be subscribed to, to receive notification of changes in the property. The templating engine uses this, but you can also directly subscribe as well. Here's how you would subscribe to changes in the `name` property pf a `Person` class: diff --git a/packages/web-components/fast-element/docs/guide/using-directives.md b/packages/web-components/fast-element/docs/guide/using-directives.md index 40a09ff344b..abd8a740ceb 100644 --- a/packages/web-components/fast-element/docs/guide/using-directives.md +++ b/packages/web-components/fast-element/docs/guide/using-directives.md @@ -7,11 +7,11 @@ custom_edit_url: https://github.com/microsoft/fast-dna/edit/master/packages/web- In addition to declaring dynamic parts of templates with expressions, you also have access to several powerful *directives*, which aid in common scenarios. -## Structural Directives +## Structural directives Structural directives change the shape of the DOM itself by adding and removing nodes based on the state of your element. -### The When Directive +### The `when` directive The `when` directive enables you to conditionally render blocks of HTML. When you provide an expression to `when` it will render the child template into the DOM when the expression evaluates to `true` and remove the child template when it evaluates to `false` (or if it is never `true`, the rendering will be skipped entirely). @@ -69,7 +69,7 @@ const template = html` `; ``` -### The Repeat Directive +### The `repeat` directive To render a list of data, use the `repeat` directive, providing the list to render and a template to use in rendering each item. @@ -141,7 +141,7 @@ Some context properties are opt-in because they are more costly to update. So, f In addition to providing a template to render the items with, you can also provide an expression that evaluates to a template. This enables you to dynamically change what you are using to render the items. Each item will still be rendered with the same template, but you can use techniques from "Composing Templates" below to render a different template depending on the item itself. -### Composing Templates +### Composing templates The `ViewTemplate` returned from the `html` tag helper has special handling when it is used inside of another template. This is done so that you can create templates and compose them into other templates. @@ -396,11 +396,11 @@ export function when(condition, templateOrTemplateExpression) { As you can see, all that `when` does is compose a new function that checks your condition. If it's `true,` it invokes your template provider function; if `false`, it returns `null`, indicating nothing should be rendered. -## Referential Directives +## Referential directives Referential directives allow you to easily get references to DOM nodes in various scenarios. -### The Ref Directive +### The `ref` directive Sometimes you need a direct reference to a single DOM node from your template. This might be because you want to control the playback of a `video` element, use the drawing context of a `canvas` element, or pass an element to a 3rd party library. Whatever the reason, you can get a reference to the DOM node by using the `ref` directive. @@ -436,7 +436,7 @@ Place the `ref` directive on the element you want to reference and provide it wi If you provide a type for your HTML template, TypeScript will type check the property name you provide to ensure that it actually exists on your element. ::: -### The Children Directive +### The `children` directive Besides using `ref` to reference a single DOM node, you can use `children` to get references to all child nodes of a particular element. @@ -490,7 +490,7 @@ const template = html` `; ``` -### The Slotted Directive +### The `slotted` directive Sometimes you may want references to all nodes that are assigned to a particular slot. To accomplish this, use the `slotted` directive. (For more on slots, see [Working with Shadow DOM](./working-with-shadow-dom).) @@ -519,7 +519,7 @@ export class MyElement extends FASTElement { Similar to the `children` directive, the `slotted` directive will populate the `slottedNodes` property with nodes assigned to the slot. If `slottedNodes` is decorated with `@observable` then it will be updated dynamically as the assigned nodes change. Like any observable, you can optionally implement a *propertyName*Changed method to be notified when the nodes change. Additionally, you can provide an `options` object to the `slotted` directive to specify a customized configuration for the underlying [assignedNodes() API call](https://developer.mozilla.org/en-US/docs/Web/API/HTMLSlotElement/assignedNodes) or specify a `filter`. -## Host Directives +## Host directives So far, our bindings and directives have only affected elements within the Shadow DOM of the component. However, sometimes you want to affect the host element itself, based on property state. For example, a progress component might want to write various `aria` attributes to the host, based on the progress state. In order to facilitate scenarios like this, you can use a `template` element as the root of your template, and it will represent the host element. Any attribute or directive you place on the `template` element will be applied to the host itself. diff --git a/packages/web-components/fast-element/docs/guide/working-with-shadow-dom.md b/packages/web-components/fast-element/docs/guide/working-with-shadow-dom.md index 372a399f69f..8b102707c82 100644 --- a/packages/web-components/fast-element/docs/guide/working-with-shadow-dom.md +++ b/packages/web-components/fast-element/docs/guide/working-with-shadow-dom.md @@ -7,7 +7,7 @@ custom_edit_url: https://github.com/microsoft/fast-dna/edit/master/packages/web- So far we've looked at how to define elements, how to define attributes on those elements, and how to control element rendering through declarative templates. However, we haven't yet seen how our custom elements can be composed together with standard HTML or other custom elements. -## The Default Slot +## The default slot To enable composition, `FASTElement` leverages the Shadow DOM standard. Previously, we've seen how `FASTElement` automatically attaches a `ShadowRoot`, and when your element declares a template, it renders that template into the Shadow DOM. To enable element composition, all we need to do is make use of the standard `` element within our template. @@ -79,7 +79,7 @@ If you find the terms "Light DOM" and "Shadow DOM" unintuitive, you're not alone With slots at our disposal, we now unlock the full compositional model of HTML for use in our own elements. However, there's even more that slots can do. -## Named Slots +## Named slots In the example above, we use a single `slot` element to render *all* content placed between the start and end tags of the `name-tag`. However, we're not limited to only having a default slot. We can also have *named slots* that declare other locations to which we can render content. To demonstrate this, let's add a named slot to our `name-tag`'s template where we can display the person's avatar. @@ -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. @@ -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. diff --git a/packages/web-components/fast-foundation/docs/integrations/aspnet.md b/packages/web-components/fast-foundation/docs/integrations/aspnet.md index 5f6af1a3909..28b9f878e34 100644 --- a/packages/web-components/fast-foundation/docs/integrations/aspnet.md +++ b/packages/web-components/fast-foundation/docs/integrations/aspnet.md @@ -7,7 +7,7 @@ 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). @@ -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: diff --git a/packages/web-components/fast-foundation/docs/integrations/aurelia.md b/packages/web-components/fast-foundation/docs/integrations/aurelia.md index 24b3ed982ea..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/). @@ -23,7 +23,7 @@ Follow the prompts, answering each question in turn. It is recommended that you 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. @@ -103,7 +103,7 @@ 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/). @@ -123,7 +123,7 @@ Follow the prompts, answering each question in turn. It is recommended that you 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. diff --git a/packages/web-components/fast-foundation/docs/integrations/blazor.md b/packages/web-components/fast-foundation/docs/integrations/blazor.md index b06cb07fcf7..fc87f2f516a 100644 --- a/packages/web-components/fast-foundation/docs/integrations/blazor.md +++ b/packages/web-components/fast-foundation/docs/integrations/blazor.md @@ -7,7 +7,7 @@ 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). @@ -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: diff --git a/packages/web-components/fast-foundation/docs/integrations/webpack.md b/packages/web-components/fast-foundation/docs/integrations/webpack.md index 34778b01e23..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,7 +41,7 @@ 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 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/). @@ -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. 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 9bbfa85b873..b9fb99810be 100644 --- a/packages/web-components/fast-foundation/src/button/README.md +++ b/packages/web-components/fast-foundation/src/button/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/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 8233c0a9072..ff519085007 100644 --- a/packages/web-components/fast-foundation/src/menu/README.md +++ b/packages/web-components/fast-foundation/src/menu/README.md @@ -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 e61c8a3ab60..e6ad019bf79 100644 --- a/packages/web-components/fast-foundation/src/progress/README.md +++ b/packages/web-components/fast-foundation/src/progress/README.md @@ -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 2c37a2d8751..7b59f206f0f 100644 --- a/packages/web-components/fast-foundation/src/radio-group/README.md +++ b/packages/web-components/fast-foundation/src/radio-group/README.md @@ -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/components/getting-started.md b/sites/website/src/docs/components/getting-started.md index ec7210cefb8..8a921c185e3 100644 --- a/sites/website/src/docs/components/getting-started.md +++ b/sites/website/src/docs/components/getting-started.md @@ -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,7 +74,7 @@ The [Design System Provider](./design-system-provider) provides design informati ``` -## Add Components +## Add components 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. diff --git a/sites/website/src/docs/introduction.md b/sites/website/src/docs/introduction.md index afbbc503c1b..7d19c67f5d0 100644 --- a/sites/website/src/docs/introduction.md +++ b/sites/website/src/docs/introduction.md @@ -57,11 +57,11 @@ This package does not export Web Components registered as [custom elements](http 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). From 1eb4271d899e3af4f16c7eded07280940e4586b9 Mon Sep 17 00:00:00 2001 From: Rob Eisenberg Date: Tue, 23 Jun 2020 13:04:18 -0400 Subject: [PATCH 06/10] Update packages/web-components/fast-components-msft/README.md Co-authored-by: Chris Holt --- packages/web-components/fast-components-msft/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/web-components/fast-components-msft/README.md b/packages/web-components/fast-components-msft/README.md index 59d93c91324..46968864eb9 100644 --- a/packages/web-components/fast-components-msft/README.md +++ b/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 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 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 From ecaa878ddbb3124b9c18336de54179cc146a3892 Mon Sep 17 00:00:00 2001 From: Rob Eisenberg Date: Tue, 23 Jun 2020 15:36:57 -0400 Subject: [PATCH 07/10] docs: fix up some design language wording to make fluent clearer --- README.md | 2 +- packages/web-components/README.md | 2 +- sites/website/src/docs/components/getting-started.md | 2 +- sites/website/src/docs/introduction.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 50199f3ef49..61dea61d11e 100644 --- a/README.md +++ b/README.md @@ -63,7 +63,7 @@ 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-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 diff --git a/packages/web-components/README.md b/packages/web-components/README.md index 6df8cbf8c6f..1dc0fa70b93 100644 --- a/packages/web-components/README.md +++ b/packages/web-components/README.md @@ -30,4 +30,4 @@ 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-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. \ No newline at end of file +`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. \ No newline at end of file diff --git a/sites/website/src/docs/components/getting-started.md b/sites/website/src/docs/components/getting-started.md index 8a921c185e3..8b242e7899d 100644 --- a/sites/website/src/docs/components/getting-started.md +++ b/sites/website/src/docs/components/getting-started.md @@ -6,7 +6,7 @@ custom_edit_url: https://github.com/microsoft/fast-dna/edit/master/sites/website [![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) -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 diff --git a/sites/website/src/docs/introduction.md b/sites/website/src/docs/introduction.md index 7d19c67f5d0..d1eeed90c18 100644 --- a/sites/website/src/docs/introduction.md +++ b/sites/website/src/docs/introduction.md @@ -51,7 +51,7 @@ 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-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 From 0c5dd5f585606bfecbc7417914f8c31e128598b6 Mon Sep 17 00:00:00 2001 From: Rob Eisenberg Date: Tue, 23 Jun 2020 15:43:47 -0400 Subject: [PATCH 08/10] docs: adjust explanation in faq for fluent, fluent ui, and fast --- sites/website/src/docs/resources/faq.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/sites/website/src/docs/resources/faq.md b/sites/website/src/docs/resources/faq.md index 8bf6f9c510d..2863be57305 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 a tech stack that 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 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 a particular implementation of the Fluent Design language, implemented natively in React. FAST is a tech stack that enables implementing components, design systems, and apps (see "What's the difference between FAST and Fluent"). The FAST team provides an implementation of Fluent, built with web components, via its `fast-components-msft` package. #### How does `fast-element` compare to "Framework X"? From c81fd1b151a83be4c0a2e50cc83235744bd5e650 Mon Sep 17 00:00:00 2001 From: Rob Eisenberg Date: Tue, 23 Jun 2020 15:47:17 -0400 Subject: [PATCH 09/10] docs(faq): fix typo --- sites/website/src/docs/resources/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sites/website/src/docs/resources/faq.md b/sites/website/src/docs/resources/faq.md index 2863be57305..08d740a40bd 100644 --- a/sites/website/src/docs/resources/faq.md +++ b/sites/website/src/docs/resources/faq.md @@ -19,7 +19,7 @@ Fluent is Microsoft's design language, independent of any particular implementat ### What's the difference between FAST and Fluent UI? -Fluent UI refers to a particular implementation of the Fluent Design language, implemented natively in React. FAST is a tech stack that enables implementing components, design systems, and apps (see "What's the difference between FAST and Fluent"). The FAST team provides an implementation of Fluent, built with web components, via its `fast-components-msft` package. +Fluent UI refers to a particular implementation of the Fluent Design language, implemented natively in React. FAST is a tech stack that enables implementing components, design systems, and apps (see "What's the difference between FAST and Fluent?"). The FAST team provides an implementation of Fluent, built with web components, via its `fast-components-msft` package. #### How does `fast-element` compare to "Framework X"? From 9caf8f52e3eb0dbce597e52786355e62b6b068c6 Mon Sep 17 00:00:00 2001 From: Rob Eisenberg Date: Tue, 23 Jun 2020 16:07:58 -0400 Subject: [PATCH 10/10] docs(faq): messaging clarity after discussion --- sites/website/src/docs/resources/faq.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sites/website/src/docs/resources/faq.md b/sites/website/src/docs/resources/faq.md index 08d740a40bd..7a9c96f2816 100644 --- a/sites/website/src/docs/resources/faq.md +++ b/sites/website/src/docs/resources/faq.md @@ -15,11 +15,11 @@ When the project was originally founded, it went by the name FAST-DNA, which sto ### What's the difference between FAST and Fluent? -Fluent is Microsoft's design language, independent of any particular implementation technology. FAST is a tech stack that 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 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. +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 refers to a particular implementation of the Fluent Design language, implemented natively in React. FAST is a tech stack that enables implementing components, design systems, and apps (see "What's the difference between FAST and Fluent?"). The FAST team provides an implementation of Fluent, built with web components, via its `fast-components-msft` package. +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"?