From 3d5d1db5e8eea37bcc6d296e4a349d08b0f75414 Mon Sep 17 00:00:00 2001 From: Nora Krantz <75342690+nkrantz@users.noreply.github.com> Date: Thu, 16 Nov 2023 13:24:19 -0500 Subject: [PATCH] chore: add wizard page template docs (#3601) * chore: add wizard page template docs * chore: update text color of form section description * chore: fix a11y failure * chore: pr feedback * chore: make sure example code matches story code * chore: use more button groups --- .changeset/hip-colts-invite.md | 6 + .../form/src/FormSectionDescription.tsx | 2 +- .../page-templates/SettingsExamples.ts | 1 - .../page-templates/WizardExamples.ts | 451 +++++++++++++++ .../ingredients/WizardIngredients.tsx | 60 ++ .../src/pages/page-templates/wizard/index.mdx | 180 +++++- .../stories/PageTemplates.stories.tsx | 530 +++++++++++++++++- 7 files changed, 1223 insertions(+), 7 deletions(-) create mode 100644 .changeset/hip-colts-invite.md create mode 100644 packages/paste-website/src/component-examples/page-templates/WizardExamples.ts create mode 100644 packages/paste-website/src/components/ingredients/WizardIngredients.tsx diff --git a/.changeset/hip-colts-invite.md b/.changeset/hip-colts-invite.md new file mode 100644 index 0000000000..003dc84a73 --- /dev/null +++ b/.changeset/hip-colts-invite.md @@ -0,0 +1,6 @@ +--- +"@twilio-paste/form": patch +"@twilio-paste/core": patch +--- + +[Form] Change color of FormSectionDescription from color-text-weak to color-text diff --git a/packages/paste-core/components/form/src/FormSectionDescription.tsx b/packages/paste-core/components/form/src/FormSectionDescription.tsx index 71d689c9a3..be0af2ec0b 100644 --- a/packages/paste-core/components/form/src/FormSectionDescription.tsx +++ b/packages/paste-core/components/form/src/FormSectionDescription.tsx @@ -26,7 +26,7 @@ export const FormSectionDescription = React.forwardRef diff --git a/packages/paste-website/src/component-examples/page-templates/WizardExamples.ts b/packages/paste-website/src/component-examples/page-templates/WizardExamples.ts new file mode 100644 index 0000000000..fbe7bbfd8f --- /dev/null +++ b/packages/paste-website/src/component-examples/page-templates/WizardExamples.ts @@ -0,0 +1,451 @@ +export const DefaultWizardExample = ` + + + + + + Breadcrumb + Breadcrumb + Breadcrumb + + + + Label + + Label + + Label + + Label + + Label + + + Wizard title + + Verb heading + + + Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi non ex risus. Aenean at ante id lectus + faucibus hendrerit a fringilla lorem. Pellentesque faucibus sit amet dolor vitae lacinia. + + + + +
+ + + + + + + + + + + + + + + + +
+ + + + + + + + +`.trim(); + +export const DefaultWizardWithContentExample = ` +<> + +
+ + + + + + + Add Reverse ETL destination + + Set up destination + + + +
+ + + + + Identifies this destination within your organization and typically includes the business unit, + geographic region, or environment. Example: Google Analytics North America Prod. + + +
+ + + + + + + + + + + +`.trim(); + +export const DefaultWizardOrderedListExample = ` + + + + + Select warehouse type + + Connect warehouse + + Set sync schedule + + Set selective sync + + + Add warehouse + + Connect Azure SQL data warehouse + + + Follow the steps below to start setting up Azure SQL data warehouse. + + + + +
+ + + + 1 + + + + + Configure your AzureSQL database + + Make sure you’re logging in with a user that has read and write permissions so that we can write to + your database. If you’re unsure on how to get started, view our documentation on Azure SQL data + warehouse. + + + + + + + + 2 + + + + + Name your schema + + Pick a name to help you identify this space in the warehouse, or use the default name provided. This + can’t be changed once the warehouse is connected. + + + + + + + + + + + + 3 + + + + + Enter your credentials + Copy and paste these credentials from AzureSQL. + + + + + + + + + + + + + + + + + + + + + + + 4 + + + + + + Test connection + + + + + + + +
+ + + + + + + Test your warehouse connection first. + + + + + + +`.trim(); + +export const WizardFooterOptionsExample = ` + + + + + + + + + + + + + + + + + +`.trim(); + +export const WizardFullPageExample = ` + + + + + Entities: Add warehouse + + + + + + + + + + Add warehouse + + { + setValue(newValue); + }} + name="warehouse type" + > + + Snowflake + + + Redshift + + + BigQuery + + + + + + + + + + +`.trim(); + +export const WizardDefaultHeaderWithProgressStepsExample = ` + + + + + + Breadcrumb + Breadcrumb + Breadcrumb + + + + Label + + Label + + Label + + Label + + Label + + + Wizard title + + Verb heading + + + Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi non ex risus. Aenean at ante id lectus + faucibus hendrerit a fringilla lorem. Pellentesque faucibus sit amet dolor vitae lacinia. + + + + + +`.trim(); + +export const WizardFullPageHeaderWithProgressStepsExample = ` + + + + + Wizard title + + + + + Label + + Label + + Label + + + + + + + +`.trim(); diff --git a/packages/paste-website/src/components/ingredients/WizardIngredients.tsx b/packages/paste-website/src/components/ingredients/WizardIngredients.tsx new file mode 100644 index 0000000000..c93c781979 --- /dev/null +++ b/packages/paste-website/src/components/ingredients/WizardIngredients.tsx @@ -0,0 +1,60 @@ +import { Anchor } from "@twilio-paste/anchor"; +import { ListItem, UnorderedList } from "@twilio-paste/list"; +import * as React from "react"; + +import { Ingredients, Related, Required } from "./Ingredients"; + +const WizardIngredients: React.FC = () => { + return ( + + + + + Heading + + + Button + + + Form and form elements like{" "} + Input, Checkbox,{" "} + Radio Group,{" "} + Select, Combobox,{" "} + Textarea,{" "} + Date Picker,{" "} + Time Picker,{" "} + Visual Picker,{" "} + Help Text, and Label + + + Icons: ArrowBack, ArrowForward + + + + + + + Breadcrumb + + + Detail Text + + + Progress Steps + + + Separator + + + Sidebar + + + Topbar + + + + + ); +}; + +export { WizardIngredients }; diff --git a/packages/paste-website/src/pages/page-templates/wizard/index.mdx b/packages/paste-website/src/pages/page-templates/wizard/index.mdx index fae0e7712d..ffa2a126d0 100644 --- a/packages/paste-website/src/pages/page-templates/wizard/index.mdx +++ b/packages/paste-website/src/pages/page-templates/wizard/index.mdx @@ -1,10 +1,14 @@ export const meta = { title: 'Wizard', - description: 'A Wizard flow guides customers through complicated tasks to reach a goal.', + description: 'A Wizard focuses customers through a series of tasks to reach a goal.', slug: '/page-templates/wizard/', }; -import {InDevelopment} from '../../../components/empty-state/InDevelopment'; +import {Callout, CalloutHeading, CalloutText} from '@twilio-paste/callout'; +import {Anchor} from '@twilio-paste/anchor'; + +import {DefaultWizardExample, DefaultWizardWithContentExample, DefaultWizardOrderedListExample, WizardFooterOptionsExample, WizardFullPageExample, WizardDefaultHeaderWithProgressStepsExample, WizardFullPageHeaderWithProgressStepsExample} from '../../../component-examples/page-templates/WizardExamples'; +import {WizardIngredients} from '../../../components/ingredients/WizardIngredients'; import {SidebarCategoryRoutes} from '../../../constants'; import DefaultLayout from '../../../layouts/DefaultLayout'; import {getFeature, getNavigationData} from '../../../utils/api'; @@ -43,7 +47,177 @@ export const getStaticProps = async () => { - + + +## About Wizard + +Use a Wizard when a customer’s goal is long or complex, and breaking it up into smaller page-by-page tasks allows the user to focus and not feel overwhelmed. A Wizard can be useful when the tasks to reach a goal are dependent on each other, and customers need to finish different tasks based on previous ones. + +Start by splitting the goal across multiple tasks with each page containing just one main task, for example: +- One piece of information the customer needs to know +- One decision they have to make +- One question they have to answer + +A single task or page can still have multiple form fields or pieces of information if they’re related. + + + Looking for guidelines on multi-step flows contained to Modals or Cards? + We don’t have guidelines yet for multi-step flows that aren’t the only flow on a page. If you need it for your work, please consider partnering with us to contribute it. + + +## Ingredients + + + +## How to use this template + + + +### Content structure + +Before deciding on a page layout, make a few content and experience decisions first. This includes: + +- **Wizard title:** Describes the overall goal the customer is trying to achieve. The title should start with a verb. Examples: “Upgrade”, “Build Track call”. +- **Task headings:** For each page, the task heading describes the current task the customer is doing. Each heading should generally be in the format “[Verb] [object]”. Examples: “Select computed trait”, “Connect to Whatsapp”. +- **Task content:** Decide what content and components will help a customer finish each task. +- **Goal linearity and duration:** Decide whether a customer can achieve the entire goal in one session. Decide whether they need to leave Twilio to finish a task and whether they need to wait for Twilio to do something before finishing the flow. + +There are 3 standard max-widths for the content of each Wizard page. Based on the content you need for each task, start with the smallest max-width and size up as needed: +1. `size-70` (712px). If this is too small, use: +2. `size-100` (1024px). If this is too small, use: +3. Full-width, with a max-width of `size-70` for the Page Header. + +Use the same max-width for each page of the Wizard if possible. + +### Default template + +In most scenarios, you’ll take customers through a Wizard without having to change the Sidebar or Topbar. + + + +#### Page header + +At the top of each page of the Wizard, add: +- Wizard title as [Detail Text](/components/detail-text) (optional) +- Task [Heading](/components/heading) +- [Paragraph](/components/paragraph) text under the heading to explain the step (optional) + +#### Body + +Use the [Form](/components/form) component to set spacing between form elements. + +There may be cases where you need to show multiple tasks on the same page because customers need to reference them at the same time. If this is the case, use a stylized ordered list (coming soon!) to group tasks. + + + + + Looking for guidelines on progressive disclosures? + We don’t have guidelines yet for this part of Wizard. If you need it for your work, please consider partnering with us to contribute it. + + +#### Actions footer + +Use these actions in the footer, starting from the right side of the page: +- A primary, right-aligned next [Button](/components/button) to let a customer move to the next task. The Button is right-aligned to signal that the flow is moving forward. If there are more tasks, use the word “Next” followed by [ArrowForwardIcon](/components/icon). If the customer is on the last task, the Button should indicate they are finishing the goal, and not include the arrow icon. +- A secondary, right-aligned Button with the word “Cancel” if customers can’t save their progress, or “Close” if they can. Follow the [confirmation pattern](/patterns/confirmation) for guidance on how to ask a customer to confirm that they want to leave a Wizard or save their progress. +- A secondary, left-aligned back Button. If there were previous tasks, use the [ArrowBackIcon](/components/icon) followed by the word “Back”. If there are no previous tasks, don’t show the Button. + +If the task contents don’t fill the width of the page body, use a [Separator](/components/separator) above the actions with a gap of `space-50`. However this should be used sparingly because in most cases your content should fill the width of the page body. + +Don’t disable any footer Buttons unless it’s immediately obvious to customers why they’re disabled. Disabled Buttons aren’t focusable and don’t provide any information about why they’re disabled. Instead, show Buttons in their default state, then provide helpful error text after they’re pressed. + + + +### Full-page template + + + +Use the full-page Wizard template when it’s absolutely critical that a customer remains focused to finish the task. + +If your app allows it, load the Wizard without a Sidebar, and replace the content in the Topbar with: + +- The Wizard title as a left-aligned [Heading](/components/heading) +- A secondary, right-aligned Button with the word “Cancel” if customers can’t save their progress, or “Close” if they can. Follow the [confirmation pattern](/patterns/confirmation) for guidance on how to ask a customer to confirm that they want to leave a Wizard or save their progress. + +If your app doesn’t allow loading a page without the navigation frame, [collapse the Sidebar](/components/sidebar#compact-push-sidebar) and follow the [default Wizard template](#default-template). + +#### Page header + +At the top of the page, add the Task [Heading](/components/heading) and if needed, [Paragraph](/components/paragraph) text under the heading to explain the step. + +#### Body + +Follow the [default Wizard template](#default-template). + +#### Actions footer + +Follow the [default Wizard template](#default-template), but don’t include a close button in the footer. + +### When to use Progress Steps + +Only use [Progress Steps](/components/progress-steps) when necessary. Some scenarios include when: + +- A customer needs to return to previous steps, especially across multiple sessions. +- A goal takes a long time to finish. +- A customer is trying a feature out or going through more of an exploratory flow. Progress Steps can help them understand if they want to complete the steps. + +If the customer’s journey through a Wizard is relatively linear, continuous, and short, don’t use Progress Steps. + +When in doubt, start by not using Progress Steps, and add it in once it’s clear the experience suffers without it. + + + Research insight + Research from GOV.UK showed that their users were actually getting confused and intimidated when seeing their progress indicator. They found that completion rates, time-to-completion, and total amount of online applications were unaffected after removing their progress bar from their services. + + +Match Progress Steps labels to task headings for each page. If you need to use Progress Steps and there’s forking logic in the flow, hide Progress Steps until there’s a single path forward, or make the step labels generic enough to cover all variants of a task. + +#### With the default template + +Place Progress Steps above the Wizard title. + + + +#### With the full-page template + +Center Progress Steps in the Topbar. + + diff --git a/packages/paste-website/stories/PageTemplates.stories.tsx b/packages/paste-website/stories/PageTemplates.stories.tsx index 1f100e8871..a6f511b377 100644 --- a/packages/paste-website/stories/PageTemplates.stories.tsx +++ b/packages/paste-website/stories/PageTemplates.stories.tsx @@ -21,9 +21,20 @@ import { DescriptionListSet, DescriptionListTerm, } from "@twilio-paste/description-list"; -import { Form, FormActions, FormControl } from "@twilio-paste/form"; +import { DetailText } from "@twilio-paste/detail-text"; +import { + Form, + FormActions, + FormControl, + FormSection, + FormSectionDescription, + FormSectionHeading, +} from "@twilio-paste/form"; import { Column, Grid } from "@twilio-paste/grid"; import { Heading } from "@twilio-paste/heading"; +import { HelpText } from "@twilio-paste/help-text"; +import { ArrowBackIcon } from "@twilio-paste/icons/esm/ArrowBackIcon"; +import { ArrowForwardIcon } from "@twilio-paste/icons/esm/ArrowForwardIcon"; import { DownloadIcon } from "@twilio-paste/icons/esm/DownloadIcon"; import { EditIcon } from "@twilio-paste/icons/esm/EditIcon"; import { FilterIcon } from "@twilio-paste/icons/esm/FilterIcon"; @@ -37,12 +48,22 @@ import { InPageNavigation, InPageNavigationItem } from "@twilio-paste/in-page-na import { Input } from "@twilio-paste/input"; import { Label } from "@twilio-paste/label"; import { Paragraph } from "@twilio-paste/paragraph"; +import { + ProgressStepComplete, + ProgressStepCurrent, + ProgressStepIncomplete, + ProgressStepSeparator, + ProgressSteps, +} from "@twilio-paste/progress-steps"; import { ScreenReaderOnly } from "@twilio-paste/screen-reader-only"; import { Select } from "@twilio-paste/select"; import { Separator } from "@twilio-paste/separator"; +import { Sidebar, SidebarPushContentWrapper } from "@twilio-paste/sidebar"; import { TBody, THead, Table, Td, Th, Tr } from "@twilio-paste/table"; import { Text } from "@twilio-paste/text"; +import { Topbar, TopbarActions } from "@twilio-paste/topbar"; import { useUID } from "@twilio-paste/uid-library"; +import { VisualPickerRadio, VisualPickerRadioGroup } from "@twilio-paste/visual-picker"; import * as React from "react"; export default { @@ -675,7 +696,6 @@ export const FullSettingsExample = (): JSX.Element => { display="flex" flexDirection="column" rowGap="space130" - maxWidth="size90" > @@ -860,3 +880,509 @@ export const SettingsOverviewExample = (): JSX.Element => { SettingsOverviewExample.parameters = { padding: false, }; + +export const DefaultWizardExample = (): JSX.Element => { + const input1 = useUID(); + const input2 = useUID(); + const input3 = useUID(); + const input4 = useUID(); + return ( + + + + + + Breadcrumb + Breadcrumb + Breadcrumb + + + + Label + + Label + + Label + + Label + + Label + + + Wizard title + + Verb heading + + + Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi non ex risus. Aenean at ante id lectus + faucibus hendrerit a fringilla lorem. Pellentesque faucibus sit amet dolor vitae lacinia. + + + + +
+ + + + + + + + + + + + + + + + +
+ + + + + + + + + + ); +}; +DefaultWizardExample.parameters = { + padding: false, +}; + +export const DefaultWizardWithContentExample = (): JSX.Element => { + const input1 = useUID(); + const sidebarId = useUID(); + const topbarSkipLinkID = useUID(); + const sidebarNavigationSkipLinkID = useUID(); + const mainContentSkipLinkID = useUID(); + return ( + <> + +
+ + + + + + + Add Reverse ETL destination + + Set up destination + + + +
+ + + + + Identifies this destination within your organization and typically includes the business unit, + geographic region, or environment. Example: Google Analytics North America Prod. + + +
+ + + + + + + + + + + + + ); +}; +DefaultWizardWithContentExample.parameters = { + padding: false, +}; + +export const DefaultWizardOrderedListExample = (): JSX.Element => { + const input1 = useUID(); + const input2 = useUID(); + const input3 = useUID(); + const input4 = useUID(); + const input5 = useUID(); + return ( + + + + + Select warehouse type + + Connect warehouse + + Set sync schedule + + Set selective sync + + + Add warehouse + + Connect Azure SQL data warehouse + + + Follow the steps below to start setting up Azure SQL data warehouse. + + + + +
+ + + + 1 + + + + + Configure your AzureSQL database + + Make sure you’re logging in with a user that has read and write permissions so that we can write to + your database. If you’re unsure on how to get started, view our documentation on Azure SQL data + warehouse. + + + + + + + + 2 + + + + + Name your schema + + Pick a name to help you identify this space in the warehouse, or use the default name provided. This + can’t be changed once the warehouse is connected. + + + + + + + + + + + + 3 + + + + + Enter your credentials + Copy and paste these credentials from AzureSQL. + + + + + + + + + + + + + + + + + + + + + + + 4 + + + + + + Test connection + + + + + + + +
+ + + + + + + Test your warehouse connection first. + + + + + + + ); +}; +DefaultWizardOrderedListExample.parameters = { + padding: false, +}; + +export const WizardFooterOptionsExample = (): JSX.Element => { + return ( + + + + + + + + + + + + + + + + + + + ); +}; +WizardFooterOptionsExample.parameters = { + padding: false, +}; + +export const WizardFullPageExample = (): JSX.Element => { + const [value, setValue] = React.useState(""); + return ( + + + + + Entities: Add warehouse + + + + + + + + + + Add warehouse + + { + setValue(newValue); + }} + name="warehouse type" + > + + Snowflake + + + Redshift + + + BigQuery + + + + + + + + + + + + ); +}; +WizardFullPageExample.parameters = { + padding: false, +}; + +export const WizardDefaultHeaderWithProgressStepsExample = (): JSX.Element => { + return ( + + + + + + Breadcrumb + Breadcrumb + Breadcrumb + + + + Label + + Label + + Label + + Label + + Label + + + Wizard title + + Verb heading + + + Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi non ex risus. Aenean at ante id lectus + faucibus hendrerit a fringilla lorem. Pellentesque faucibus sit amet dolor vitae lacinia. + + + + + + ); +}; +WizardDefaultHeaderWithProgressStepsExample.parameters = { + padding: false, +}; + +export const WizardFullPageHeaderWithProgressStepsExample = (): JSX.Element => { + return ( + + + + + Wizard title + + + + + Label + + Label + + Label + + + + + + + + ); +}; +WizardFullPageHeaderWithProgressStepsExample.parameters = { + padding: false, +};