Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updated notification/usage.mdx with content-focused edits #4434

Open
wants to merge 12 commits into
base: main
Choose a base branch
from
Prev Previous commit
Next Next commit
:chore: format
  • Loading branch information
alisonjoseph committed Jan 22, 2025
commit 14bb32e3ec7bd9db5ae8a836a6d1380c81dafda3
Original file line number Diff line number Diff line change
@@ -70,6 +70,10 @@
height: 100%;
}

.table .cell :global(.cds--snippet) {
margin-right: $spacing-03;
}

.descriptionCell {
min-width: 240px;
}
18 changes: 16 additions & 2 deletions src/components/StatusIndicatorTable/StatusIndicatorRow.js
Original file line number Diff line number Diff line change
@@ -1,6 +1,10 @@
import React from 'react';
import cx from 'classnames';
import { StructuredListRow, StructuredListCell } from '@carbon/react';
import {
CodeSnippet,
StructuredListRow,
StructuredListCell,
} from '@carbon/react';
import {
icon,
iconGroup,
@@ -49,6 +53,7 @@ const StatusIndicatorRow = ({
fileNames,
name,
token,
secondarytoken,
description,
usage,
}) => {
@@ -78,7 +83,16 @@ const StatusIndicatorRow = ({
</StatusIconWrapper>
</StructuredListCell>
<StructuredListCell className={cell}>{name}</StructuredListCell>
<StructuredListCell className={cell}>{token}</StructuredListCell>
<StructuredListCell className={cell}>
<CodeSnippet type="inline" feedback="Copied!">
{token}
</CodeSnippet>
{secondarytoken && (
<CodeSnippet type="inline" feedback="Copied!">
{secondarytoken}
</CodeSnippet>
)}
</StructuredListCell>
<StructuredListCell className={cx(cell, descriptionCell)}>
{description}
<br />
1 change: 1 addition & 0 deletions src/data/status-indicators/status-indicators.yaml
Original file line number Diff line number Diff line change
@@ -11,6 +11,7 @@ high:
- warning-filled
- warning-outline
token: $support-error
secondarytoken: $test
description:
Indicates an error (often inline) that needs immediate attention
usage: warnings, errors, alerts, failure
4 changes: 2 additions & 2 deletions src/pages/components/code-snippet/style.mdx
Original file line number Diff line number Diff line change
@@ -17,8 +17,8 @@ tabs: ['Usage', 'Style', 'Code', 'Accessibility']
| Copy button | See [ghost button - icon only](/components/button/style#ghost-button) | |
| Container:focus | border | `$focus` |

<Caption>
* Denotes a contextual color token that will change values based on the layer
<Caption fullWidth>
\* Denotes a contextual color token that will change values based on the layer
it is placed on.
</Caption>

111 changes: 57 additions & 54 deletions src/pages/components/notification/usage.mdx
Original file line number Diff line number Diff line change
@@ -81,12 +81,12 @@ although some product teams also support banners and notification centers.

### Variants

| Variant | Purpose |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Inline](#inline) | Inline notifications show up in task flows, to notify users of the status of an action. They usually appear at the top of the primary content area. |
| Variant | Purpose |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Inline](#inline) | Inline notifications show up in task flows, to notify users of the status of an action. They usually appear at the top of the primary content area. |
| [Toast](#toast) | Toast notifications are non-modal, time-based window elements used to display short messages; they usually appear at the top of the screen and disappear after a few seconds. |
| [Actionable](#actionable) | Actionable notifications allow for interactive elements within a notification styled like an inline or toast notification. |
| [Callout](#callout) | Callouts are used to highlight important information that loads with the contents of the page, is placed contextually, and cannot be dismissed. |
| [Actionable](#actionable) | Actionable notifications allow for interactive elements within a notification styled like an inline or toast notification. |
| [Callout](#callout) | Callouts are used to highlight important information that loads with the contents of the page, is placed contextually, and cannot be dismissed. |

### Feature flags

@@ -172,32 +172,32 @@ take action and, therefore, does not include success or error statuses.
## Content

Notifications provide limited space for content and, therefore, the content must
be short and concise. Follow the guidance in
[IBM Style - Messages](https://ibmdocs-test.dcs.ibm.com/docs/en/ibm-style?topic=format-messages)
and write the message so the user can, by scanning the notification, be
apprised of the situation and quickly know what to do next.
be short and concise. Follow the guidance in
[IBM Style - Messages](https://ibmdocs-test.dcs.ibm.com/docs/en/ibm-style?topic=format-messages)
and write the message so the user can, by scanning the notification, be apprised
of the situation and quickly know what to do next.

### Main elements

#### Title

- The title should be short and descriptive, explaining the most important piece
of information. For error messages, tell users what stopped or can't be done in
the title, for example “Server instance unavailable”.
of information. For error messages, tell users what stopped or can't be done
in the title, for example “Server instance unavailable”.
- Don't use a period to end a title.
- When using rich text, such as in a title, a screen reader will read aloud the
entire message as one sentence. Because the message will be read as one string,
do not depend on text styling to convey meaning.
entire message as one sentence. Because the message will be read as one
string, do not depend on text styling to convey meaning.

#### Body content

- Be concise; limit the content to one or two short sentences.
- Don't repeat or paraphrase the title.
- Explain how to resolve the issue by including any troubleshooting actions or
next steps. This is what IBM Style calls the “user action”.
User actions are mandatory for error messages.
- When possible, use an actionable notification and include links in the notification
body that redirect the user to where they resolve the problem.
next steps. This is what IBM Style calls the “user action”. User actions are
mandatory for error messages.
- When possible, use an actionable notification and include links in the
notification body that redirect the user to where they resolve the problem.

#### Action button

@@ -216,8 +216,8 @@ apprised of the situation and quickly know what to do next.

If a toast or inline notification requires a message longer than two lines, use
an actionable notification and include a short message with a “View more” link
that takes the user to a view of the full notification message. The target of the “View more” link can be
either a full page with more details or a modal.
that takes the user to a view of the full notification message. The target of
the “View more” link can be either a full page with more details or a modal.

### Further guidance

@@ -227,8 +227,8 @@ For further content guidance, see Carbon's
## Inline

Inline notifications show up in task flows to notify users of the status of an
action or system. Inline notifications usually appear at the top of the primary content area or
close to the item needing attention.
action or system. Inline notifications usually appear at the top of the primary
content area or close to the item needing attention.

### Inline formatting

@@ -252,9 +252,9 @@ Inline notifications appear near their related items. They can expand to fill
the width of the container or content area they are in and should align to the
grid columns.

Place inline notifications at the bottom of forms, just above the
submission and cancel buttons. When error notifications apply to individual text
inputs, they should supplement the error state on that specific input field.
Place inline notifications at the bottom of forms, just above the submission and
cancel buttons. When error notifications apply to individual text inputs, they
should supplement the error state on that specific input field.

<Row>
<Column colLg={8}>
@@ -279,8 +279,9 @@ critical for a user to read or interact with the notification.

## Toast

Toast notifications are non-modal, time-based window elements used to display short messages;
they usually appear at the top of the screen and disappear after a few seconds.
Toast notifications are non-modal, time-based window elements used to display
short messages; they usually appear at the top of the screen and disappear after
a few seconds.

### Toast formatting

@@ -296,9 +297,10 @@ they usually appear at the top of the screen and disappear after a few seconds.

Toast notifications can include a time stamp at the bottom the container. The
time stamp shows the time the notification was sent. Using time stamps is
optional but toast notifications should be consistent across the product so either all
toast notifications should include time stamps or none of them should. The time stamp is optional
and can be removed if a third line of content is needed.
optional but toast notifications should be consistent across the product so
either all toast notifications should include time stamps or none of them
should. The time stamp is optional and can be removed if a third line of content
is needed.

#### Sizing

@@ -328,25 +330,25 @@ dismissed.

### Dismissal

Toast notifications persist by default, but they can timeout and be coded to
Toast notifications persist by default, but they can timeout and be coded to
dismiss automatically after five seconds on the screen. They can also include a
close button so users can dismiss them sooner. Toast notifications cover content on the
screen so they should always be easily dismissed. Because toast notifications
can dismiss automatically, users should be able to access them elsewhere after
the toast notification disappears if they need more time to read the notification
or who want to refer to it later.
close button so users can dismiss them sooner. Toast notifications cover content
on the screen so they should always be easily dismissed. Because toast
notifications can dismiss automatically, users should be able to access them
elsewhere after the toast notification disappears if they need more time to read
the notification or who want to refer to it later.

## Actionable

Actionable notifications are inline or toast notifications that have interactive elements.
Because actionable notifications require user interaction, actionable notifications come
into focus when triggered and, therefore, they disrupt screen readers and keyboard users.
Only oe action is allowed for each notification, and this action frequently takes users
to a flow or page related to the message where they can resolve the
notification.
Actionable notifications are inline or toast notifications that have interactive
elements. Because actionable notifications require user interaction, actionable
notifications come into focus when triggered and, therefore, they disrupt screen
readers and keyboard users. Only oe action is allowed for each notification, and
this action frequently takes users to a flow or page related to the message
where they can resolve the notification.

Consider using a notification center where a user can revisit and
act on past notifications.
Consider using a notification center where a user can revisit and act on past
notifications.

### Formatting

@@ -360,9 +362,9 @@ notification.
#### Toast

Actionable toast notifications can include a tertiary button at the end of their
body content. This button should be short and should take users to a page or modal
where they can take action to address the notification or find further
information. Because toast notifications automatically dismiss, ensure there are
body content. This button should be short and should take users to a page or
modal where they can take action to address the notification or find further
information. Because toast notifications automatically dismiss, ensure there are
alternative routes to navigate to the link destination.

<Row>
@@ -379,12 +381,12 @@ alternative routes to navigate to the link destination.

### Dismissal

Actionable notifications persist until a user dismisses them. If
you're using inline styling, refer to [inline notifications](#inline-notifications) for
inline dismissal. If you're using toast-notification style for an actionable notification,
the notification should remain on screen until the user dismisses it. Because the
notification remains open, the user has enough time to interact with the
button without the toast closing too soon. For more information, see
Actionable notifications persist until a user dismisses them. If you're using
inline styling, refer to [inline notifications](#inline-notifications) for
inline dismissal. If you're using toast-notification style for an actionable
notification, the notification should remain on screen until the user dismisses
it. Because the notification remains open, the user has enough time to interact
with the button without the toast closing too soon. For more information, see
[toast notifications](#toast-notifications).

### Links
@@ -395,8 +397,9 @@ actionable notification can be used to redirect the user to next steps.
### Actions

If needed, actionable notifications can include a ghost button for inline
notifications or a tertiary button for toast notificationss. These action buttons enable users
to address the notification or navigate to a page for more details.
notifications or a tertiary button for toast notificationss. These action
buttons enable users to address the notification or navigate to a page for more
details.

## Callout

Loading