Docs: Updated Status docs to include design guidelines (#1940)

docs/pages/status.js

@@ -43,7 +43,65 @@ export default function SearchFieldPage({ generatedDocGen }: {| generatedDocGen:
           />
         </MainSection.Subsection>
       </MainSection>
+      <MainSection name="Best practices">
+        <MainSection.Subsection columns={2}>
+          <MainSection.Card
+            cardSize="md"
+            type="do"
+            description="Use Status to communicate a step in a workflow or the state of an item."
+            defaultCode={`
+<Status type="ok" accessibilityLabel="This item is ok" />
+`}
+          />
+          <MainSection.Card
+            cardSize="md"
+            type="don't"
+            description="Use SVGs or images that resemble the Status’ symbols to denote status."
+            defaultCode={`
+<Icon icon="workflow-status-problem" size="24" accessibilityLabel="This item has an error" />
+`}
+          />
+          <MainSection.Card
+            cardSize="md"
+            type="do"
+            description="Place Status close to its subject to provide context and reference. It can be placed as an inline element or paired side by side as needed."
+            defaultCode={`
+<Flex gap={1} alignItems="center">
+  <Status accessibilityLabel="This item is complete" type="ok" />
+  <Text weight="bold" size="300">Campaign complete</Text>
+</Flex>
+`}
+          />
+          <MainSection.Card
+            cardSize="md"
+            type="don't"
+            description="Place Status far away from its subject. "
+            defaultCode={`
+<Flex gap={12} direction="column" alignItems="center">
+  <Status accessibilityLabel="This item is paused" type="halted" />
+  <Text weight="bold" size="300">Campaign paused</Text>
+</Flex>
 
+`}
+          />
+          <MainSection.Card
+            cardSize="md"
+            type="do"
+            description="Use `title` when the status it represents is unique, specific and critical for the user to know."
+            defaultCode={`
+<Status type="inProgress" title="Pending review" />
+`}
+          />
+          <MainSection.Card
+            cardSize="md"
+            type="don't"
+            description="Use Status' `subText` to display extraneous messaging."
+            defaultCode={`
+<Status type="problem" title="Error" subtext="Please try again" />
+`}
+          />
+        </MainSection.Subsection>
+      </MainSection>
       <MainSection
         name="Accessibility"
         description="Icons are a great way to help users who have difficulties with reading, focus attention, and low vision impairments. For such use cases, Status can be used without accompanying `title` text."
@@ -54,7 +112,7 @@ export default function SearchFieldPage({ generatedDocGen }: {| generatedDocGen:
           description={`
 If Status appears without \`title\` text, \`accessibilityLabel\` should be used to provide a text description for screen readers to announce and communicate the represented icon, as shown in the first example.
 
-Avoid using the generic words like  "image" or "icon"; instead, use verbs that describe the meaning of the icon, for example: "there is a problem with this item".
+Avoid using the generic words like "image" or "icon"; instead, use verbs that describe the meaning of the icon, for example: "Upload in progress".
 
 If using \`title\` to describe what the icon represents, \`accessibilityLabel\` does not need to be provided, as shown in the second example.
 `}
@@ -111,6 +169,20 @@ If using \`title\` to describe what the icon represents, \`accessibilityLabel\`
           />
         </MainSection.Subsection>
       </MainSection>
+      <MainSection name="Related">
+        <MainSection.Subsection
+          description={`
+**[Icon](/icon)**
+Icon should be used to display a symbol that does not represent the state or status of an item.
+
+**[Badge](/badge)**
+Use Badge to label or mark an item with a designation or category.
+
+**[Callout](/callout)**
+Use Callout to communicate page-level status, such as an error, and to provide actionable next steps.
+    `}
+        />
+      </MainSection>
     </Page>
   );
 }

packages/gestalt/src/Status.js

@@ -58,7 +58,7 @@ type Props = {|
 |};
 
 /**
- * [Status](https://gestalt.pinterest.systems/status) is an indicator with an icon that provides information to a user.
+ * [Status](https://gestalt.pinterest.systems/status) is a graphic indicator of an element’s state.
  */
 export default function Status({ accessibilityLabel, subtext, title, type }: Props): Node {
   const { icon, color } = ICON_COLOR_MAP[type];