fix: updated component readme.md files to be more consistent

packages/fast-components-react-msft/src/action-trigger/README.md

@@ -1,13 +1,17 @@
 # Action trigger
+
 *Action trigger* performs an operation that is positioned inline on the page. Use *action trigger* for taking an action or for interacting with something like a file or media resource. Examples include “Save,” “Edit,” or “Play.” Using an *action trigger* keeps the user within the current context rather than forcing them to navigate to a different page. Thus, use an *action trigger* as part of an interactive in-page experience.  *Action trigger* is built using a host element such as a button or an anchor, and can also be used in a group of elements. Typically, *action triggers* are used inside interactive tables or related to other interactive content. This means that the trigger should be co-located with the positioning of the material it will be acting upon. There is no provision for displaying alternate labels to indicate a change of state — use the action toggle if you need this capability.
 
 ## Usage
+
 Use *action trigger* to take an action in the middle of a workflow. For example, to play an album before buying it. Use a glyph and/or text label so the user can visually identify the *action trigger*. When using a glyph label only, add a tooltip to the *action trigger* so that there is a secondary means for identifying the function of the *action trigger*.
 
 The required "glyph" prop takes a function that returns a ReactNode to render the glyph (ie. a [render prop](https://reactjs.org/docs/render-props.html)).  Note that the function should accept a string parameter that is applied as a classname to the top level element of the resulting node.  This classname  will be populated by the *action trigger* component to use an internally generated class ("actionTrigger_glyph") to apply to the glyph for styling.
 
 ## Style guidance
-Position the *action trigger* so that it is in close proximity to the item it will be acting upon, and where it is easy for the user to identify this association. 
+
+Position the *action trigger* so that it is in close proximity to the item it will be acting upon, and where it is easy for the user to identify this association.
 
 ## Accessibility
-If more verbose language is needed to fully capture the *action trigger* meaning for assistive technologies, an unhandled prop `aria-label` may be used to provide more context.
+
+If more verbose language is needed to fully capture the *action trigger* meaning for assistive technologies, an unhandled prop [`aria-label`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-label_attribute) may be used to provide more context.

packages/fast-components-react-msft/src/breadcrumb/README.md

@@ -1,8 +1,11 @@
-## Breadcrumb
-A generic breadcrumb component following the w3.org [breadcrumb](https://www.w3.org/TR/2017/NOTE-wai-aria-practices-1.1-20171214/examples/breadcrumb/index.html) pattern. The *breadcrumb* will accept any child elements but is built to work with `a` elements.
+# Breadcrumb
+
+A breadcrumb component following the w3.org [breadcrumb](https://www.w3.org/TR/2017/NOTE-wai-aria-practices-1.1-20171214/examples/breadcrumb/index.html) pattern. The *breadcrumb* will accept any child elements but is built to work with [`<a>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a) elements.
+
+## Usage
 
-### Usage
 To denote the current page the *breadcrumb* automatically sets the last child `aria-current` prop to "page", an enumerated type value for `aria-current`. Addtionally *breadcrumb* accepts an optional `separator` prop that will render a ReactNode between navigation elements.
 
-### Accessibility
-The *breadcrumb* component consists of a `nav` element with `aria-label` set to a `label` prop. One should set the `label` prop to identify the structure as a breadcrumb trail and make it a navigation landmark so that it is easy to locate. The last child element `aria-current` prop is marked "page" to indicate that it reprents the current page.
+## Accessibility
+
+The *breadcrumb* component consists of a [navigation section](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/nav_) element with [`aria-label`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-label_attribute) set to a `label` prop. One should set the `label` prop to identify the structure as a breadcrumb trail and make it a navigation landmark so that it is easy to locate. The last child element `aria-current` prop is marked "page" to indicate that it reprents the current page.

packages/fast-components-react-msft/src/button/README.md

@@ -1,8 +1,11 @@
 # Button
-The *Button* component can be either an [anchor](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a) or [button](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button) element but will appear with button styling. Setting the `href` prop will automatically set the element type to `anchor`.
+
+The *Button* component can be either an [`<a>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a) or [`<button>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button) element but will appear with button styling. Setting the `href` prop will set the element to [`<a>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a) automatically.
 
 ## Usage
+
 Make sure the button text conveys a clear purpose to the user. Button text must describe the action the button will perform and should include a verb. Use concise, specific, self-explanatory text &ndash; usually a single word. Buttons should always include a noun if there is any room for interpretation about what the verb operates on. If the button’s text content is dynamic, consider how the button will resize and what will happen to components around it. Use only a single line of text. The text shouldn’t change unless for localization. Default buttons should always perform safe operations. For example, a default button should never delete.
 
 ## Style guidance
+
 Show only one primary button that inherits theme color at rest state. In the event there are more than two buttons with equal priority, all buttons should have neutral backgrounds. “Submit,” “OK,” and “Apply” buttons should always be styled as primary buttons. When “Reset” or “Cancel” buttons appear alongside one of the above, they should be styled as secondary buttons.

packages/fast-components-react-msft/src/call-to-action/README.md

@@ -1,13 +1,17 @@
 # Call to action
+
 A *call to action* is typically involved in selling or marketing a product and should entice users to perform an action around a product. For example, it may call the user to purchase a product, download an app, or to learn more.
 
 ## Usage
+
 Interacting with *call to action* should generally navigate a user to a targeted page where they can take action on the item. For example, clicking on a ‘Buy now’ call to action for a Microsoft device will take them to a product detail page where they can configure or purchase the device. Call to action text should be as concise and focused as possible, relying on the content around it to communicate the details and context of the action.
 
 Use *call to action* to urge a user to take action on what the page is converying or promoting. Always make sure to use unique text strings for each call to action. This leads to better accessibility and assists in quicker voice navigation. Always keep the text as concise as possible and use sentence casing (as opposed to all caps).
 
 ## Style guidance
+
 The default *call to action* uses the accent color as the component background. If the accent color background is not desired, a secondary configuration is also available with a neutral, lighter background. Use the lightweight configuration of *call to action* if no background is desired.
 
 ## Accessibility
-If more verbose language is needed to fully capture the *call to action* meaning for assistive technologies, an unhandled prop `aria-label` may be used to provide more context.
+
+If more verbose language is needed to fully capture the *call to action* meaning for assistive technologies, an unhandled prop [`aria-label`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-label_attribute) may be used to provide more context.

packages/fast-components-react-msft/src/caption/README.md

@@ -1,8 +1,11 @@
 # Caption
+
 *Caption* component can help provide context to images, figures, or tables.
 
 ## Usage
+
 *Caption* should be used sparingly. Due to the small font size of *caption*, legibility may suffer, so it should not be used for long descriptions or as a paragraph. It should add informational value without being a distraction. *Captions* are also used for footnotes or as secondary text to provide additional information.
 
 ## Style guidance
+
 The default size is 1, with an additional smaller size at 2.

packages/fast-components-react-msft/src/card/README.md

@@ -1,10 +1,13 @@
 # Card
-*Cards* are snapshots of content that are typically used in a group to present collections of related information. *Cards* can represent any quickly consumable information.  The *card* component can be either a [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div), [article](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/article), or [section](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/section) element.
+
+*Cards* are snapshots of content that are typically used in a group to present collections of related information. *Cards* can represent any quickly consumable information.  The *card* component can be either a [`<div>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div), [`<article>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/article), or [`<section>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/section) element.
 
 ## Usage
+
 Use *cards* when displaying a feed of content or when a stronger isolation between each content items is needed. *Cards* are also well suited for scenarios where the content is not consistent and requires different fields, image sizes, or content, which is often the case in a feed. *Cards* create an opportunity to present a collection of related content in a rich and dynamic way.
 
 Use *cards* when:
-- There are many content items that need to be displayed.
-- The content available between each content item is not consistent resulting in many different sizes and layouts that can be used together.
-- The content items need to be sorted in various ways that can’t rely on a curated layout. However, Cards can also be used for curated layouts.
+
+* There are many content items that need to be displayed.
+* The content available between each content item is not consistent resulting in many different sizes and layouts that can be used together.
+* The content items need to be sorted in various ways that can’t rely on a curated layout. However, Cards can also be used for curated layouts.

packages/fast-components-react-msft/src/checkbox/README.md

@@ -1,8 +1,11 @@
 # Checkbox
+
 Use a *checkbox* to select or deselect items in a list. Use a single *checkbox* by itself in a *toggle* scenario (e.g. "remember me" in a login scenario). Use it within a group for multi-select scenarios, where a user chooses one or more items from a group of choices that are NOT mutually exclusive.
 
 ## Usage
-*Checkboxes* can be grouped in collections where checking/unchecking the collection *checkbox* can facilitate choosing all or none within the collection, while also preserving the ability to check/uncheck sub-choices. When a collection of sub-choices have both checked and unchecked items, the parent *checkbox* needs to display as indeterminate. The indeterminate functionality is beyond the scope of the framework and is the responsibility of the consuming team.
+
+*Checkboxes* can be grouped in collections where checking/unchecking the collection *checkbox* can facilitate choosing all or none within the collection, while also preserving the ability to check or uncheck sub-choices. When a collection of sub-choices have both checked and unchecked items, the parent *checkbox* needs to display as indeterminate. The indeterminate functionality is beyond the scope of the framework and is the responsibility of the consuming team.
 
 ## Accessibility
-Valid markup requires *checkbox* to be used inside a form with a submit button.
+
+Valid markup requires *checkbox* to be used inside a [`<form>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form) element with a [`<input type="submit">`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/submit) element.

packages/fast-components-react-msft/src/context-menu-item/README.md

@@ -1,2 +1,3 @@
 # Context menu item
-A item component intended to work as a child of the *context-menu*.
+
+A item component intended to work as a child of the *context menu*.

packages/fast-components-react-msft/src/context-menu/README.md

@@ -1,5 +1,7 @@
-## Context menu
-A generic menu component implementing the [menu](https://www.w3.org/TR/wai-aria-1.1/#menu) role and the keyboard navigation aligning to that role. The *context-menu* will accept any child elements but is built to work with *context-menu-item* and *divider* components.
+# Context menu
+
+A generic menu component implementing the [`menu`](https://www.w3.org/TR/wai-aria-1.1/#menu) role and the keyboard navigation aligning to that role. A *context menu* will accept any child elements but is built to work with *context menu item* and *divider* components.
 
 ## Accessibility
-The *context-menu* considers a child element focusable when it has a role of `"menuitem"`, `"menuitemradio"`, or `"menuitemcheckbox"`, and will manage focus between these elements automatically. 
+
+The *context menu* considers a child element focusable when it has a role of `menuitem`, `menuitemradio`, or `menuitemcheckbox` and will manage focus between these elements automatically.

packages/fast-components-react-msft/src/dialog/README.md

@@ -1,5 +1,9 @@
 # Dialog
-The *Dialog* component accepts children and can either be a modal, or a non-modal dialog. Modal dialogs prevent users from interacting with the rest of the page content, while non-modal dialogs allow users the ability to continue interacting with the page. The width and height of the dialog content area can be set by props. If no props are passed to set width or height, the dialog width will default to 640px and the height will default to 480px.
+
+The *dialog* component accepts children and can either be a modal, or a non-modal dialog. Modal dialogs prevent users from interacting with the rest of the page content, while non-modal dialogs allow users the ability to continue interacting with the page. The width and height of the dialog content area can be set by props. If no props are passed to set width or height, the dialog width will default to 640px and the height will default to 480px.
 
 ## Accessibility
-A *Dialog* must include one focusable control. When the dialog appears on the screen, keyboard focus should move to the first focusable element. While not required to be focused, a dialog should include a label. This can be applied as an `aria-label` using the `label` prop, or by referencing a child within the dialog with the `aria-labelledby` attribute using the `labelledby` prop. Optionally, additional context can be provided to assistive technologies by including an `aria-describedby` attribute which can be applied using the `describedby` prop. Learn more about dialog accessibility at [MDN](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_dialog_role).
+
+A *dialog* must include one focusable control. When the dialog appears on the screen, keyboard focus should move to the first focusable element. While not required to be focused, a dialog should include a label. This can be applied as an [`aria-label`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-label_attribute) using the `label` prop, or by referencing a child within the dialog with the [`aria-labelledby`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-labelledby_attribute) attribute using the `labelledby` prop. Optionally, additional context can be provided to assistive technologies by including an [`aria-describedby`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-describedby_attribute) attribute which can be applied using the `describedby` prop.
+
+Learn more about [dialog accessibility](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_dialog_role).

packages/fast-components-react-msft/src/divider/README.md

@@ -1,8 +1,11 @@
 # Divider
-The *Divider* component can be an [hr](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/hr) element.
+
+The *divider* component can be an [`<hr>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/hr) element.
 
 ## Usage
-Use the divider to show a change in the content between two blocks of information, that may not otherwise have a clear beginning or end, and to separate information blocks where the context or continuity changes between the blocks.
+
+Use the *divider* to show a change in the content between two blocks of information, that may not otherwise have a clear beginning or end, and to separate information blocks where the context or continuity changes between the blocks.
 
 ## Accessibility
-The *divider* is intrinsically set as `role="separator"`, and therefore is not necessary to explicitly include in the markup. When  usage involves changing the look of the page but does not have all the functional, interactive, or structural relevance implied by the hr element, `role="presentation"` can be applied from the prop interface.
+
+The *divider* is intrinsically set as `role="separator"`, and therefore is not necessary to explicitly include in the markup. When  usage involves changing the look of the page but does not have all the functional, interactive, or structural relevance implied by the hr element, [`role="presentation"`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_presentation_role) can be applied from the prop interface.

packages/fast-components-react-msft/src/flipper/README.md

@@ -1,5 +1,7 @@
 # Flipper
-Use the *flipper* component to page through content blocks one at a time or to scroll through content. 
+
+Use the *flipper* component to page through content blocks one at a time or to scroll through content.
 
 ## Accessibility
-In a majority of use cases, *flipper* should be hidden from assistive technologies as it typically is a secondary method of navigation which can be confusing for users. *Flipper* is hidden from screen readers by default, but can be exposed by passing the `visibleToAssistiveTechnologies` prop. When exposing *flipper* to screen readers, be sure to also pass the `label` prop. Correct and precise labeling of a component that is purely visual and has no textual context is needed to give proper context to assistive technologies. When exposed to screen readers, be sure to label each *flipper* clearly by describing what it will do. When a *flipper* does not have a valid action, it should be hidden — removing it from interaction.
+
+In a majority of use cases, *flipper* should be hidden from assistive technologies as it typically is a secondary method of navigation which can be confusing for users. *Flipper* is hidden from screen readers by default, but can be exposed by passing the `visibleToAssistiveTechnologies` prop. When exposing *flipper* to screen readers, be sure to also pass the `label` prop. Correct and precise labeling of a component that is purely visual and has no textual context is needed to give proper context to assistive technologies. When exposed to screen readers, be sure to label each *flipper* clearly by describing what it will do. When a *flipper* does not have a valid action, it should be hidden – removing it from interaction.