chore: add error state guidance to docs site (#3123)

* chore: create error state pattern page

* chore: remove unnecessary imports

* chore: add tables and examples

* fix: copy paste error

* chore: megans feedback

* chore: update to markdown

* chore: update component pages

* chore: feedback from megan

* chore: add component examples

* chore: capitalize combobox

* chore: saras feedback

* chore: add ingredients

* chore: try a thing

---------

Co-authored-by: Si Taggart <me@simontaggart.com>

.github/workflows/on_merge_to_main.yml

@@ -52,7 +52,7 @@ jobs:
         run: yarn install --immutable
 
       - name: Run prerelease
-        run: yarn prerelease --base=origin/main
+        run: yarn prerelease
         env:
           NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN }}
 
@@ -117,7 +117,7 @@ jobs:
         run: yarn install --immutable
 
       - name: Build packages
-        run: yarn build --base=origin/main~1
+        run: yarn build
         env:
           NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN }}
 

.github/workflows/on_pull_request.yml

@@ -51,10 +51,10 @@ jobs:
         run: yarn install --immutable
 
       - name: Build packages
-        run: yarn build --base=origin/main
+        run: yarn build
 
       - name: Run type checker
-        run: yarn type-check --base=origin/main
+        run: yarn type-check
 
   eslint:
     name: Lint repository
@@ -99,7 +99,7 @@ jobs:
         run: yarn install --immutable
 
       - name: Build packages
-        run: yarn build --base=origin/main
+        run: yarn build
         env:
           NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN }}
 
@@ -149,7 +149,7 @@ jobs:
         run: yarn install --immutable
 
       - name: Build packages
-        run: yarn build --base=origin/main
+        run: yarn build
         env:
           NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN }}
 
@@ -192,7 +192,7 @@ jobs:
 
       # Note: Build first before we change the react version installed.
       - name: Build packages
-        run: yarn build --base=origin/main
+        run: yarn build
         env:
           NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN }}
 
@@ -243,7 +243,7 @@ jobs:
 
       # Note: Build first before we change the react version installed.
       - name: Build packages
-        run: yarn build --base=origin/main
+        run: yarn build
         env:
           NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN }}
 
@@ -315,7 +315,7 @@ jobs:
         run: yarn install --immutable
 
       - name: Build packages
-        run: yarn build --base=origin/main
+        run: yarn build
         env:
           NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN }}
 
@@ -369,7 +369,7 @@ jobs:
         run: yarn install --immutable
 
       - name: Build packages
-        run: yarn build --base=origin/main
+        run: yarn build
         env:
           NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN }}
 
@@ -421,7 +421,7 @@ jobs:
         run: yarn install --immutable
 
       - name: Build packages
-        run: yarn build --base=origin/main
+        run: yarn build
         env:
           NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN }}
 

.github/workflows/on_pull_request_package_size.yml

@@ -22,7 +22,7 @@ jobs:
       - uses: zahnster/compressed-size-action@2.4.2
         with:
           repo-token: "${{ secrets.GITHUB_TOKEN }}"
-          build-script: "build:js --base=origin/main"
+          build-script: "build:js"
           # only do common js files, no need to double count files
           pattern: "{**/dist/**/*.js,./packages/paste-icons/cjs/**/*.js}"
           exclude: "{**/*.map,**/node_modules/**,**/*.es.js,**/*.es6.js,**/*.debug.js,**/*.debug.es.js}"

cypress/integration/sitemap-vrt/constants.ts

@@ -111,6 +111,7 @@ export const SITEMAP = [
   '/patterns/filter-group/',
   '/patterns/',
   '/patterns/empty-state/',
+  '/patterns/error-state/',
   '/patterns/notifications-and-feedback/',
   '/patterns/object-details/',
   '/patterns/privacy/',

package.json

@@ -30,8 +30,8 @@
     "start:nextjs-template": "yarn workspace @twilio-paste/nextjs-template dev",
     "start:contrast-checking": "concurrently \"yarn:start:tokens\" \"yarn:start:token-contrast-checker\"",
     "prebuild": "ts-node ./tools/build/pre-build.ts && yarn packages:check",
-    "build": "yarn prebuild && yarn nx affected --parallel --target=build --exclude @twilio-paste/website @twilio-paste/theme-designer @twilio-paste/nextjs-template @twilio-paste/token-contrast-checker",
-    "build:js": "yarn prebuild && yarn nx affected --parallel --target=build:js --exclude @twilio-paste/website @twilio-paste/theme-designer",
+    "build": "yarn prebuild && yarn nx run-many --target=build --exclude @twilio-paste/website @twilio-paste/theme-designer @twilio-paste/nextjs-template @twilio-paste/token-contrast-checker",
+    "build:js": "yarn prebuild && yarn nx run-many --target=build:js --exclude @twilio-paste/website @twilio-paste/theme-designer",
     "build:core": "yarn nx run @twilio-paste/core:build",
     "build:codemods": "yarn nx run @twilio-paste/codemods:build",
     "build:tokens": "yarn nx run @twilio-paste/design-tokens:tokens",
@@ -71,7 +71,7 @@
     "lint:nextjs-template": "eslint -c ./packages/paste-nextjs-template/.eslintrc.json --ext .tsx,.ts ./packages/paste-nextjs-template",
     "lint:vscode-intellisense": "eslint -c ./apps/vs-code-intellisense/.eslintrc.json --ext .tsx,.ts ./apps/vs-code-intellisense",
     "lint:repo": "eslint -c .eslintrc.repo.js --ext .tsx,.ts .",
-    "type-check": "yarn nx affected --parallel --target=tsc",
+    "type-check": "yarn nx run-many --target=tsc",
     "tsc": "echo 'Did you mean to run yarn type-check?'",
     "chromatic": "chromatic",
     "packages:check": "manypkg check && monopeers check",

packages/paste-website/src/component-examples/FormExamples.ts

@@ -297,7 +297,7 @@ const FormExample = () => {
       </Heading>
       <Callout variant="error">
         <CalloutHeading as="h4">
-          Please fix the issues with these fields
+          These fields are missing values:
         </CalloutHeading>
         <CalloutList as="ul">
           <CalloutListItem>Street address</CalloutListItem>
@@ -317,7 +317,7 @@ const FormExample = () => {
           aria-describedby={seed('street-address-error')}
         />
         <HelpText variant="error" id={seed('street-address-error')}>
-          Please add a valid street address.
+          Enter a street address.
         </HelpText>
       </FormControl>
       <FormControlTwoColumn>
@@ -337,7 +337,7 @@ const FormExample = () => {
           </Label>
           <Input id={seed('zip')} aria-describedby={seed('zip-error')} type="text" hasError required />
           <HelpText variant="error" id={seed('zip-error')}>
-            Please add a valid zip code.
+            Enter a zip code.
           </HelpText>
         </FormControl>
       </FormControlTwoColumn>
@@ -354,7 +354,7 @@ const FormExample = () => {
           value="email@xyz.yxz"
         />
         <HelpText variant="error" id={seed('email-error')}>
-          Please add a valid email address.
+          Enter an email address.
         </HelpText>
       </FormControl>
       <FormActions>

packages/paste-website/src/component-examples/RadioButtonGroupExamples.ts

@@ -30,8 +30,8 @@ export const ErrorExample = `const RadioButtonGroupExample = () => {
       attached
       name="foo"
       legend="What is your preferred programming language?"
-      errorText="Choose a programming language"
-      helpText="Choose the language with which you are most familiar"
+      errorText="Select a programming language."
+      helpText="Select the language with which you are most familiar."
     >
       <RadioButton value="js" hasError>JavaScript</RadioButton>
       <RadioButton value="py" hasError>Python</RadioButton>

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

@@ -151,14 +151,13 @@ You may use [the Text primitive](/primitives/text) as a child of Alert, but if y
 
 ### Error
 
-Use an error alert to help a user understand a critical issue at the system level. Provide a way to resolve the issue in the alert.
+Use an error alert to help a user understand a critical issue at the system level, like site-wide service disruptions, active incidents, or expired billing information. Alerts should not appear in response to user action or inputs.
 
-Be cautious about using an error alert because they can be stressful for a user to see. In most cases, error alerts should be assigned `role="alert"`.
+When possible, provide a way to resolve the issue in the alert.
 
-There's a good chance you need to use an error alert if both these conditions are met:
+In most cases, error alerts should be assigned `role="alert"`.
 
-- The system-level issue is preventing the user from continuing a flow.
-- The user must take an action to resolve the issue.
+For additional guidance on what kind of component to use, use the [Alert vs. Callout vs. Toast vs. Help Text guide](#alert-vs-callout-vs-toast-vs-help-text). For additional guidance on how to compose error messages, refer to the [error state pattern](/patterns/error-state).
 
 You may use [the Text primitive](/primitives/text) as a child of Alert, but if you do, be sure to pass `color="inherit"` for error alerts.
 
@@ -202,7 +201,7 @@ For an `error` variant, for example, set the `i18nErrorLabel` prop.
 
 ## Composition Notes
 
-Keep alert text brief by placing only the highest priority information in an alert. Too much text in an alert can overwhelm a user. A good rule of thumb is to keep alert text to a single line in a desktop-sized container, or limiting it to 90 characters.
+Keep alert content brief by placing only the highest priority information in an alert. A good rule of thumb is to keep alert text to a single line in a desktop-sized container, or limiting it to 90 characters.
 
 <Blockquote
   name="Matthew Butterick"
@@ -215,15 +214,44 @@ Keep alert text brief by placing only the highest priority information in an ale
 
 Compose an alert with:
 
-- **A title (optional).** Bold this text at the beginning of the alert. This should be the most scannable text in the alert.
-- **Body text.** Use the default text style. Provide specificity on the issue and a resolution if applicable via an [anchor](/components/anchor). Be cautious about using a button in an alert since it may compete with other buttons on the screen and should be used only to trigger an action. If you must use a button, use a [small button](/components/button/#small-button).
+- **Title (optional).** Bold the text at the beginning of the alert. The title should be concise and convey the essence of the issue..
+- **Body text.** Use the default text style. Do not repeat information contained in a title. Explain what happened, and if something is wrong, how to fix it. If the resolution requires going to a different page, include an [anchor](/components/anchor). Use buttons sparingly, since they may compete with other buttons on the screen. Only use a small button if it will trigger an action.
+- **Full punctuation.** Use periods after full sentences. Avoid using exclamation points.
 
-### When to Use an Alert
+### Alert vs. Callout vs. Toast vs. Help Text
+
+Alert
+
+- Alerts communicate information relevant at the system level.
+- Do not use Alerts in response to user action.
+
+Callout
+
+- Callouts communicate information particular to a section of a page, or information that applies to a whole page.
+- Use a Callout when there are multiple pieces of information to convey. For example, an error summary.
+- Callouts can result from a user action, but don’t have to. Therefore, they can include either static or contextual content.
+
+Toast
+
+- Toasts communicate brief, easily comprehended messages.
+- Toasts generally result from a user action.
+- If the message is contextual or specific to a particular part of a page, consider Help Text or a Callout.
+- Do not use a Toast if the message is longer than two sentences (~140 characters). Use a Callout instead.
+- Do not use a Toast if there is more than one anchor or button. Use a Callout instead.
+
+Help Text
+
+- Help Text communicates contextual responses.
+- Help Text can result from a user action, but don’t have to.
+
+## Placement and behavior
 
 Place an alert where it makes the most contextual sense. Don't cover other UI elements with an alert.
 
 In general, the persistence and behavior on scroll of an alert should match the element it's scoped to. For example, if an alert is scoped to a navigation bar that is sticky on scroll and persists across several pages, the alert should similarly be sticky and persist across several pages. However, don't persist the alert across too many pages in a user session since it may lose its interruptive intent.
 
+### Do & Don't
+
 <DoDont>
   <Do
     title="Do"

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

@@ -139,7 +139,6 @@ Text length should be kept short.
 ### Accessibility
 
 - Ensure that Badge text is clear enough to understand immediately without having to rely on color to communicate meaning.
-  For example, an error badge should say “Token missing” rather than just “Token”, so the error is communicated via the Badge label.
 - For Status Badges, the inclusion of an icon is recommended to further reinforce the meaning.
 
 ## Examples
@@ -191,6 +190,10 @@ impending error. When using the Warning Badge, it is recommended that you includ
 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.
 
+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).
+
 <LivePreview scope={{Box, Badge, InformationIcon, ErrorIcon, WarningIcon, SuccessIcon, NewIcon}} language="jsx">
   {`<Box display="flex" columnGap="space80">
   <Badge as="span" variant="error">
@@ -338,6 +341,8 @@ of the Popover docs to add a Popover to a Badge.
 
 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.
+
 ### Use cases
 
 #### Call attention to attributes of table items
@@ -550,6 +555,25 @@ Use a Badge when you want to add a label to a piece of UI for quick identificati
   </Dont>
 </DoDont>
 
+<DoDont>
+  <Do title="Do" body="Ensure badge text communicates the problem.">
+    <Box alignItems="center" display="flex" justifyContent="space-around" height="100%" paddingX="space60">
+      <Badge variant="error" as="span">
+        <ErrorIcon title="error" size="sizeIcon10" />
+        Token missing
+      </Badge>
+    </Box>
+  </Do>
+  <Dont title="Don't" body="Don’t rely just on color to communicate meaning.">
+    <Box alignItems="center" display="flex" justifyContent="space-around" height="100%" paddingX="space60">
+      <Badge variant="error" as="span">
+        <ErrorIcon title="error" size="sizeIcon10" />
+        Token
+      </Badge>
+    </Box>
+  </Dont>
+</DoDont>
+
 ---
 
 ## Usage Guide