docs: Standardize component descriptions (#2108)

joebuono · Joe Buono · web-flow · commit 2770c8c7bdbf · 2022-06-16T13:14:06.000-04:00
* first batch of component description changes

* second batch of standardized descriptions

* last batch of standardized component descriptions

* update link description

* responding to pr feedback

* change to singular

* remove extraneous commit

Co-authored-by: Joe Buono &lt;joebuono@amazon.com&gt;
diff --git a/docs/src/pages/[platform]/components/alert/index.page.mdx b/docs/src/pages/[platform]/components/alert/index.page.mdx
@@ -1,6 +1,6 @@
 ---
 title: Alert
-description: An Alert displays a brief, important message in a way that attracts the user's attention without interrupting the user's task. Alerts are typically intended to be read out dynamically by a screen reader.
+description: Alert displays a brief message in a way that attracts the user’s attention without interrupting their task.
 ariaPattern: https://www.w3.org/WAI/ARIA/apg/patterns/alert
 themeSource: packages/ui/src/theme/tokens/components/alert.ts
 reactSource: packages/react/src/primitives/Alert/Alert.tsx
diff --git a/docs/src/pages/[platform]/components/badge/index.page.mdx b/docs/src/pages/[platform]/components/badge/index.page.mdx
@@ -1,6 +1,6 @@
 ---
 title: Badge
-description: A Badge is a small visual element to denote a status or message about an item. A small, color-coded visual element that contains letters or numbers, that you can use to label, categorize, or organize items.
+description: Badge is a color-coded element used to display a status or message about an item.
 themeSource: packages/ui/src/theme/tokens/components/badge.ts
 reactSource: packages/react/src/primitives/Badge/Badge.tsx
 supportedFrameworks: react
diff --git a/docs/src/pages/[platform]/components/button/index.page.mdx b/docs/src/pages/[platform]/components/button/index.page.mdx
@@ -1,6 +1,6 @@
 ---
 title: Button
-description: The Button primitive is used to trigger an action or event, such as submitting a form, opening a dialog, canceling an action, or performing a delete operation.
+description: Button allows users to perform actions.
 ariaPattern: https://www.w3.org/WAI/ARIA/apg/patterns/button
 themeSource: packages/ui/src/theme/tokens/components/button.ts
 reactSource: packages/react/src/primitives/Button/Button.tsx
diff --git a/docs/src/pages/[platform]/components/card/index.page.mdx b/docs/src/pages/[platform]/components/card/index.page.mdx
@@ -1,6 +1,6 @@
 ---
 title: Card
-description: The Card component can be used to group related pieces of content.
+description: Card groups related pieces of content.
 themeSource: packages/ui/src/theme/tokens/components/card.ts
 reactSource: packages/react/src/primitives/Card/Card.tsx
 supportedFrameworks: react
diff --git a/docs/src/pages/[platform]/components/checkboxfield/index.page.mdx b/docs/src/pages/[platform]/components/checkboxfield/index.page.mdx
@@ -1,6 +1,6 @@
 ---
 title: CheckboxField
-description: CheckboxField is used to mark an individual item as selected, or to select multiple items from a list of individual items.
+description: CheckboxField allows users to mark items as selected.
 ariaPattern: https://www.w3.org/WAI/ARIA/apg/patterns/checkbox
 themeSource: packages/ui/src/theme/tokens/components/checkbox.ts
 reactSource: packages/react/src/primitives/CheckboxField/CheckboxField.tsx
diff --git a/docs/src/pages/[platform]/components/divider/index.page.mdx b/docs/src/pages/[platform]/components/divider/index.page.mdx
@@ -1,6 +1,6 @@
 ---
 title: Divider
-description: A Divider creates separations in content. Dividers can help organize content and establish visual rhythm.
+description: Divider helps organize content, separate sections and establish visual rhythm.
 themeSource: packages/ui/src/theme/tokens/components/divider.ts
 reactSource: packages/react/src/primitives/Divider/Divider.tsx
 supportedFrameworks: react
diff --git a/docs/src/pages/[platform]/components/expander/index.page.mdx b/docs/src/pages/[platform]/components/expander/index.page.mdx
@@ -1,6 +1,6 @@
 ---
 title: Expander
-description: The Expander primitive enables users to expand or collapse a set of sections.
+description: Expander allows users to expand or collapse a set of sections.
 ariaPattern: https://www.w3.org/WAI/ARIA/apg/patterns/accordion
 themeSource: packages/ui/src/theme/tokens/components/expander.ts
 reactSource: packages/react/src/primitives/Expander/Expander.tsx
diff --git a/docs/src/pages/[platform]/components/flex/index.page.mdx b/docs/src/pages/[platform]/components/flex/index.page.mdx
@@ -1,6 +1,6 @@
 ---
 title: Flex
-description: A layout container using Flexbox.
+description: Flex provides a layout container using CSS Flexbox.
 reactSource: packages/react/src/primitives/Flex/Flex.tsx
 supportedFrameworks: react
 ---
diff --git a/docs/src/pages/[platform]/components/grid/index.page.mdx b/docs/src/pages/[platform]/components/grid/index.page.mdx
@@ -1,6 +1,6 @@
 ---
 title: Grid
-description: Grid provides a CSS grid container.
+description: Grid provides a layout container using CSS Grid.
 reactSource: packages/react/src/primitives/Grid/Grid.tsx
 supportedFrameworks: react
 ---
diff --git a/docs/src/pages/[platform]/components/heading/index.page.mdx b/docs/src/pages/[platform]/components/heading/index.page.mdx
@@ -1,6 +1,6 @@
 ---
 title: Heading
-description: A Heading primitive is used for semantic section heading text representing six levels.
+description: Heading renders semantic section heading text representing six levels.
 themeSource: packages/ui/src/theme/tokens/components/heading.ts
 reactSource: packages/react/src/primitives/Heading/Heading.tsx
 supportedFrameworks: react
diff --git a/docs/src/pages/[platform]/components/icon/index.page.mdx b/docs/src/pages/[platform]/components/icon/index.page.mdx
@@ -1,6 +1,6 @@
 ---
 title: Icon
-description: The icon component displays simple vector graphics for use in other components like Buttons.
+description: Icon is used to display Scalable Vector Graphics (SVG).
 themeSource: packages/ui/src/theme/tokens/components/icon.ts
 reactSource: packages/react/src/primitives/Icon/Icon.tsx
 supportedFrameworks: react
diff --git a/docs/src/pages/[platform]/components/image/index.page.mdx b/docs/src/pages/[platform]/components/image/index.page.mdx
@@ -1,6 +1,6 @@
 ---
 title: Image
-description: The Image primitive can be used to display responsive images.
+description: Image is used to display responsive images.
 themeSource: packages/ui/src/theme/tokens/components/image.ts
 reactSource: packages/react/src/primitives/Image/Image.tsx
 supportedFrameworks: react
diff --git a/docs/src/pages/[platform]/components/link/index.page.mdx b/docs/src/pages/[platform]/components/link/index.page.mdx
@@ -1,6 +1,6 @@
 ---
 title: Link
-description: Links are customizable and themable elements used for Navigation. By default Links render an anchor tag but can be configured to be used with routing libraries.
+description: Link renders an anchor element <a> by default and is primarily used for navigation.
 ariaPattern: https://www.w3.org/WAI/ARIA/apg/patterns/link
 themeSource: packages/ui/src/theme/tokens/components/link.ts
 reactSource: packages/react/src/primitives/Link/Link.tsx
diff --git a/docs/src/pages/[platform]/components/loader/index.page.mdx b/docs/src/pages/[platform]/components/loader/index.page.mdx
@@ -1,6 +1,6 @@
 ---
 title: Loader
-description: Loaders provide a visual cue that an action is either processing or awaiting a result. They are used to help the customer understand the system is working to fulfill a request.
+description: Loader provides a visual cue to the user that the system is processing, awaiting a result or working to fulfill a request.
 themeSource: packages/ui/src/theme/tokens/components/loader.ts
 reactSource: packages/react/src/primitives/Loader/Loader.tsx
 supportedFrameworks: react
diff --git a/docs/src/pages/[platform]/components/menu/index.page.mdx b/docs/src/pages/[platform]/components/menu/index.page.mdx
@@ -1,6 +1,6 @@
 ---
 title: Menu
-description: Menu provides an accessible, interactive menu for selecting actions within an application. Dropdown menu is collision-aware and will automatically change location based on available space.
+description: Menu provides a way for users to navigate and select actions within an application.
 ariaPattern: https://www.w3.org/WAI/ARIA/apg/patterns/menubutton/
 themeSource: packages/ui/src/theme/tokens/components/menu.ts
 reactSource: packages/react/src/primitives/Menu/Menu.tsx
diff --git a/docs/src/pages/[platform]/components/pagination/index.page.mdx b/docs/src/pages/[platform]/components/pagination/index.page.mdx
@@ -1,6 +1,6 @@
 ---
 title: Pagination
-description: Pagination provides navigation to allow customers to move between large sets of content that are distributed across multiple pages.
+description: Pagination allows users to navigate large sets of data.
 themeSource: packages/ui/src/theme/tokens/components/pagination.ts
 reactSource: packages/react/src/primitives/Pagination/Pagination.tsx
 supportedFrameworks: react
diff --git a/docs/src/pages/[platform]/components/passwordfield/index.page.mdx b/docs/src/pages/[platform]/components/passwordfield/index.page.mdx
@@ -1,6 +1,6 @@
 ---
 title: PasswordField
-description: The PasswordField primitive allows users to input passwords. It also features full password manager support and an optional show/hide password button for user convenience.
+description: PasswordField allows users to input passwords with the convenience of full password manager support.
 reactSource: packages/react/src/primitives/PasswordField/PasswordField.tsx
 supportedFrameworks: react
 ---
diff --git a/docs/src/pages/[platform]/components/phonenumberfield/index.page.mdx b/docs/src/pages/[platform]/components/phonenumberfield/index.page.mdx
@@ -1,6 +1,6 @@
 ---
 title: PhoneNumberField
-description: The PhoneNumberField form primitive can be used allow users to input a phone number.
+description: PhoneNumberField allows users to input phone numbers.
 reactSource: packages/react/src/primitives/PhoneNumberField/PhoneNumberField.tsx
 supportedFrameworks: react
 ---
diff --git a/docs/src/pages/[platform]/components/placeholder/index.page.mdx b/docs/src/pages/[platform]/components/placeholder/index.page.mdx
@@ -1,6 +1,6 @@
 ---
 title: Placeholder
-description: The Placeholder component is used to fill out the interface while content is loaded asynchronously.
+description: Placeholder can be used to fill out an interface while the content is loading.
 themeSource: packages/ui/src/theme/tokens/components/placeholder.ts
 reactSource: packages/react/src/primitives/Placeholder/Placeholder.tsx
 supportedFrameworks: react
diff --git a/docs/src/pages/[platform]/components/radiogroupfield/index.page.mdx b/docs/src/pages/[platform]/components/radiogroupfield/index.page.mdx
@@ -1,6 +1,6 @@
 ---
 title: RadioGroupField
-description: A RadioGroupField allows users to select a single option from a list of mutually exclusive options.
+description: RadioGroupField allows users to select a single option from a list of mutually exclusive options.
 ariaPattern: https://www.w3.org/WAI/ARIA/apg/patterns/radiobutton
 themeSource: packages/ui/src/theme/tokens/components/radio.ts
 reactSource: packages/react/src/primitives/RadioGroupField/RadioGroupField.tsx
diff --git a/docs/src/pages/[platform]/components/rating/index.page.mdx b/docs/src/pages/[platform]/components/rating/index.page.mdx
@@ -1,6 +1,6 @@
 ---
 title: Rating
-description: The Rating component displays a read-only star rating of a product or service.
+description: Rating displays a read-only star rating of a product or service.
 themeSource: packages/ui/src/theme/tokens/components/rating.ts
 reactSource: packages/react/src/primitives/Rating/Rating.tsx
 supportedFrameworks: react
diff --git a/docs/src/pages/[platform]/components/scrollview/index.page.mdx b/docs/src/pages/[platform]/components/scrollview/index.page.mdx
@@ -1,6 +1,6 @@
 ---
 title: ScrollView
-description: ScrollView is a View that allows scrolling of its inner contents.
+description: ScrollView allows content to be scrollable.
 reactSource: packages/react/src/primitives/ScrollView/ScrollView.tsx
 supportedFrameworks: react
 ---
diff --git a/docs/src/pages/[platform]/components/selectfield/index.page.mdx b/docs/src/pages/[platform]/components/selectfield/index.page.mdx
@@ -1,6 +1,6 @@
 ---
 title: SelectField
-description: The SelectField primitive allows you to create a drop-down list.
+description: SelectField allows users to select from a menu of options.
 ariaSource: https://www.w3.org/WAI/ARIA/apg/patterns/combobox
 themeSource: packages/ui/src/theme/tokens/components/select.ts
 reactSource: packages/react/src/primitives/SelectField/SelectField.tsx
diff --git a/docs/src/pages/[platform]/components/sliderfield/index.page.mdx b/docs/src/pages/[platform]/components/sliderfield/index.page.mdx
@@ -1,6 +1,6 @@
 ---
 title: SliderField
-description: Sliders allow users to quickly select a value within a range. They should be used when the upper and lower bounds to the range are invariable.
+description: SliderField allows users to select a value within a defined range.
 ariaPattern: https://www.w3.org/WAI/ARIA/apg/patterns/slider
 themeSource: packages/ui/src/theme/tokens/components/sliderField.ts
 reactSource: packages/react/src/primitives/SliderField/SliderField.tsx
diff --git a/docs/src/pages/[platform]/components/stepperfield/index.page.mdx b/docs/src/pages/[platform]/components/stepperfield/index.page.mdx
@@ -1,6 +1,6 @@
 ---
 title: StepperField
-description: A StepperField is a number input with buttons to increase or decrease the value.
+description: StepperField allows users to increment or decrement a number input.
 ariaPattern: https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton
 themeSource: packages/ui/src/theme/tokens/components/stepperField.ts
 reactSource: packages/react/src/primitives/StepperField/StepperField.tsx
diff --git a/docs/src/pages/[platform]/components/switchfield/index.page.mdx b/docs/src/pages/[platform]/components/switchfield/index.page.mdx
@@ -1,6 +1,6 @@
 ---
 title: SwitchField
-description: The SwitchField form primitive is a toggleable input type with a checked (on) and unchecked (off) state.
+description: SwitchField allows users to toggle an input.
 ariaPattern: https://www.w3.org/WAI/ARIA/apg/patterns/switch
 themeSource: packages/ui/src/theme/tokens/components/switchField.ts
 reactSource: packages/react/src/primitives/SwitchField/SwitchField.tsx
diff --git a/docs/src/pages/[platform]/components/table/index.page.mdx b/docs/src/pages/[platform]/components/table/index.page.mdx
@@ -1,6 +1,6 @@
 ---
 title: Table
-description: The Table primitive provides users with a styled and customizable table element.
+description: Table displays tabular data using the HTML <table> element and related elements.
 ariaPattern: https://www.w3.org/WAI/ARIA/apg/patterns/table
 themeSource: packages/ui/src/theme/tokens/components/table.ts
 reactSource: packages/react/src/primitives/Table/Table.tsx
diff --git a/docs/src/pages/[platform]/components/tabs/index.page.mdx b/docs/src/pages/[platform]/components/tabs/index.page.mdx
@@ -1,6 +1,6 @@
 ---
 title: Tabs
-description: Tabs organize content into multiple sections and allow users to navigate between them. The content under the set of Tabs should be related and form a coherent unit.
+description: Tabs allow users to navigate between sections of related content.
 ariaPattern: https://www.w3.org/WAI/ARIA/apg/patterns/tabpanel
 themeSource: packages/ui/src/theme/tokens/components/tabs.ts
 reactSource: packages/react/src/primitives/Tabs/Tabs.tsx
diff --git a/docs/src/pages/[platform]/components/text/index.page.mdx b/docs/src/pages/[platform]/components/text/index.page.mdx
@@ -1,6 +1,6 @@
 ---
 title: Text
-description: The Text primitive is used to display simple strings of text in an interface.
+description: Text is used to display text in an interface, and renders a <p> element by default.
 themeSource: packages/ui/src/theme/tokens/components/text.ts
 reactSource: packages/react/src/primitives/Text/Text.tsx
 supportedFrameworks: react
diff --git a/docs/src/pages/[platform]/components/textareafield/index.page.mdx b/docs/src/pages/[platform]/components/textareafield/index.page.mdx
@@ -1,6 +1,6 @@
 ---
 title: TextAreaField
-description: The TextAreaField form primitive can be used allow users to input multiline text content.
+description: TextAreaField allows users to input multiline text content.
 reactSource: packages/react/src/primitives/TextAreaField/TextAreaField.tsx
 supportedFrameworks: react
 ---
diff --git a/docs/src/pages/[platform]/components/textfield/index.page.mdx b/docs/src/pages/[platform]/components/textfield/index.page.mdx
@@ -1,6 +1,6 @@
 ---
 title: TextField
-description: The TextField form primitive can be used allow users to input text content.
+description: TextField allows users to input text content.
 reactSource: packages/react/src/primitives/TextField/TextField.tsx
 supportedFrameworks: react
 ---
diff --git a/docs/src/pages/[platform]/components/togglebutton/index.page.mdx b/docs/src/pages/[platform]/components/togglebutton/index.page.mdx
@@ -1,6 +1,6 @@
 ---
 title: ToggleButton
-description: A toggle button represents an on/off state for some configuration, for example switching on/off bold text in a text editor.
+description: ToggleButton allows users to toggle the on/off state for some configuration.
 ariaPattern: https://www.w3.org/WAI/ARIA/apg/patterns/button
 themeSource: packages/ui/src/theme/tokens/components/toggleButton.ts
 reactSource: packages/react/src/primitives/ToggleButton/ToggleButton.tsx
diff --git a/docs/src/pages/[platform]/components/visuallyhidden/index.page.mdx b/docs/src/pages/[platform]/components/visuallyhidden/index.page.mdx
@@ -1,6 +1,6 @@
 ---
 title: VisuallyHidden
-description: The VisuallyHidden primitive is used to visually hide content while leaving it available for screen readers.
+description: VisuallyHidden is used to visually hide content while leaving it available for screen readers.
 reactSource: packages/react/src/primitives/VisuallyHidden/VisuallyHidden.tsx
 supportedFrameworks: react
 ---
