new confirmation page (#3339)

* new confirmation page

* fixed markdown error

* updated markdown error

* updated markdown errors

* updated markdown errors

* updated markdown errors

* changed table formatting

* small text updates

* added import DoDont

* updated import info

* chore: add confirmations page to cypress constants list

* chore: confirmations to confirmation

---------

Co-authored-by: “nora <[email protected]>
Co-authored-by: Simon Taggart <[email protected]>

cypress/integration/sitemap-vrt/constants.ts

@@ -117,6 +117,7 @@ export const SITEMAP = [
  '/introduction/for-engineers/quickstart/',
  '/patterns/button-vs-anchor/',
  '/introduction/working-with-us/',
+ '/patterns/confirmation/',
  '/patterns/delete/',
  '/patterns/data-export/',
  '/patterns/filter-group/',

packages/paste-website/src/pages/patterns/confirmation/index.mdx

@@ -0,0 +1,144 @@
+export const meta = {
+ title: 'Confirmation',
+ description:
+ 'A confirmation ensures a user understands what will happen if they take an action that’s destructive, complex, or has an unexpected result.',
+ slug: '/patterns/confirmation/',
+};
+
+import {Anchor} from '@twilio-paste/anchor';
+import {Box} from '@twilio-paste/box';
+import {Card} from '@twilio-paste/card';
+import {Disclosure, DisclosureHeading, DisclosureContent} from '@twilio-paste/disclosure';
+import {DoDont, Do, Dont} from '../../../components/DoDont';
+import {Grid, Column} from '@twilio-paste/grid';
+import {Heading} from '@twilio-paste/heading';
+import {Paragraph} from '@twilio-paste/paragraph';
+import {Text} from '@twilio-paste/text';
+import {useUID} from '@twilio-paste/uid-library';
+import {ResponsiveImage} from '../../../components/ResponsiveImage';
+import DeleteMediumSeverityImage from '../../../assets/images/patterns/delete-medium-severity.png';
+import DeleteHighSeverityImage from '../../../assets/images/patterns/delete-high-severity.png';
+import DefaultLayout from '../../../layouts/DefaultLayout';
+import {getFeature, getNavigationData} from '../../../utils/api';
+
+export default DefaultLayout;
+
+export const getStaticProps = async () => {
+ const navigationData = await getNavigationData();
+ const feature = await getFeature('Confirmation');
+ return {
+ props: {
+ data: {
+ ...feature,
+ },
+ navigationData,
+ },
+ };
+};
+
+<content>
+
+<NormalizedPatternHeader description={meta.description} name={meta.title} data={props.data} />
+
+</content>
+
+---
+
+<contentwrapper>
+
+<PageAside data={mdxHeadings} />
+
+<content>
+
+## Ingredients
+
+<Grid gutter="space30" marginBottom="space80">
+ <Column>
+ <Card>
+ <Heading as="h3" variant="heading40" marginBottom="space0">
+ <Anchor href="/components/alert-dialog">Alert Dialog</Anchor>
+ </Heading>
+ </Card>
+ </Column>
+</Grid>
+
+```jsx
+// import all ingredients for the confirmation pattern
+
+import {AlertDialog} from '@twilio-paste/core/alert-dialog';
+```
+
+## Usage
+
+### General
+
+Use a confirmation to ask the user to verify that they want to proceed with a complex action, or one with significant or unanticipated consequences (like irreversibility). Confirmation messages are always triggered by an initial user action.
+Confirmations are displayed using an [Alert Dialog](/components/alert-dialog), since it requires the user to interact with the component.
+
+### Composition notes
+
+Each confirmation [Alert Dialog](/components/alert-dialog) should follow a predictable content pattern.
+
+#### Heading
+
+The [Heading](/components/heading) should be phrased as a question. In general:
+
+- Avoid using articles like “the” or “a.”
+- Avoid the phrase “Are you sure?”
+- Use sentence case.
+
+#### Paragraph (optional)
+
+The [Paragraph](/components/paragraph) should include 1-3 sentences that explain the outcomes of the actions. If the action is irreversible, say so.
+
+#### Buttons
+
+Confirmation messages typically have 2 [Buttons](/components/button): one that confirms the action and another that offers an alternative. Labels should be short and mirror the language in the title whenever possible.
+
+## Variations
+
+Confirmation messages are used in a variety of situations where it’s important to confirm that the user wants to proceed with an action, like saving changes before exiting, starting a process that could incur unexpected costs, or [deleting something](/patterns/delete).
+
+| Use case | Sample text | Sample CTAs |
+| ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| User wants to [delete](/patterns/delete) something | **Delete [thing]?** <br/> You’re deleting [object name]. You cannot undo this action. | Cancel \| Delete [thing] |
+| User wants to [delete](/patterns/delete) something that has major consequences | **Delete [thing]?** <br/> When you delete [thing], all [objects] are permanently deleted. You cannot undo this action. Enter [user input] to delete [thing] | Cancel \| Delete [thing] |
+| User wants to change something | **Change [thing]?** <br/> When you change [thing], your [objects] are deleted. | Cancel \| Change [thing] |
+| User wants to leave a flow but may want to save changes | **Save changes?** <br/> If you close without saving, changes are lost. | Close without saving \| Save and close |
+| User wants to leave a flow but changes can’t be saved | **Stop [doing thing]?** <br/> Your changes will not be saved. | Keep [doing thing] \| Stop [doing thing] |
+| User wants to perform an action that has implications for resources (money, credits, etc.) | **Use title to repeat action** <br/> Explain what could happen to the resource, and offer other options if available and appropriate. | _Offer clear alternatives_ |
+
+## Dos and Don'ts
+
+<DoDont>
+ <Do title="Do" body="Tell the user if they cannot undo the action." preview={false} />
+ <Dont title="Don't" body="Don't use confirmation messages for routine, easily reversed actions." preview={false} />
+</DoDont>
+
+<DoDont>
+ <Do title="Do" body="Phrase the heading as a question." preview={false} />
+ <Dont title="Don't" body="Don't use the phrase “Are you sure?”" preview={false} />
+</DoDont>
+
+<DoDont>
+ <Do title="Do" body="Make the buttons clear alternatives." preview={false} />
+ <Dont
+ title="Don't"
+ body="Don't use a Cancel as a CTA button if the user action is related to cancellation. It's confusing!"
+ preview={false}
+ />
+</DoDont>
+
+## Starter kits
+
+### CodeSandbox
+
+Coming soon
+
+### Figma
+
+Coming soon
+
+</content>
+
+</contentwrapper>