From adbf7a169f71706f52663b0187e84766f5c65004 Mon Sep 17 00:00:00 2001 From: Sean Nelson <139248410+partlysean44@users.noreply.github.com> Date: Thu, 3 Aug 2023 13:51:19 -0500 Subject: [PATCH] docs: Expanded button documentation (#440) * docs(button): Expanded button documentation to include more examples and content guidelines * Create violet-flowers-doubt.md * Revert "docs(button): Expanded button documentation to include more examples and content guidelines" This reverts commit 2f11d5df95a9e82bf72dd6d8740cc70b5e77b7d9. * Revert "Revert "docs(button): Expanded button documentation to include more examples and content guidelines"" This reverts commit 1183bbf680b946ca20a244e9b7fae2ffa68e8d4b. * Removing my changes to these files * Update package.json --- .changeset/violet-flowers-doubt.md | 2 + apps/website/docs/actions/button.mdx | 115 ++++++++++++++++++++------- 2 files changed, 90 insertions(+), 27 deletions(-) create mode 100644 .changeset/violet-flowers-doubt.md diff --git a/.changeset/violet-flowers-doubt.md b/.changeset/violet-flowers-doubt.md new file mode 100644 index 000000000..a845151cc --- /dev/null +++ b/.changeset/violet-flowers-doubt.md @@ -0,0 +1,2 @@ +--- +--- diff --git a/apps/website/docs/actions/button.mdx b/apps/website/docs/actions/button.mdx index 70b0c9ec3..d9a1310da 100644 --- a/apps/website/docs/actions/button.mdx +++ b/apps/website/docs/actions/button.mdx @@ -1,91 +1,152 @@ --- title: Button -description: Clickable elements that communicate actions that users can take. +description: Buttons are clickable elements used for performing interface actions. sidebar_custom_props: status: 'production' --- -Clickable elements that communicate actions that users can take. +Buttons are clickable elements used for performing interface actions. Button labels let users know what will happen next. -```jsx live - -``` +:::note +Buttons are not links and should not be used for navigation. Buttons _do something_, links _go somewhere_. When you want to navigate a user to another page or website, use a [link](link). +::: -## Usage +## Appearance ### Primary -Primary buttons are used to indicate the highest priority action a user can perform. +Use a `primary` button variant to indicate the strongest call to action on a page. Primary buttons should appear only once per section. Not every page needs a primary button. + ```jsx live - + ``` ### Secondary -Secondary buttons are second in priority to primary buttons and are used for important actions that -aren't the primary action. +The `secondary` button should be the default button variant for most use cases. ```jsx live - + ``` ### Tertiary -Tertiary buttons are the lowest priority actions and should be used for less commonly used actions. +Use a `tertiary` button to deprioritize actions when placed next to secondary or primary buttons. Tertiary buttons may also be used to lessen visual distraction when a multitude of similar actions are being used, or when the button exists inside an element with little spacing. + +For example, a table that includes a download button in each row should use the `tertiary` variant. ```jsx live - + ``` -### Destructive +### Danger -Destructive buttons are used to indicate an action that is destructive and cannot be undone. +The `danger` variant is used to indicate an action that is destructive and cannot be undone. ```jsx live - + ``` ### Brand -Brand buttons are used for project44 specific marketing moments and should be use sparingly. +Use a `brand` button variant for project44 specific marketing moments. This should be used sparingly. ```jsx live - + ``` +## States + +### Disabled + +Use the `isDisabled` prop to disable a button that isn’t usable. Disabled buttons present a number of accessibility issues, particularly in forms, so they should be used sparingly. + +```jsx live + +``` + +## Sizing + ### Small -Small buttons are used when vertical spacing is limited. +Set the button size to `small` when vertical spacing is limited, like inside a table row. ```jsx live ``` +## Icons + ### Start Icon -Include an icon before the button label. +Use `startIcon` to include [icon](/core/icons) before the button label. ```jsx live - + ``` ### End Icon -Include an icon after the button label. +Use `endIcon` to include an [icon](/core/icons) after the button label. End icons should be used to imply _directionality_ to the button's action, like traversing pages in a table or revealing a menu under the button. ```jsx live - + ``` -### Disabled State +## Common configurations + +### Dropdown button -Set the `isDisabled` prop to prevent a user from pressing a button. +Create a dropdown button by adding the `ChevronDown` icon at the end. ```jsx live - + ``` +## Content guidelines + +Button labels should be concise and predictable. A user should understand what action will take place after clicking the button. When writing labels, start with a **verb** to imply action and add context with a supportive **noun**. + +:::tip Correct +View shipments +::: + +:::danger Incorrect +Shipments list +::: + +:::caution +Do not rely on an icon to stand in as a label's verb. +::: + + +### Sentence case + +Use sentence case, not title case, when writing button labels. Capitalize only the first word in a string, as well as any other words that require capitalization, like proper nouns, initialisms, or acronyms. + +We use sentence case because it's more conversational and makes it easier for users to distinguish between common nouns and proper nouns. + +:::tip Correct +Sign up +::: + +:::danger Incorrect +Sign Up +::: + +### Brevity + +Don't use long, redundant button labels and avoid unnecessary articles such as "a", "an", or "the" for a more concise label. + +:::tip Correct +Create user +::: + +:::danger Incorrect +Click here to create a new user +::: + ## Props - + \ No newline at end of file