From 6ad3f5f2cc3930399356adcb71a037a0a5ba9eac Mon Sep 17 00:00:00 2001 From: Alison Joseph Date: Thu, 19 Dec 2024 11:44:09 -0600 Subject: [PATCH] chore:format --- src/pages/components/button/style.mdx | 18 ++-- src/pages/components/button/usage.mdx | 139 +++++++++++++------------- 2 files changed, 80 insertions(+), 77 deletions(-) diff --git a/src/pages/components/button/style.mdx b/src/pages/components/button/style.mdx index 976ba95e757..41a42a99c28 100755 --- a/src/pages/components/button/style.mdx +++ b/src/pages/components/button/style.mdx @@ -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 @@ -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` | diff --git a/src/pages/components/button/usage.mdx b/src/pages/components/button/usage.mdx index 74de66c1451..88f03a06a7c 100755 --- a/src/pages/components/button/usage.mdx +++ b/src/pages/components/button/usage.mdx @@ -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 | | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -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. @@ -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. | @@ -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 @@ -275,10 +277,10 @@ button locations include: Alignment of buttons across various layouts. -| 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 @@ -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) - - Login screen using a fluid input field and a fluid button. - +Login screen using a fluid input field and a fluid button. @@ -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. @@ -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 @@ -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 {verb} + {noun} content formula on @@ -676,8 +676,7 @@ We do not recommend changing the label of the button to show a state change. - Icon only copy button of code snippet conveying validation through - a tooltip. + Icon only copy button of code snippet conveying validation through a tooltip. ### Loading @@ -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. @@ -760,8 +759,8 @@ tertiary and ghost buttons for these supporting actions or experiences. - 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. ## Secondary button @@ -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 @@ -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. @@ -956,7 +956,9 @@ on the page. -Example of a ghost button aligned horizontally and inline with a component. + + Example of a ghost button aligned horizontally and inline with a component. + ### Best practices @@ -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. @@ -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. @@ -1126,12 +1128,12 @@ recognized icons within IBM Software and beyond. | Stop | | Stop outline | | Refresh | | 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 @@ -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. @@ -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. @@ -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.