[WNMGDS-2864] Add utility actions pattern guidance page

packages/docs/content/patterns/utility-actions.mdx

@@ -0,0 +1,163 @@
+---
+title: Utility Actions
+intro: Utility actions for a webpage including print, email, RSS and more.
+core:
+ figmaNodeId: 4744-4695
+---
+
+import {
+ Button,
+ DownloadIcon,
+ EmailIcon,
+ LinkIcon,
+ PrintIcon,
+ RssIcon,
+ Table,
+ TableBody,
+ TableCaption,
+ TableCell,
+ TableHead,
+ TableRow,
+ WhatsNewIcon,
+} from '@cmsgov/design-system';
+
+## Example
+
+The example below shows utility actions for Print, Email and RSS.
+
+<EmbeddedExample>
+ <div className="ds-l-row ds-u-justify-content--end">
+ <div className="ds-l-col--2">
+ <Button variation="ghost" size="small">
+ <PrintIcon ariaHidden={false} className="ds-u-margin-right--1" />
+ Print
+ </Button>
+ </div>
+ <div className="ds-l-col--2">
+ <Button variation="ghost" size="small">
+ <EmailIcon ariaHidden={false} className="ds-u-margin-right--1" />
+ Email
+ </Button>
+ </div>
+ <div className="ds-l-col--2">
+ <Button variation="ghost" size="small">
+ <RssIcon ariaHidden={false} className="ds-u-margin-right--1" />
+ RSS
+ </Button>
+ </div>
+ </div>
+</EmbeddedExample>
+
+### Available Actions
+
+In Figma, use the toggle feature to select different utility actions.
+
+<Table>
+ <TableCaption>Available utility actions include:</TableCaption>
+ <TableHead>
+ <TableRow>
+ <TableCell key="utility" id="utility">
+ Utility
+ </TableCell>
+ <TableCell key="action" id="action">
+ Action
+ </TableCell>
+ </TableRow>
+ </TableHead>
+ <TableBody>
+ <TableRow key="Print">
+ <TableCell key="Utility" headers="utility" stackedTitle="Print Icon">
+ <Button variation="ghost" size="medium">
+ <PrintIcon ariaHidden={false} className="ds-u-margin-right--1" />
+ Print
+ </Button>
+ </TableCell>
+ <TableCell key="Action" headers="action" stackedTitle="Print description.">
+ Opens print terminal
+ </TableCell>
+ </TableRow>
+ <TableRow key="Email">
+ <TableCell key="Utility" headers="utility" stackedTitle="Email Icon">
+ <Button variation="ghost" size="medium">
+ <EmailIcon ariaHidden={false} className="ds-u-margin-right--1" />
+ Email
+ </Button>
+ </TableCell>
+ <TableCell key="Action" headers="action" stackedTitle="Email description.">
+ Opens default desktop email app
+ </TableCell>
+ </TableRow>
+ <TableRow key="RSS">
+ <TableCell key="Utility" headers="utility" stackedTitle="RSS Icon">
+ <Button variation="ghost" size="medium">
+ <RssIcon ariaHidden={false} className="ds-u-margin-right--1" />
+ RSS
+ </Button>
+ </TableCell>
+ <TableCell key="Action" headers="action" stackedTitle="RSS description.">
+ Opens an XML feed in a different tab
+ </TableCell>
+ </TableRow>
+ <TableRow key="Link">
+ <TableCell key="Utility" headers="utility" stackedTitle="Link Icon">
+ <Button variation="ghost" size="medium">
+ <LinkIcon ariaHidden={false} className="ds-u-margin-right--1" />
+ Link
+ </Button>
+ </TableCell>
+ <TableCell key="Action" headers="action" stackedTitle="Link description.">
+ Copies link for current page to clipboard
+ </TableCell>
+ </TableRow>
+ <TableRow key="Download">
+ <TableCell key="Utility" headers="utility" stackedTitle="Download Icon">
+ <Button variation="ghost" size="medium">
+ <DownloadIcon ariaHidden={false} className="ds-u-margin-right--1" />
+ Download
+ </Button>
+ </TableCell>
+ <TableCell key="Action" headers="action" stackedTitle="Download description.">
+ Initiates download
+ </TableCell>
+ </TableRow>
+ <TableRow key="What's New">
+ <TableCell key="Utility" headers="utility" stackedTitle="What's New Icon">
+ <Button variation="ghost" size="medium">
+ <WhatsNewIcon ariaHidden={false} className="ds-u-margin-right--1" />
+ What's New
+ </Button>
+ </TableCell>
+ <TableCell key="Action" headers="action" stackedTitle="What's New description.">
+ Opens sidebar with updates
+ </TableCell>
+ </TableRow>
+ </TableBody>
+</Table>
+
+## When to use
+
+- Content on a webpage or a document is something a user would want to be able to refer back to - provide options to print, email, or download.
+- If you would like to give the user the option to:
+ - Open an XML feed in a different tab
+ - Copy a link to a webpage
+ - Open a popup with new updates or new website capabilities
+
+### Usage
+
+- Utility actions are ghost buttons for available actions that do not take priority over primary or secondary call-to-actions (CTAs).
+- Placement should be in the page header and top, right aligned.
+- Include no more than 3 utility actions on a page to prevent cluttering the user interface (UI) and distracting the user.
+- When pairing 2 or more utility action buttons, the preferred action goes on the left.
+- Be consistent with the inclusion of utility actions and their order across pages and products.
+- Follow any additional governance established by your UX and content lead for which utility actions to include.
+
+### When to consider alternatives
+
+- If an action (e.g. printing or emailing) is a critical call-to-action on a webpage, consider using a solid or outlined main button.
+- If the utility action is opening a link in a new webpage versus triggering an action, refer to [guidance on links](/foundation/typography/links).
+- Carefully consider which utility actions are used on mobile (since space is a premium.)
+
+## Accessibility
+
+- Always include both the icon and label in utility actions to meet accessibility standards.
+- Don't create CTAs that duplicate utility actions on a page. Having multiple "print" actions on a page can hinder accessibility for screen reader users.