Merge branch 'master' into docs--component-content-updates-#3

src/pages/components/data-table/usage.mdx

@@ -4,6 +4,20 @@ description: The data table component allows for the flexible display and sortin
 tabs: ["Usage", "Style", "Code", "Accessibility"]
 ---
 
+<PageDescription>
+
+Data tables are used to organize and display data efficiently. The data table component allows for customization with additional functionality, as needed by your product's users.
+
+</PageDescription>
+
+<AnchorLinks>
+
+<AnchorLink>Basic data table</AnchorLink>
+<AnchorLink>Additional functionality</AnchorLink>
+<AnchorLink>Feedback</AnchorLink>
+
+</AnchorLinks>
+
 import { rowData, headerData } from "../../../data/components/data-table.js";
 import {
   Delete16 as Delete,
@@ -403,4 +417,8 @@ By default, the expand-all chevron is not shown. Keeping detailed information in
 
 </div>
 
-<Caption>Expandabling all rows with skeleton states</Caption>
+<Caption>Expanding all rows with skeleton states</Caption>
+
+## Feedback
+
+Help us improve this component by providing feedback, asking questions, and leaving any other comments on [GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md).

src/pages/components/date-picker/usage.mdx

@@ -16,6 +16,7 @@ Date and time pickers allow users to select a single or a range of dates and tim
 <AnchorLink>Content</AnchorLink>
 <AnchorLink>Interaction</AnchorLink>
 <AnchorLink>Time picker</AnchorLink>
+<AnchorLink>Feedback</AnchorLink>
 
 </AnchorLinks>
 
@@ -157,3 +158,7 @@ The simple date picker provides the user with a text input in which they can inp
 ## Time picker
 
 Time pickers provide the user with a text input in which they can input hours/minutes. Additionally, they can be accompanied by an “AM/PM” selection and a time zone selection, which is styled as an [inline select](/components/select/usage).
+
+## Feedback
+
+Help us improve this component by providing feedback, asking questions, and leaving any other comments on [GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md).

src/pages/components/dropdown/usage.mdx

@@ -4,12 +4,19 @@ description: Dropdowns present a list of options that can be used to filter or s
 tabs: ["Usage", "Style", "Code", "Accessibility"]
 ---
 
+<PageDescription>
+
+Dropdowns present a list of options that can be used to filter or sort existing content.
+
+</PageDescription>
+
 <AnchorLinks>
 
 <AnchorLink>General guidance</AnchorLink>
 <AnchorLink>Variations</AnchorLink>
 <AnchorLink>Content</AnchorLink>
 <AnchorLink>Interaction</AnchorLink>
+<AnchorLink>Feedback</AnchorLink>
 
 </AnchorLinks>
 
@@ -246,3 +253,7 @@ This variation of dropdown follows the same interaction patterns described above
 
 </Column>
 </Row>
+
+## Feedback
+
+Help us improve this component by providing feedback, asking questions, and leaving any other comments on [GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md).

src/pages/components/file-uploader/usage.mdx

@@ -4,12 +4,19 @@ description: File uploaders allow the user to transfer a file or submit content
 tabs: ["Usage", "Style", "Code", "Accessibility"]
 ---
 
+<PageDescription>
+
+The file uploader allows a user to transfer a file or submit content of their own.
+
+</PageDescription>
+
 <AnchorLinks>
 
 <AnchorLink>General guidance </AnchorLink>
 <AnchorLink>Interaction</AnchorLink>
 <AnchorLink>Upload state</AnchorLink>
 <AnchorLink>Removing files</AnchorLink>
+<AnchorLink>Feedback</AnchorLink>
 
 </AnchorLinks>
 
@@ -158,3 +165,7 @@ Developers using file uploader will be able to use JavaScript to inject a Loadin
 ## Removing files
 
 Developers will use JavaScript to inject a “close” button on each file that is selected to be uploaded. It's up to the developer to code the logic for removing these files individually. However, keep in mind that this kind of editing isn't supported natively in the browser.
+
+## Feedback
+
+Help us improve this component by providing feedback, asking questions, and leaving any other comments on [GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md).

src/pages/components/form/usage.mdx

@@ -4,12 +4,19 @@ description: Forms are used for submitting data. Consider each field and what va
 tabs: ["Usage", "Style", "Code", "Accessibility"]
 ---
 
+<PageDescription>
+
+A form is a group of related input controls that allows users to provide data or configure options.
+
+</PageDescription>
+
 <AnchorLinks>
 
 <AnchorLink>General guidance </AnchorLink>
 <AnchorLink>Format</AnchorLink>
 <AnchorLink>Form logic</AnchorLink>
 <AnchorLink>Validation and errors</AnchorLink>
+<AnchorLink>Feedback</AnchorLink>
 
 </AnchorLinks>
 
@@ -239,3 +246,7 @@ All fields in a form are assumed required, with optional fields being tagged as
 
 </Column>
 </Row>
+
+## Feedback
+
+Help us improve this component by providing feedback, asking questions, and leaving any other comments on [GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md).

src/pages/components/inline-loading/usage.mdx

@@ -4,6 +4,12 @@ description: The inline loading component provides visual feedback that a user's
 tabs: ["Usage", "Style", "Code", "Accessibility"]
 ---
 
+<PageDescription>
+
+The inline loading component provides visual feedback that a user's action is being processed.
+
+</PageDescription>
+
 <AnchorLinks>
 
 <AnchorLink>General guidance</AnchorLink>
@@ -44,7 +50,7 @@ tabs: ["Usage", "Style", "Code", "Accessibility"]
 
 Inline loading spinners are used when performing actions. They notify to the user that their request is being processed. Although they do not provide details about what is occurring on the back-end, they reassure the user that their action is being processed.
 
-It is best practice to use an Inline loading component for any Create, Update, or Delete actions. The component provides feedback to the user about the progress of the action they took. This could be in a table, after a primary or secondary button click, or even in a modal.
+Use an inline loading component for any Create, Update, or Delete actions. It can be used in a table, after a primary or secondary button click, or even in a modal.
 
 ## Format
 

src/pages/components/link/usage.mdx

@@ -1,9 +1,28 @@
 ---
 title: Link
-description: Links are used primarily as a navigational element. Links may also change what or how data is displayed.
+description: Links are used as navigational elements. They may appear on their own, within a sentence or paragraph, or directly following the content.
 tabs: ["Usage", "Style", "Code", "Accessibility"]
 ---
 
+<PageDescription>
+
+Links are used as navigational elements. They may appear on their own, within a sentence or paragraph, or directly following the content.
+
+</PageDescription>
+
+<AnchorLinks>
+
+<AnchorLink>Overview</AnchorLink>
+<AnchorLink>Formatting</AnchorLink>
+<AnchorLink>Content</AnchorLink>
+<AnchorLink>Behaviors</AnchorLink>
+<AnchorLink>Link types</AnchorLink>
+<AnchorLink>Modifiers</AnchorLink>
+<AnchorLink>Related</AnchorLink>
+<AnchorLink>Feedback</AnchorLink>
+
+</AnchorLinks>
+
 <ComponentDemo
   components={[
     {
@@ -28,14 +47,118 @@ tabs: ["Usage", "Style", "Code", "Accessibility"]
   `}</ComponentVariant>
 </ComponentDemo>
 
-## General guidance
+## Overview
+
+Links are used as navigational elements and can be used on their own or inline with text. They provide a lightweight option for navigation but like other interactive elements, too many links will clutter a page and make it difficult for users to identify their next steps. This is especially true for inline links, which should be used sparingly.
+
+### When to use
+
+Use links when you want users to:
+
+- Navigate to a different page within the application
+- Navigate to an entirely different site
+- Jump to an element on the same page
+- Link to emails or phone numbers
+
+### When not to use
+
+Use a button instead of a link for actions that will change data or manipulate how it is displayed, change a state, or trigger an action. Buttons should never be used for navigational actions.
+
+### Types
+
+| Type                           | Usage                                                                                                                                                            |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Standalone](#standalone-link) | These links are the default link type. They are used on their own or directly following content and they do not use underlines. They can be paired with an icon. |
+| [Inline](#inline-link)         | Inline links are used within a sentence or paragraph and are styled with an underline. They should not be paired with an icon.                                   |
 
-_Links_ are used primarily as a navigational element. Links may also change what or how data is displayed (i.e., view more, show all). If the action taken by the user will change or manipulate data, use a [button](/components/button/usage).
+## Formatting
+
+### Anatomy
+
+<Row>
+<Column colLg={8}>
+
+![link anatomy image](images/01_link_anatomy_608.png)
+
+</Column>
+</Row>
+
+1. **Label:** Communicates what is being linked to.
 
 ## Content
 
-- Use text for links rather than graphics or icons.
-- Links should be three words or less.
-- Text should be consistent with the title of the intended destination.
-- Use caution with links that are several words long. It is recommended that links are long enough to be understood by the user, but short enough to prevent text wrapping.
-- Avoid the term “click here,” other links to “here,” or the web address itself. Instead, use a meaningful descriptive label for the link, and match the destination site name.
+We recommend links be three words or fewer. Because links take users to a new location, it is important that their labels accurately reflect the content users will find at the link destination. Use meaningful labels for links and avoid terms like "click here" or the web address itself.
+
+Links need to be clear enough to be understood by the user, but should not be so long that the text wraps unless used inline.
+
+For further content guidance, see Carbon's [content guidelines](/guidelines/content/action-labels).
+
+## Behaviors
+
+### Interactions
+
+#### Mouse
+
+Users can open a link by clicking anywhere along the link text or on the associated icon.
+
+#### Keyboard
+
+Users can open a link by pressing `Enter` while the link has focus. For additional keyboard interactions, see the Accessibility tab.
+
+#### Screen readers
+
+VoiceOver: Users can open a link by pressing `Control-Option-Space` or `Enter`.
+
+JAWS: Users can open a link by pressing `Enter`.
+
+NVDA: Users can open a link by pressing `Enter`.
+
+For additional information, see [screen reader tests](accessibility/#macos-screen-reader-tests).
+
+## Link types
+
+### Standalone link
+
+Standalone links are used on their own directly following content. They should not be used within sentences or paragraphs. Standalone links are the default link style for Carbon and only have an underline in the hover state.
+
+The standalone link component can be paired with an icon. Use 16px icons and place them to the right of the link. Icons should always be the same color as the link text.
+
+<Row>
+<Column colLg={8}>
+
+![link with icon example](images/02_link_icon_608.png)
+
+</Column>
+</Row>
+
+### Inline link
+
+Inline links are used in sentences or paragraphs of text. The inline link behaves the same as the standalone link but it is styled with an underline. This helps differentiate them from the text they are placed next to and makes it clear users can interact with them.
+
+Inline links should not be used on their own and should not be paired with icons.
+
+<Row>
+<Column colLg={8}>
+
+![inline link example](images/03_link_inline_608.png)
+
+</Column>
+</Row>
+
+## Modifiers
+
+### Visited style
+
+By default, the link component does not use a visited style. Visited links indicate that a user has already opened the link so they can be a helpful indicator during task completion. Visited styles should be used sparingly because they often clutter the the page and add further visual noise as users are trying to navigate a product. They can be used if it is important that a user knows they have already clicked on a link.
+
+### Links that trigger actions
+
+Some links trigger actions to aid task completion in addition to navigation. These links should still serve a navigation purpose. A common example is linking phone numbers so clicking the website automatically opens and calls the phone number when clicked. The label and any accompanying icons should make it clear what action will be triggered and where the user will be directed.
+
+## Related
+
+- [Button component](https://www.carbondesignsystem.com/components/button/usage/)
+
+## Feedback
+
+Help us improve this component by providing feedback, asking questions, and leaving any other comments on [GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md).

src/pages/get-started/design/sketch.mdx

@@ -34,7 +34,7 @@ There are [four Carbon themes](/guidelines/color/overview#themes), two light (Wh
     <ResourceCard
       onClick={() => fathom("trackGoal", "P0OEN9TS", 0)}
       subTitle="Get the White theme"
-      href="sketch://add-library/cloud/JaVzz"
+      href="sketch://add-library/cloud/557b75ff-67d3-41ab-ada5-fa25447218c1"
     >
       <MdxIcon name="sketch" />
     </ResourceCard>
@@ -43,7 +43,7 @@ There are [four Carbon themes](/guidelines/color/overview#themes), two light (Wh
     <ResourceCard
       onClick={() => fathom("trackGoal", "T7D1HJ3L", 0)}
       subTitle="Get the Gray 10 theme"
-      href="sketch://add-library/cloud/Onwv2"
+      href="sketch://add-library/cloud/b4ea2a21-4b1a-4c64-99dc-a1365eff5d5f"
     >
       <MdxIcon name="sketch" />
     </ResourceCard>
@@ -52,7 +52,7 @@ There are [four Carbon themes](/guidelines/color/overview#themes), two light (Wh
     <ResourceCard
       onClick={() => fathom("trackGoal", "LYFJTPDE", 0)}
       subTitle="Get the Gray 90 theme"
-      href="sketch://add-library/cloud/eo37p"
+      href="sketch://add-library/cloud/a324c6dd-df97-435e-b79f-3a29e04922fc"
     >
       <MdxIcon name="sketch" />
     </ResourceCard>
@@ -61,7 +61,7 @@ There are [four Carbon themes](/guidelines/color/overview#themes), two light (Wh
     <ResourceCard
       onClick={() => fathom("trackGoal", "3XH0SIBJ", 0)}
       subTitle="Get the Gray 100 theme"
-      href="sketch://add-library/cloud/d13Ll"
+      href="sketch://add-library/cloud/9d47a4fd-70dd-44ff-bc57-22c79da8e477"
     >
       <MdxIcon name="sketch" />
     </ResourceCard>
@@ -113,15 +113,15 @@ Visit the [Sketch library](https://sketch.cloud/s/ngV7z) page and choose `Downlo
   <Column colLg={4} colMd={4} noGutterSm>
     <ResourceCard
       subTitle="Download the IBM Grid template"
-      href="https://sketch.cloud/s/ngV7z"
+      href="https://client.sketch.cloud/v1/documents/17f9be17-44ed-4553-be2b-350043b5f1b2/download/IBM+Grid+template.sketch?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZGVudCI6IjE3ZjliZTE3LTQ0ZWQtNDU1My1iZTJiLTM1MDA0M2I1ZjFiMiIsImF1ZCI6Ikpva2VuIiwiZXhwIjoxNTg4OTYwOTUzLCJpYXQiOjE1ODg5NTczNTMsImlzcyI6Ikpva2VuIiwianRpIjoiMm82aG9pcWRqMWZqZzBqM244ZWhyazUxIiwibmJmIjoxNTg4OTU3MzUzfQ.o-TfVs6DWYBx0V2U69cPTUafPqE8U4Oj2K7lTSKi96A"
     >
       <MdxIcon name="sketch" />
     </ResourceCard>
   </Column>
   <Column colLg={4} colMd={4} noGutterSm>
     <ResourceCard
       subTitle="Download the UI Shell template"
-      href="https://sketch.cloud/s/EjVmA"
+      href="https://client.sketch.cloud/v1/documents/6f9f95b5-eebf-4a66-a4ad-e84c42f88c3c/download/UI+Shell+templates.sketch?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZGVudCI6IjZmOWY5NWI1LWVlYmYtNGE2Ni1hNGFkLWU4NGM0MmY4OGMzYyIsImF1ZCI6Ikpva2VuIiwiZXhwIjoxNTg4OTYxMTMwLCJpYXQiOjE1ODg5NTc1MzAsImlzcyI6Ikpva2VuIiwianRpIjoiMm82aG90NG84YTZtM2ZxaG5nZDBzNjU1IiwibmJmIjoxNTg4OTU3NTMwfQ.kD4u_gOx15zGMpHiqcM5eekPzzKKa6nVZrrqB9yW02Y"
     >
       <MdxIcon name="sketch" />
     </ResourceCard>