Merge branch 'main' into input/url

packages/paste-website/src/pages/components/badge/index.mdx

@@ -137,26 +137,25 @@ It can be used in a wide variety of situations, such as labeling Beta product fe
 or an attribute such as “Inbound” or “Outbound”. A Badge can also be used to show a count,
 such as the number of new messages.
 
-A Badge should contain text content and can optionally contain an Icon.
-Text length should be kept short.
+A Badge should contain text content and can optionally contain an [Icon](/components/icon).
+Text length should be kept short, generally 1-3 words.
 
 ### Accessibility
 
-- Ensure that Badge text is clear enough to understand immediately without having to rely on color to communicate meaning.
-- For Status Badges, the inclusion of an icon is recommended to further reinforce the meaning.
+- Ensure that Badge text can be understood immediately, so the user does not have to rely on color to communicate meaning.
+- For Status Badges, it's recommended to include an icon to reinforce meaning.
 
 ## Examples
 
 ### Variants
 
-Badges variants such as `success` and `warning` should be used in cases where the Badge is intended to communicate a specific,
-semantic attribute, such as “warning” or “new”. These Badges should generally have an Icon that
+Use Badge variants such as `success` and `warning` when the Badge is intended to communicate a specific,
+semantic attribute, such as “warning” or “new”. These Badges should generally have an [Icon](/components/icon) that
 should be prefixed before the text.
 
 #### Neutral
 
-Use the Neutral Badge to highlight neutral attributes of an object. When using the Neutral Badge,
-the inclusion of an Information icon is optional.
+Use the neutral Badge to highlight neutral attributes of an object. An information icon is optional.
 
 <LivePreview scope={{Box, Badge, InformationIcon, ErrorIcon, WarningIcon, SuccessIcon, NewIcon}} language="jsx">
   {`<Box display="flex" columnGap="space80">
@@ -173,8 +172,7 @@ the inclusion of an Information icon is optional.
 
 #### Warning
 
-Use the Warning Badge to highlight attributes of an object that the user must be made aware of to avoid incurring an
-impending error. When using the Warning Badge, it is recommended that you include a Warning icon.
+Use the warning Badge to highlight attributes of an object that the user must be made aware of to avoid incurring an error. A warning icon is recommended.
 
 <LivePreview scope={{Box, Badge, InformationIcon, ErrorIcon, WarningIcon, SuccessIcon, NewIcon}} language="jsx">
   {`<Box display="flex" columnGap="space80">
@@ -191,10 +189,9 @@ impending error. When using the Warning Badge, it is recommended that you includ
 
 #### Error Badge
 
-Use the Error Badge to highlight attributes of an object that the user must be made aware of because they are considered
-to be in a bad or broken state and should be addressed. When using the Error Badge, it is recommended that you include an Error icon.
+Use the error Badge to highlight attributes of an object that signal to the user that they object is in bad or broken state. An error icon is recommended.
 
-Do not use an Error Badge unless there is additional guidance elsewhere on the page that explains to the user how to fix the broken state.
+Do not use an error Badge unless there is additional guidance elsewhere on the page that explains to the user how to fix the broken state.
 
 For additional guidance on how to compose error messages, refer to the [error state pattern](/patterns/error-state).
 
@@ -213,8 +210,8 @@ For additional guidance on how to compose error messages, refer to the [error st
 
 #### Success Badge
 
-Use the Success Badge to highlight attributes of an object that were completed or would be considered to be in a good
-state. When using the Success Badge, it is recommended that you include a Success icon.
+Use the success Badge to highlight attributes of an object that were completed or are considered to be in a good
+state. A success icon is recommended.
 
 <LivePreview scope={{Box, Badge, InformationIcon, ErrorIcon, WarningIcon, SuccessIcon, NewIcon}} language="jsx">
   {`<Box display="flex" columnGap="space80">
@@ -231,8 +228,7 @@ state. When using the Success Badge, it is recommended that you include a Succes
 
 #### New Badge
 
-Use the New Badge to highlight an object that is new, beta, pilot, or experimental.
-When using the New Badge, it is recommended that you include a New icon.
+Use the new Badge to highlight an object that is new, beta, pilot, or experimental. A new icon is recommended. 
 
 <LivePreview scope={{Box, Badge, InformationIcon, ErrorIcon, WarningIcon, SuccessIcon, NewIcon}} language="jsx">
   {`<Box display="flex" columnGap="space80">
@@ -249,8 +245,8 @@ When using the New Badge, it is recommended that you include a New icon.
 
 #### Subaccount Badge
 
-The Subaccount Badge is reserved for specific use cases only. Consult with the Console team before implementing this variant.
-When using the Subaccount Badge, it is recommended that you include a Users icon.
+The subaccount Badge is reserved for specific use cases only. Consult with the Console team before implementing this variant.
+A users icon is recommended.
 
 <LivePreview scope={{Box, Badge, UsersIcon}} language="jsx">
   {`<Box display="flex" columnGap="space80">
@@ -267,9 +263,8 @@ When using the Subaccount Badge, it is recommended that you include a Users icon
 
 ### Decorative
 
-Use Decorative Badges to highlight attributes that do not have a strictly semantic meaning (like warning, error, or success)
-but would benefit from the visual affordance of differently-colored Badges. Decorative Badges can have an optional Icon that,
-when used, should be prefixed before the text.
+Use the decorative Badge to highlight attributes that do not have a strictly semantic meaning (like warning, error, or success)
+but would benefit from the visual affordance of differently-colored Badges. Icons are optional, and should appear before the text.
 
 <LivePreview scope={{Box, Badge, SMSCapableIcon, MMSCapableIcon, VoiceCapableIcon, FaxCapableIcon}} language="jsx">
   {`<Box display="flex" columnGap="space80">
@@ -295,9 +290,9 @@ when used, should be prefixed before the text.
 
 ### Counter
 
-Counter Badges should be used to visually highlight a count in a UI.
+Use the counter Badge should be used to visually highlight a count in a UI.
 For example, the number of pending invitations or the number of errors.
-Counter Badges are limited to Neutral and Error variants, and the error variant will always include an error icon.
+Counter Badges are limited to Neutral and Error variants, and the error variant should always include an error icon.
 
 <LivePreview scope={{Box, Badge, InformationIcon, ErrorIcon, WarningIcon, SuccessIcon, NewIcon}} language="jsx">
   {`<Box display="flex" columnGap="space80">
@@ -328,7 +323,7 @@ To do so, add an `href` prop and set `as="a"` on the Badge.
 
 ### Badge with button functionality
 
-A Badge can also be used to trigger an in-page action, such as showing a Popover or Modal Dialog.
+A Badge can also be used to trigger an in-page action, such as showing a [Popover](/components/popover) or [Modal](/components/modal).
 To do so, provide an `onClick` event handler and set `as="button"` on the Badge.
 Refer to the [PopoverBadgeButton](/components/popover/#popoverbadgebutton) section
 of the Popover docs to add a Popover to a Badge.
@@ -359,7 +354,7 @@ of the Popover docs to add a Popover to a Badge.
 
 ### Small Badges
 
-Use small Badges sparingly, only when needed for vertical density. Guidelines for using variants in small Badge are the same as in their default size.
+Use a small Badge only when vertical density is a concern. The guidelines for using variants in a small Badge are the same as in their default size.
 
 <LivePreview scope={{Box, Badge, InformationIcon, ErrorIcon, WarningIcon, SuccessIcon, NewIcon}} language="jsx">
   {`<Box display="flex" columnGap="space40" rowGap="space60" flexWrap="wrap">
@@ -387,11 +382,15 @@ Use small Badges sparingly, only when needed for vertical density. Guidelines fo
 
 ---
 
-## Composition Notes
+## Composition notes
 
 Use a Badge when you want to add a label to a piece of UI for quick identification and navigation.
 
-Badge labels should be one to three words, or numbers.
+Badge labels should be 1-3 words and ideally less than 20 characters. Badge labels can also be numbers. 
+
+Use sentence case for Badge labels. Do not wrap Badge text to more than one line.
+
+Use the same grammatical construction for a set of Badges. For example, if a set of Badges highlights statuses, make each Badge an adjective. 
 
 ### Use cases
 
@@ -477,7 +476,7 @@ Badge labels should be one to three words, or numbers.
 
 ---
 
-### Do &amp; Don't
+### Do and don't
 
 <DoDont>
   <Do title="Do" body="Use Badge to highlight an attribute of an object for quick identification.">
@@ -499,7 +498,7 @@ Badge labels should be one to three words, or numbers.
 </DoDont>
 
 <DoDont>
-  <Do title="Do" body="Use 1-3 words as Badge text.">
+  <Do title="Do" body="Use 1-3 words and sentence case for Badge text.">
     <Box alignItems="center" display="flex" justifyContent="space-around" height="100%" paddingX="space60">
       <Badge variant="new" as="span">
         <NewIcon title="New Badge component" size="sizeIcon10" />

packages/paste-website/src/pages/components/breadcrumb/index.mdx

@@ -65,7 +65,7 @@ export const getStaticProps = async () => {
 
 Breadcrumb navigation helps the user understand their location in an app or website by providing a trail back to the top level of the website.
 
-Breadcrumbs are listed in order and represent the hierarchy of the page in the product. They will include links to parent pages and can optionally show the current page.
+Breadcrumbs are listed in order and represent the hierarchy of the page in the product. Do not include the current page in the hierarchy unless there is no page header on the current page. 
 
 <Callout variant="warning" marginY="space70">
   <CalloutHeading as="h4">Using Breadcrumb in Console products</CalloutHeading>
@@ -99,7 +99,9 @@ The Breadcrumb component uses [Anchors](/components/anchor) to link back to pare
 
 ### Breadcrumb with unlinked page
 
-Use a Breadcrumb with an unlinked page when there's a parent page that customers can't return to, but showing the navigation hierarchy of the current page still helps a customer with their workflow. However this should **not** be used to show the current page, especially if there is a visible page heading directly below the Breadcrumb.
+Always show the full IA hierarchy of the current page, even if one of the parent pages cannot be navigated to. When a parent page cannot be navigated to, use an unlinked Breadcrumb. 
+
+Do not use an unlinked Breadcrumb to display the name of the current page in the Breadcrumb. The current page's header provides a clearer indication to the user of where they are in the product.
 
 To show an unlinked page, use a `BreadcrumbItem` with no `href`.
 
@@ -156,7 +158,13 @@ our BreadcrumbItem component creates links using [Anchor](/components/anchor) un
 
 ---
 
-## When to use Breadcrumb
+## Composition notes
+
+Keep breadcrumb text short, ideally less than 15 characters. When the linked page has a longer title, follow [the truncation guidance](#breadcrumb-with-truncation).
+
+Do not include the current page in the navigation, since the page header provides a clearer indication to the user of where they are in the product.
+
+## Do and don't
 
 <DoDont>
   <Do title="Do" body="Add a slash between two BreadcrumbItems." center>
@@ -183,7 +191,7 @@ our BreadcrumbItem component creates links using [Anchor](/components/anchor) un
   </Do>
   <Dont
     title="Don't"
-    body="Avoid using an unlinked BreadcrumbItem, especially if there's already a visible heading on the page. Exceptions can be made when there are parent pages that customers can't return to, but still need to actively reference."
+    body="Do not include the current page in the navigation trail, unless the current page doesn't have a header."
     center
   >
     <Breadcrumb>

packages/paste-website/src/pages/components/card/index.mdx

@@ -72,16 +72,13 @@ export const getStaticProps = async () => {
 
 ### About Cards
 
-Cards are specifically-styled containers that group relatable content and actions. Card is an extremely
-flexible container that does not require specific components inside of it. You can compose a Card to support your use case,
-but elements such as [Heading](/components/heading), [Paragraph](/components/paragraph), and [Button](/components/button) or [Anchor](/components/anchor) are commonly used.
-See [When to use a Card](#when-to-use-a-card) and [Examples](#examples) for common Card patterns and dos/donts.
+Cards are specifically-styled containers that group related content and actions. Cards are a great tool for placing a concise amount of related information together in one object, much like a business card or baseball card in real life.
 
-A Card does not handle any interactive events such as hover, click, or focus, though children
-composed inside of it may commonly have event handlers.
+Card is an extremely flexible container that does not require specific components inside of it. You can compose a Card to support your use case, but elements such as [Heading](/components/heading), [Paragraph](/components/paragraph), and [Button](/components/button) or [Anchor](/components/anchor) are commonly used.
 
-Acknowledging the flexibility of Card component, there are several [non-negotiable properties](#anatomy)
-of a Card that differentiate it from a more basic page-layout element, such as [Box](/primitives/box) including background color, border width, border radius, and border color.
+A Card does not handle any interactive events such as hover, click, or focus, though children composed inside of it may commonly have event handlers.
+
+Acknowledging the flexibility of Card component, there are several [non-negotiable properties](#anatomy) of a Card that differentiate it from a more basic page-layout element, such as [Box](/primitives/box) including background color, border width, border radius, and border color.
 
 ### Card vs. Box
 
@@ -166,15 +163,15 @@ Card using Box or Flex.
 </Card>;`}
 </LivePreview>
 
-## Composing a Card
-
-### When to use a Card
+## Composition notes
 
-Cards are a great tool for relating a concise amount of related information together in one object, much like a business card or baseball card in real life.
+When a Card contains text content, use the following guidelines:
 
-For example, you might use a single Card as a summary for a feature whose call to action encourages a user to dive deeper. Alternatively, multiple Cards on a single page with hierarchy of equal weights could be used to highlight multiple choices or paths a user can take.
+- Use a [Heading](/components/heading) to highlight the most important information.
+- Use a [Paragraph](/components/paragraph) to add additional context. Do not repeat the information in the header. Front-load the most critical information.
+- When presenting multiple Cards of equal weight on a single page, structure each Card's content similarly.
 
-Ultimately, Card is a very flexible component that can fit a variety of needs. If you feel that you have a unique use case or are limited by the Card implementation, please visit Design System Office Hours to see how we can help address your needs.
+## Do and don't
 
 <DoDont>
   <Do

packages/paste-website/src/pages/components/checkbox/index.mdx

@@ -318,16 +318,18 @@ If the selected options don't pass the group validation requirements, display an
 
 ## Composition notes
 
-### Checkbox labels, legends and help text
+### Checkbox labels, legends, and help text
 
-Checkboxes and checkbox groups must have a visible label.
+Checkboxes and Checkbox Groups must have a visible label.
+- Aim for no more than 3 words. If the label must be longer and space is limited, wrap the label. 
+- Structure each checkbox label similarly. For example, make each checkbox a noun.
+- Avoid articles ("a", "the") and punctuation. For example, use "SIM registration code" rather than "The SIM registration code".
 
-Use concise, descriptive language to describe the requested value or group.
+Checkbox labels should reflect what happens if the box is checked. Avoid situations where the user must check a box to negate something. For example, "Don't send message."
 
-- Use help text to provide additional context about the option if needed.
-- Avoid articles ("a", "the") and punctuation. For example, use "SIM registration code" rather than "The SIM registration code".
+Avoid constructing the legend and label text to read as a sentence. 
 
-Use [Help Text](/components/help-text) to give additional context and provide enough information to avoid errors.
+Use [Help Text](/components/help-text) to give additional context and provide enough information to avoid errors. Consider using Help Text to indicate to users that they can select multiple options. Limit Help Text to 1-2 sentences.
 
 To support internationalization, avoid starting a sentence with the legend and using the field to finish it since sentence structures vary across languages. For example, use "Phone Number capabilities", not "Phone Number capabilities include:".
 
@@ -337,11 +339,7 @@ Validate form fields on form submission. Don't validate each item in a group, tr
 
 Use inline error text to explain how to fix an error. Because space is typically limited, focus the error text on how users can fix the issue. For additional guidance on how to compose error messages, refer to the [error state pattern](/patterns/error-state).
 
-## When to use a Checkbox and Checkbox Group
-
-Use a checkbox when users are required to make a binary choice. Use a checkbox group when more than one checkbox is related to one another.
-
-There is no maximum number of checkboxes you can have in a group, but consider using another component when you have more than 6 options. Some alternatives might be a [Select](https://paste.twilio.design/components/select/) or [Combobox](https://paste.twilio.design/components/combobox/).
+## Do and don't
 
 <DoDont>
   <Do title="Do" body="Use checkboxes to enable multiple choice." />

packages/paste-website/src/pages/components/disclosure/index.mdx

@@ -320,9 +320,7 @@ Each Disclosure can be disabled by setting the `disabled` prop on the `Disclosur
 
 ## Composition notes
 
-Both `DisclosureHeading` and `DisclosureContent` accept any child component, leaving flexibility to create a large number of custom compositions for your product needs.
-
-The only thing you **must not** do is place a focusable element inside the `DisclosureHeading`, see [accessibility notes](/components/disclosure#accessibility).
+Both `DisclosureHeading` and `DisclosureContent` accept any child component. However, [avoid placing a focusable element inside the `DisclosureHeading`](/components/disclosure#accessibility).
 
 <LivePreview
   scope={{
@@ -348,6 +346,10 @@ The only thing you **must not** do is place a focusable element inside the `Disc
 </Disclosure>`}
 </LivePreview>
 
+Disclosure headers should be short, no more than 1 line, and prioritize the user goal. Use sentence case for the headers.
+
+Any content contained within a disclosure can be formatted into multiple paragraphs with sub-headers, if needed.
+
 Disclosures with an error icon in the header must include additional information on the nature of the error and how the user can fix it within the disclosure content. For additional guidance on how to compose error messages, refer to the [error state pattern](/patterns/error-state).
 
 <LivePreview