Skip to content

Commit

Permalink
chore:format
Browse files Browse the repository at this point in the history
  • Loading branch information
@alisonjoseph
alisonjoseph committed Dec 19, 2024
1 parent 6505681 commit 6ad3f5f
Show file tree
Hide file tree
Showing 2 changed files with 80 additions and 77 deletions.
18 changes: 9 additions & 9 deletions src/pages/components/button/style.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -447,12 +447,12 @@ and any proper nouns capitalized.

## Structure

Primary, Secondary, Tertiary, Danger Primary and Danger tertiary button
follows the same structure measurements. A button cannot have any element
or text within 16 pixels / 1 rem of its borders. For a button with a glyph,
the space between the button label and the glyph must be greater than or
equal to 16 pixels / 1 rem. This is to accommodate for instances where two
or more buttons with glyphs appear together.
Primary, Secondary, Tertiary, Danger Primary and Danger tertiary button follows
the same structure measurements. A button cannot have any element or text within
16 pixels / 1 rem of its borders. For a button with a glyph, the space between
the button label and the glyph must be greater than or equal to 16 pixels / 1
rem. This is to accommodate for instances where two or more buttons with glyphs
appear together.

### Button structure

Expand Down Expand Up @@ -481,10 +481,10 @@ or more buttons with glyphs appear together.

Ghost and Danger ghost button follow the same structure measurements.

| Element | Property | px / rem | Spacing token |
| ------------------------- | ---------------------------- | -------- | ------------- |
| Element | Property | px / rem | Spacing token |
| ------------------------- | --------------------------- | -------- | ------------- |
| Ghost button without icon | padding-left, padding-right | 16 / 1 | `$spacing-05` |
| Ghost button with icon | spacing | 8 / 0.5 | `$spacing-03` |
| Ghost button with icon | spacing | 8 / 0.5 | `$spacing-03` |
| Ghost icon only button | padding-left, padding-right | 16 / 1 | `$spacing-05` |

<Row>
Expand Down
139 changes: 71 additions & 68 deletions src/pages/components/button/usage.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -119,8 +119,9 @@ desired action is to take the user to a new page.
### Variants

Each button variant has a particular function and its design signals that
function to the user. It is, therefore, very important that the different variants
are implemented consistently across productsto convey the correct actions.
function to the user. It is, therefore, very important that the different
variants are implemented consistently across productsto convey the correct
actions.

| Variant | Purpose |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
Expand All @@ -135,9 +136,9 @@ are implemented consistently across productsto convey the correct actions.
### Anatomy

A button’s label is the most important element on a button, as it communicates
the action that will be performed when the user interacts with it. In a
button the label is always left-aligned, not center-aligned. By default
Carbon uses sentence case for all button labels.
the action that will be performed when the user interacts with it. In a button
the label is always left-aligned, not center-aligned. By default Carbon uses
sentence case for all button labels.

If a label is not used, an icon should be present to signify what the button
does.
Expand Down Expand Up @@ -190,7 +191,7 @@ and tokens, see [Sizes](/components/button/style#sizes.mdx) on the Style tab.
| Medium | Use when buttons are paired with 40px medium sized input fields. |
| Large (productive) | This is the most common button size. Use 14px body copy. |
| Large (expressive) | The larger expressive type size within this button provides balance when used with 16px body copy. Used by the IBM.com team in website banners. |
| Extra large | Use when buttons bleed to the edge of a larger component, like in the context of modals, side panel and narrow tearsheets. |
| Extra large | Use when buttons bleed to the edge of a larger component, like in the context of modals, side panel and narrow tearsheets. |
| 2XL | Use when buttons bleed to the edge of a larger component, like in the context of large tearsheets. |

<Row>
Expand All @@ -205,14 +206,15 @@ and tokens, see [Sizes](/components/button/style#sizes.mdx) on the Style tab.

### Emphasis

You don’t necessarily need to use the buttons in the order that their labels
imply. Although secondary buttons have less visual prominence because they are
less saturated than their primary counterparts, they are still tonally heavy.
If your layout requires multiple actions—as is the case with some toolbars,
data lists and dashboards—low emphasis buttons (tertiary or ghost) may be a
better choice.
You don’t necessarily need to use the buttons in the order that their labels
imply. Although secondary buttons have less visual prominence because they are
less saturated than their primary counterparts, they are still tonally heavy. If
your layout requires multiple actions—as is the case with some toolbars, data
lists and dashboards—low emphasis buttons (tertiary or ghost) may be a better
choice.

The most important thing is to establish a visual hierarchy between the buttons in your UI. Keep these best practices in mind.
The most important thing is to establish a visual hierarchy between the buttons
in your UI. Keep these best practices in mind.

#### A single, high-emphasis button

Expand Down Expand Up @@ -275,10 +277,10 @@ button locations include:

<Caption>Alignment of buttons across various layouts.</Caption>

| Alignment | Use case |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Left-justified | Banner call to actions, in-page forms, and nested buttons in components like tiles. |
| Right-justified | Inline notifications, inline field buttons and data tables, progressive forms, wizards, and single-button dialogs. |
| Alignment | Use case |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Left-justified | Banner call to actions, in-page forms, and nested buttons in components like tiles. |
| Right-justified | Inline notifications, inline field buttons and data tables, progressive forms, wizards, and single-button dialogs. |
| Full-span | Dialogs, side panel, and small tiles; currently Carbon does not offer a way to implement full-span buttons in code, without an override, they max out at 320px. |

#### Fixed versus fluid buttons
Expand All @@ -305,9 +307,7 @@ container—they’re either right-aligned or span the full width of the contain

![Login screen using a fluid input field and a fluid button.](images/button_usage_11.png)

<Caption>
Login screen using a fluid input field and a fluid button.
</Caption>
<Caption>Login screen using a fluid input field and a fluid button.</Caption>

</Column>
</Row>
Expand All @@ -327,10 +327,10 @@ container—they’re either right-aligned or span the full width of the contain

#### Fluid button border

There is [a 1px border](/components/button/style#ghost-button-structure.mdx)
between all fluid buttons that use the `$button-separator` token for
borders. This feature adds a 3:1 distinction between the two interactive
UI elements. The border is a recommended feature to improve accessibility.
There is [a 1px border](/components/button/style#ghost-button-structure.mdx)
between all fluid buttons that use the `$button-separator` token for borders.
This feature adds a 3:1 distinction between the two interactive UI elements. The
border is a recommended feature to improve accessibility.

<Row>
<Column colLg={8}>
Expand Down Expand Up @@ -483,8 +483,8 @@ revised our position.

Typical landing pages for product have buttons side by side. However vertical
button groups are also common in products, to save real estate in narrow columns
and occasionally side panel. In these instances, the primary button is always
on top and the secondary or tertiary button is below.
and occasionally side panel. In these instances, the primary button is always on
top and the secondary or tertiary button is below.

Generally, when designers stack buttons, they tend to use the hybrid fluid
buttons. However, stacked fluid buttons are also an option in desktop side
Expand Down Expand Up @@ -519,9 +519,9 @@ button style.

#### Button label

A button’s label is the most important element on a button, as it
communicates the action that will be performed when the user interacts with it.
Buttons need to be clear and predictable.
A button’s label is the most important element on a button, as it communicates
the action that will be performed when the user interacts with it. Buttons need
to be clear and predictable.

Button labels should clearly indicate the action of the button. To provide
enough context, use the &#123;verb&#125; + &#123;noun&#125; content formula on
Expand Down Expand Up @@ -676,8 +676,7 @@ We do not recommend changing the label of the button to show a state change.
</Row>

<Caption>
Icon only copy button of code snippet conveying validation through
a tooltip.
Icon only copy button of code snippet conveying validation through a tooltip.
</Caption>

### Loading
Expand Down Expand Up @@ -727,7 +726,7 @@ primary button. Temporarily, there may be two primary buttons on a page.

In this case, a user has triggered something with an intention to focus on
another flow, therefore temporarily having two primary buttons on a page is
acceptable. This is the only scenario where having two primary actions on a page
acceptable. This is the only scenario where having two primary actions on a page
is advised.

<Row>
Expand Down Expand Up @@ -760,8 +759,8 @@ tertiary and ghost buttons for these supporting actions or experiences.
</Row>

<Caption>
The primary intent of this page is to present content, with actions like filtering
and editing represented by tertiary and ghost buttons.
The primary intent of this page is to present content, with actions like
filtering and editing represented by tertiary and ghost buttons.
</Caption>

## Secondary button
Expand Down Expand Up @@ -839,9 +838,10 @@ fluid arrangements.

It is challenging to use a primary button in the header of a page because the
content beneath the header is probably going to have a primary action, or will
in a future release. Even if the the button in the page header is not styled as
a primary button, it has significant prominence due to its hierarchical placement
at the top.. Therefore, it is advised to use a tertiary button for page headers.
in a future release. Even if the the button in the page header is not styled as
a primary button, it has significant prominence due to its hierarchical
placement at the top.. Therefore, it is advised to use a tertiary button for
page headers.

If it is determined that the button in the page header, across all tabs, should
be primary, ensure none of the content below the header contain another primary
Expand Down Expand Up @@ -910,7 +910,7 @@ elements.
#### Aligning ghost buttons

Ghost buttons work well when aligned to a corner of a container. The general
rule for vertically aligning a ghost button with other content is to ensure its
rule for vertically aligning a ghost button with other content is to ensure its
label aligns with the text elsewhere on the page.

<DoDontRow>
Expand Down Expand Up @@ -956,7 +956,9 @@ on the page.
</Column>
</Row>

<Caption>Example of a ghost button aligned horizontally and inline with a component.</Caption>
<Caption>
Example of a ghost button aligned horizontally and inline with a component.
</Caption>

### Best practices

Expand Down Expand Up @@ -1027,10 +1029,10 @@ The danger button has three different styles:
[tertiary](/components/button/style#danger-tertiary-button-color.mdx), and
[ghost](/components/button/style#danger-ghost-button-color.mdx). Determining
which danger button style to use will depend on the level of emphasis you want
to give to the destructive action. Destructive actions that are a required or
primary step in a workflow should use the primary danger button style. However,
if a destructive action is just one of several actions a user could choose from,
then a lower emphasis style like the tertiary danger button or the ghost danger
to give to the destructive action. Destructive actions that are a required or
primary step in a workflow should use the primary danger button style. However,
if a destructive action is just one of several actions a user could choose from,
then a lower emphasis style like the tertiary danger button or the ghost danger
button may be more appropriate.

<Row>
Expand Down Expand Up @@ -1060,11 +1062,11 @@ button may be more appropriate.

### Button with icon

Icons can be placed next to labels to clarify an action and call attention
to a button. However, icons should be used sparingly, as overuse can create
visual noise and make an experience less usable. If you use a button with
an icon in one part of your UI it does not mean that you need to add icons to
all other buttons.
Icons can be placed next to labels to clarify an action and call attention to a
button. However, icons should be used sparingly, as overuse can create visual
noise and make an experience less usable. If you use a button with an icon in
one part of your UI it does not mean that you need to add icons to all other
buttons.

- Use 16px glyphs within buttons; use 20px glyphs within the large expressive
buttons.
Expand Down Expand Up @@ -1126,12 +1128,12 @@ recognized icons within IBM Software and beyond.
| Stop | <StopOutline size={16} aria-label="Stop outline"/> | Stop outline |
| Refresh | <Restart size={16} aria-label="Restart"/> | Restart |

Do you think a universal action with a clearly defined icon is missing? Let us
Do you think a universal action with a clearly defined icon is missing? Let us
know [here](https://github.com/carbon-design-system/carbon/issues/new/choose).

Icons that are not in this list can be used in buttons, as long as the
icon clearly conveys the intended action. To determine the expected use of an
icon, check its name in the
Icons that are not in this list can be used in buttons, as long as the icon
clearly conveys the intended action. To determine the expected use of an icon,
check its name in the
[Carbon icon library](https://carbondesignsystem.com/elements/icons/library/).

#### Do not use a defined icon to represent a different universal action
Expand All @@ -1157,9 +1159,9 @@ and experience.
The launch icon should be used on any call to action that launches the user into
another tab (whether the content of the new tab is part of the same product or
an entirely separate web resource). Buttons and links requiring the launch icon
are often found in the UI left navigation area, side panel, cards, and modals.
The target destination of the launch action should be made clear to the user
through the button or link label and the surrounding context. For more guidance,
are often found in the UI left navigation area, side panel, cards, and modals.
The target destination of the launch action should be made clear to the user
through the button or link label and the surrounding context. For more guidance,
see [this section](https://pages.github.ibm.com/carbon/ibm-products/guidelines/content/navigation-labels/) 
of our content guide.

Expand Down Expand Up @@ -1219,10 +1221,10 @@ associated.

#### Use the default variation for all icons

The Carbon library contains filled variants of a few icons. Since not every
icon has this variation, we advise using the default option for all icons
(the only exception is status icons, which have their own defined icon to use).
Default icons are named after their action.
The Carbon library contains filled variants of a few icons. Since not every icon
has this variation, we advise using the default option for all icons (the only
exception is status icons, which have their own defined icon to use). Default
icons are named after their action.

<DoDontRow>
<DoDont type="do" caption="Do use the default icon which is “Play”.">
Expand All @@ -1239,21 +1241,22 @@ Default icons are named after their action.

### Icon only buttons

Icon only buttons allow users to take actions, and make choices, with a
single tap. Icon buttons can take the form of a primary, secondary, tertiary,
or ghost variant but most commonly will be styled as primary or ghost buttons.
Icon only buttons allow users to take actions, and make choices, with a single
tap. Icon buttons can take the form of a primary, secondary, tertiary, or ghost
variant but most commonly will be styled as primary or ghost buttons.

Icon only buttons should be used sparingly. “For most situations, users learn
correct interpretations better with text alone than with icons alone.” —
Wiedenbeck, S (1999). For this reason, using icon-only buttons is recommended
for the following use cases.

- The icon must be standardized and recognizable without text or must represent
an action with a strong visual attribute, such as a pin icon for a pinning action.
- There is insufficient space and multiple actions, therefore a
toolbar using icon buttons is required. See
the [toolbars pattern](https://pages.github.ibm.com/cdai-design/pal/patterns/toolbars)
for more details.
- The icon must be standardized and recognizable without text or must represent
an action with a strong visual attribute, such as a pin icon for a pinning
action.
- There is insufficient space and multiple actions, therefore a toolbar using
icon buttons is required. See
the [toolbars pattern](https://pages.github.ibm.com/cdai-design/pal/patterns/toolbars)
for more details.

<Row>
<Column colLg={8}>
Expand Down

0 comments on commit 6ad3f5f

Please sign in to comment.