Skip to content

Commit

Permalink
content-updates-round3 (#3413)
Browse files Browse the repository at this point in the history 
* confirmation related changes to delete, update on interaction limitations for visual picker

* fixed dodont tags

* alert, button, popover, select, switc, table, tooltip updates

* minor fixes

* updated hyperlink based on shadi feedback

* changes based on simon feedback

* updates based on simon feedback

* Apply suggestions from code review

incorporating sarah suggestions

Co-authored-by: Sarah <sali@twilio.com>

* updates based on feedback

* chore: final dev fix up

* chore: add dodont and callout to shortcodes

* small text updates

---------

Co-authored-by: Sarah <sali@twilio.com>
Co-authored-by: Si Taggart <me@simontaggart.com>
  • Loading branch information
@mma1504 @serifluous @SiTaggart
3 people committed Aug 31, 2023
1 parent 29b6b7b commit e770583
Show file tree
Hide file tree
Showing 10 changed files with 253 additions and 211 deletions.
128 changes: 64 additions & 64 deletions packages/paste-website/src/component-examples/DeletePatternExamples.ts
View file
@@ -1,71 +1,71 @@
export const LowSeverityExample = `
const LowSeverityDelete = () => {
return (
<Button variant="destructive_link">Remove</Button>
)
}
render(
<LowSeverityDelete />
const LowSeverityDelete = () => {
return (
<Button variant="destructive_link">Remove</Button>
)
}
render(
<LowSeverityDelete />
)
`.trim();

export const MediumSeverityExample = `
const MediumSeverityDelete = () => {
const [isOpen, setIsOpen] = React.useState(false);
const handleOpen = () => setIsOpen(true);
const handleClose = () => setIsOpen(false);
return (
<>
<Button variant="destructive" onClick={handleOpen}>Delete</Button>
<AlertDialog
heading="Delete from regulatory bundle?"
isOpen={isOpen}
onConfirm={handleClose}
onConfirmLabel="Delete"
onDismiss={handleClose}
onDismissLabel="Cancel"
destructive
>
You're about to delete "Plan A Productions, LLC" from this regulatory bundle. This does not impact any other regulatory bundles.
</AlertDialog>
</>
)
}
render(
<MediumSeverityDelete />
const MediumSeverityDelete = () => {
const [isOpen, setIsOpen] = React.useState(false);
const handleOpen = () => setIsOpen(true);
const handleClose = () => setIsOpen(false);
return (
<>
<Button variant="destructive" onClick={handleOpen}>Delete</Button>
<AlertDialog
heading="Delete from regulatory bundle?"
isOpen={isOpen}
onConfirm={handleClose}
onConfirmLabel="Delete"
onDismiss={handleClose}
onDismissLabel="Cancel"
destructive
>
You're about to delete "Plan A Productions, LLC" from this regulatory bundle. This does not impact any other regulatory bundles.
</AlertDialog>
</>
)
}
render(
<MediumSeverityDelete />
)
`.trim();

export const HighSeverityExample = `
const HighSeverityDelete = () => {
const [isDisabled, setIsDisabled] = React.useState(true);
const [isOpen, setIsOpen] = React.useState(false);
const [inputString, setInputString] = React.useState('');
const [inputHasError, setInputHasError] = React.useState(false);
const handleOpen = () => {
if (inputString !== '') setIsDisabled(false);
setIsOpen(true);
};
const handleDismiss = () => {
setIsDisabled(true)
setIsOpen(false)
};
const handleConfirm = () => {
if (inputString === 'Toyota TCB Automobile (Gevelsberg)') {
setIsOpen(false)
setInputString('')
setInputHasError(false)
}
else {
setInputHasError(true)
}
};
const handleChange = (e) => {
setInputString(e.target.value)
if (e.target.value !== '') setIsDisabled(false);
else setIsDisabled(true);
};
const HighSeverityDelete = () => {
const [isDisabled, setIsDisabled] = React.useState(true);
const [isOpen, setIsOpen] = React.useState(false);
const [inputString, setInputString] = React.useState('');
const [inputHasError, setInputHasError] = React.useState(false);
const handleOpen = () => {
if (inputString !== '') setIsDisabled(false);
setIsOpen(true);
};
const handleDismiss = () => {
setIsDisabled(true)
setIsOpen(false)
};
const handleConfirm = () => {
if (inputString === 'Toyota TCB Automobile (Gevelsberg)') {
setIsOpen(false)
setInputString('')
setInputHasError(false)
}
else {
setInputHasError(true)
}
};
const handleChange = (e) => {
setInputString(e.target.value)
if (e.target.value !== '') setIsDisabled(false);
else setIsDisabled(true);
};
return (
<>
Expand Down Expand Up @@ -96,7 +96,7 @@ export const HighSeverityExample = `
}
render(
<HighSeverityDelete />
<HighSeverityDelete />
)
`.trim();

Expand All @@ -111,9 +111,9 @@ export const PostDeletionExample = `
const handleConfirm = () => {
setIsOpen(false)
toaster.push({
message: '"Plan A Productions, LLC" was deleted. To undo deletion, return to the regulatory bundle overview.',
variant: 'success',
})
message: '"Plan A Productions, LLC" was deleted. To undo deletion, return to the regulatory bundle overview.',
variant: 'success',
})
}
return (
<>
Expand All @@ -134,6 +134,6 @@ export const PostDeletionExample = `
)
}
render(
<MediumSeverityDelete />
<MediumSeverityDelete />
)
`.trim();
10 changes: 10 additions & 0 deletions packages/paste-website/src/components/paste-mdx-provider/index.tsx
View file
Expand Up @@ -13,6 +13,7 @@ import {Separator} from '@twilio-paste/separator';
import type {SeparatorProps} from '@twilio-paste/separator';
import {Table, THead, TBody, TFoot, Tr, Th, Td} from '@twilio-paste/table';
import {InlineCode} from '@twilio-paste/inline-code';
import {Callout, CalloutHeading, CalloutList, CalloutListItem, CalloutText} from '@twilio-paste/callout';

import type {CodeblockProps} from '../codeblock';
import {Codeblock} from '../codeblock';
Expand All @@ -29,6 +30,7 @@ import {StoryPreview} from '../shortcodes/StoryPreview';
import {ArticleHeader} from '../shortcodes/ArticleHeader';
import {ArticleContent, ArticleAside} from '../shortcodes/ArticleLayouts';
import {NormalizedComponentHeader} from '../shortcodes/normalized-component-header';
import {DoDont, Do, Dont} from '../DoDont';

interface PasteMDXProviderProps {
children?: React.ReactElement;
Expand Down Expand Up @@ -57,6 +59,14 @@ const shortcodes = {
ArticleAside,
NormalizedComponentHeader,
StoryPreview,
DoDont,
Do,
Dont,
Callout,
CalloutHeading,
CalloutList,
CalloutListItem,
CalloutText,
};

const MDXPoviderComponents = {
Expand Down
63 changes: 28 additions & 35 deletions packages/paste-website/src/pages/components/alert/index.mdx
View file
Expand Up @@ -67,19 +67,28 @@ Use an Alert to notify a user about high-priority or time-sensitive changes in t

Use an Alert for one of these types of information:

- **Neutral or general information.** Use this in most cases where you are notifying a user of a change.
- **Warning.** Use this for critical information that will help a user avoid an issue.
- **Error.** Use this for critical information that's preventing a user from continuing a flow and if there's action required on their end to resolve the issue.
- **Neutral or general information.** Usually information about a change users need to know about.
- **Warning.** Critical information that will help a user avoid an issue.
- **Error.** Critical information that's preventing a user from continuing a flow and if there's action required on their end to resolve the issue.

<Blockquote
name="Nielsen Norman Group"
source="Indicators, Validations, and Notifications"
sourceUrl="https://www.nngroup.com/articles/indicators-validations-notifications/"
>
A notification sent irrespective of the current user goal would likely be ignored, and may even annoy users because it
will disrupt their current task and be irrelevant to their current needs.
</Blockquote>

### Accessibility

- Pass in `role="alert"` or `role="status"` through [props](#props). Otherwise, the default role is `status` for neutral alerts and `alert` for warning and error alerts.
- Screen readers announce error and warning alert text immediately. Alerts that persist across multiple pages announce themselves repeatedly which may become annoying. Consider making alerts in these cases dismissible.
- Render an alert only when it's needed. Assistive technologies will be able to read a visually hidden element. Don't visually hide an alert and then make it visible through client-side code.
- Show an alert only when it's needed. Assistive technologies will be able to read a visually hidden element. Don't visually hide an alert and then make it visible through client-side code.

The Alert uses multiple methods to indicate the alert type.
- **Icon.** The icon visually indicates the alert type, and announces the type to a screenreader.
- **Color.** Each alert type is a different color.
Alert uses multiple methods to indicate type.
- **Icon.** An icon visually indicates the type, and announces the type to a screenreader.
- **Color.** Each type is a different color.

## Examples

Expand Down Expand Up @@ -108,21 +117,12 @@ The Alert uses multiple methods to indicate the alert type.

### Neutral

Use a neutral alert to notify a user of a change that's relevant for them to achieve their current goal. Don't use an alert to communicate general promotional information.
Use a neutral Alert to notify a user of a change that's relevant for them to achieve their current goal. Don't use it to communicate general promotional information.

In most cases, a neutral alert should be dismissible (_i.e._, have a close button) and should be assigned `role="status"`.
In most cases, a neutral Alert should be dismissible (_i.e._, have a close button) and should be assigned `role="status"`.

You may use [the Text primitive](/primitives/text) as a child of Alert, but if you do, be sure to pass `color="inherit"` for neutral alerts.

<Blockquote
name="Nielsen Norman Group"
source="Indicators, Validations, and Notifications"
sourceUrl="https://www.nngroup.com/articles/indicators-validations-notifications/"
>
A notification sent irrespective of the current user goal would likely be ignored, and may even annoy users because it
will disrupt their current task and be irrelevant to their current needs.
</Blockquote>

<LivePreview scope={{Alert, Text, Anchor}} language="jsx">
{`<Alert variant="neutral">
<strong>Set up your contact preferences.</strong> You can now set up your contact preferences on your dashboard. <Anchor href="#">Go to contact preferences</Anchor>
Expand All @@ -135,7 +135,7 @@ Use a warning Alert to help a user avoid an issue.

A warning Alert should provide explain the possible issue, what to do, and what happens if they don't. If the user can take an immediate action, provide a way to do it.

Be cautious about using a warning alert because they can be stressful for a user to see. In most cases, a warning alert should be assigned `role="alert"`.
Be cautious about using a warning Alert because they can be stressful for a user to see. In most cases, a warning Alert should be assigned `role="alert"`.

You may use [the Text primitive](/primitives/text) as a child of Alert, but if you do, be sure to pass `color="inherit"` for warning alerts.

Expand Down Expand Up @@ -195,23 +195,16 @@ For an `error` variant, for example, set the `i18nErrorLabel` prop.

## Composition notes

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.
Keep content brief by placing only the highest priority information in an Alert. A good rule of thumb is to keep text to a single line in a desktop-sized container, or [limit it to 90 characters](https://practicaltypography.com/responsive-web-design.html).

<Blockquote
name="Matthew Butterick"
source="Butterick's Practical Typography"
sourceUrl="https://practicaltypography.com/responsive-web-design.html"
>
Regardless of screen width, the optimal line length is still 45–90 characters. As you test your layout, make sure that
text elements stay within this range.
</Blockquote>
Compose an Alert with:

Compose an alert with:

- **Title (optional).** Bold the text at the beginning of the alert. The title should be concise and convey the essence of the issue.
- **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. Limit body text to 1-2 sentences and do not repeat information contained in a title. Explain what happened, and if something is wrong, how to fix it. When possible, include what happens if they don't take action. If the resolution requires going to a different page, include an [Anchor](/components/anchor). Use [Buttons](/components/button) sparingly, since they may compete with other [Buttons](/components/button) on the screen. Only use a small [Button](/components/button) if it will trigger an action.
- **Full punctuation.** Use periods after full sentences. Avoid using exclamation points.

Active voice is generally preferred (for example, "You updated the API."). However, passive voice is acceptable for alerts related to whether a system action occured or not (for example, "API was updated.").

### Alert vs. Callout vs. Toast vs. Help Text

Alert
Expand Down Expand Up @@ -240,22 +233,22 @@ Alert

### Placement and behavior

Place an alert where it makes the most contextual sense. Don't cover other UI elements with an alert.
Place an Alert where it makes the most contextual sense. Don't cover other UI elements.

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.
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"
body="Use only 1 Alert per page. Use 2 Alerts only if absolutely necessary and if the Alerts are placed in different containers. Be sure to add 0.5rem spacing if using 2 Alerts."
body="Use only one Alert per page. Use two Alerts only if absolutely necessary and if the Alerts are placed in different containers. Be sure to add 0.5rem spacing if using two Alerts."
>
<Alert variant="error">
Your account balance is low and your credit card has expired. As a result we have suspended your account
</Alert>
</Do>
<Dont title="Don't" body="Don't use more than 2 Alerts per page.">
<Dont title="Don't" body="Don't use more than two Alerts per page.">
<Alert variant="error">Your credit card has expired</Alert>
<Alert variant="warning">Your account balance is low</Alert>
<Alert variant="error">Your account is suspended</Alert>
Expand Down
23 changes: 8 additions & 15 deletions packages/paste-website/src/pages/components/button/index.mdx
View file
Expand Up @@ -74,8 +74,8 @@ a Button include:
- Closing a modal
- Moving to the next step in a flow

A Button can contain an icon and/or text. See Composing a Button below
for more detailed guidelines.
A Button can contain an icon and/or text. See [Icon Buttons](#icon-buttons)
for detailed guidelines.

#### Button vs. Anchor (Link)

Expand Down Expand Up @@ -557,24 +557,17 @@ In most cases, you’ll use a text-only Button.

Button text should:

- Use sentence case (“Log in”, not “Log In”)
- Clearly indicate what’ll happen when a user presses it.
- Use sentence case ("Sign up now", not "Sign Up Now").
- Avoid articles ("a", "the").
- Clearly indicate what will happen when a user selects it.
- Start with a verb, except for a common action like “Done.”
- Be concise without sacrificing clarity and user confidence.

Pair text with an icon only if the icon clarifies the meaning of
the Button. Use no more than one icon before text and one icon after text.
In general, align Buttons to the direction of the text (for example, left-aligned in English) for easy scannability. When moving customers through a sequence, place the primary Button in the direction of the movement (e.g., a “Next” Button goes on the right in an English-language flow).

### When to use a Button
Pair text with an icon only if the icon clarifies the meaning of the Button. Use no more than one icon before text and one icon after text.

Use a Button to indicate that users can trigger an action.

In general, align Buttons to the direction of the text (_e.g._,
left-aligned in English) for easy scannability.

When moving customers through a sequence, place the primary Button in
the direction of the movement (e.g., a “Next” Button goes on the
right in an English-language flow).
## Do and don't

<DoDont>
<Do
Expand Down
9 changes: 5 additions & 4 deletions packages/paste-website/src/pages/components/popover/index.mdx
View file
Expand Up @@ -363,12 +363,13 @@ To internationalize the Popover, pass different text as children to the Popover'

---

## When to use Popover
## Composition notes

Use Popovers to:
Use a Popover to present supplemental information with interactive elements, like an [Anchor](/components/anchor). Information in a Popover should never be essential to task completion.

- Present supplemental, interactive information on top of the UI that's not essential to completing a task, but is contextual.
- Allow a user to input information for in-context editing.
Popover content should use full sentences and punctuation. Titles are optional.

## Do and don't

<DoDont>
<Do
Expand Down

0 comments on commit e770583

Please sign in to comment.