From 7ffc6d3269d5387f95cb3786c69c2cf92aef7196 Mon Sep 17 00:00:00 2001 From: Shadi Date: Fri, 16 Aug 2019 10:41:11 -0700 Subject: [PATCH] fix(website): add button docs (#51) * fix(website): add button docs * fix: add storybook to anchor and header * fix: link line break --- .../shortcodes/component-header/index.tsx | 10 +- .../src/pages/components/anchor/index.mdx | 7 + .../src/pages/components/button/index.mdx | 222 +++++++++++++++++- .../src/pages/components/index.mdx | 21 +- 4 files changed, 238 insertions(+), 22 deletions(-) diff --git a/packages/paste-website/src/components/shortcodes/component-header/index.tsx b/packages/paste-website/src/components/shortcodes/component-header/index.tsx index 50cea40354..3d50b6839f 100644 --- a/packages/paste-website/src/components/shortcodes/component-header/index.tsx +++ b/packages/paste-website/src/components/shortcodes/component-header/index.tsx @@ -19,10 +19,15 @@ const ComponentHeaderBasic: React.FC<{name: string}> = ({name}) => ( ); +const ExternalLink = styled.a` + margin-right: ${themeGet('space.space20')}; +`; + interface ComponentHeaderProps { children?: React.ReactElement; name: string; githubUrl: string; + storybookUrl: string; data?: [ { node: { @@ -50,7 +55,7 @@ const PackageLabel = styled.dt(getPackageItemStyles, { width: '80px', }); -const ComponentHeader: React.FC = ({name, githubUrl, data}) => { +const ComponentHeader: React.FC = ({name, githubUrl, storybookUrl, data}) => { if (data == null || data[0] == null || data[0].node == null) { return ; } @@ -72,7 +77,8 @@ const ComponentHeader: React.FC = ({name, githubUrl, data} Sources - Github + Github + {storybookUrl != null ? Storybook : null} diff --git a/packages/paste-website/src/pages/components/anchor/index.mdx b/packages/paste-website/src/pages/components/anchor/index.mdx index 4de1bd2d00..ebb4bb8373 100644 --- a/packages/paste-website/src/pages/components/anchor/index.mdx +++ b/packages/paste-website/src/pages/components/anchor/index.mdx @@ -26,6 +26,7 @@ export const pageQuery = graphql` @@ -119,6 +120,12 @@ import {Anchor} from '@twilio-paste/anchor'; `} + +### Storybook + +[View Anchor in Storybook](https://twilio-labs.github.io/paste/?path=/story/components-anchor--default) + + ### Props | Prop | Type | Description | Default | diff --git a/packages/paste-website/src/pages/components/button/index.mdx b/packages/paste-website/src/pages/components/button/index.mdx index 0f2b9e3403..2734569098 100644 --- a/packages/paste-website/src/pages/components/button/index.mdx +++ b/packages/paste-website/src/pages/components/button/index.mdx @@ -6,6 +6,7 @@ description: Buttons are hot import {graphql} from 'gatsby'; import {Button} from '@twilio-paste/button'; +import {DoDont, Do, Dont} from '../../../components/DoDont'; export const pageQuery = graphql` { @@ -25,16 +26,225 @@ export const pageQuery = graphql` -## Installation + +## Guidelines + +### About buttons + +A button communicates that users can trigger an action. Places you’d use +a button include: +* Submitting a form +* 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. + + +### Button vs. Anchor (Link) + +**TL;DR** If pressing the trigger results in a URL change, or that resultant +page makes sense as a whole new browser tab use an **Anchor** element. +Everything else is a **Button**. + +It may not be immediately obvious but the semantic distinction between an +anchor and button HTML element is extremely important to learn. Without +realising it the decision can cause significant usability problems due to +the in-built behaviours, interactions and expectations that come with each. + +For example, an anchor element will perform its action when clicked and +when the enter key is pressed. A button element will perform its action +when clicked and when the enter and spacebar keys are pressed. When +holding the control or command key an anchor will open a new browser +tab, a button will not. + + +You should: + +* Use an **Anchor** when you are **navigating the user** to a new page or +place on the page +* Use a **Button** when the user is **performing an action**. An action always +happens on the same page as the trigger + +If you need to link to content, you can use our [Anchor component](/components/anchor). + + +### Accessibility + +For accessibility, the distinction becomes even more important, +especially for those who are using Assistive Technology (A.T.) such as +screen readers and dictation software. Here are some quick tips: + +* Correctly choosing between an anchor or button element will help inform A.T. +users what will happen next. Will I be taken to an entirely new page or will +something happen on the current page? +* Choose button text that clearly describes the action that is about to happen +* Don’t repeat the same button text on the same page. Try not to have 20 +“edit” buttons, add clarifying text, even if it’s visually hidden, to +fully describe the action. E.g. “edit home address”, “add new phone number” +* Don’t communicate with color alone. When choosing a destructive button, +make sure the button text also indicates the action is destructive +* Try not to use anchors that look like buttons. Voice dictation users will +struggle with these as they may say “click button” but the software can’t +tell what the anchor looks like visually + +### Examples + + + + {`
+ + + + + + + + + + + +
`} + + + +##### Primary button +Use a primary button to indicate the most prominent action a customer would +make on a screen. It should be a safe and if possible, reversible action +without much cost. + +Try to use only one primary button on a screen. Using multiple might be +distracting. + + +##### Secondary button +The secondary button is the most frequently used button. + +Use a secondary button to indicate an action that should be easy for a customer +to make but isn’t the most prominent on a screen. It should be a safe and if +possible, reversible action without much cost. + +##### Destructive button +A destructive button indicates a destructive action, such as “Delete” or +“Remove”, that might be difficult to reverse. If possible, give users +the ability to undo the action, or at least, confirm the action. + +##### Icon-only button +Use icon-only buttons sparingly. + +They should be used only in compact UI situations. Use an icon that can +only convey a single action. + +##### Link-style button +Use link-style buttons when other types of buttons may be too distracting. + +##### Small button +Use small buttons sparingly, only when needed for vertical density. +Guidelines for using variants in small buttons are the same as in +their default size. + + +### States + +##### Loading +Use the loading state if the action doesn’t happen instantly. +The button is also disabled in this state. + +However, the loading state may make an action appear to take longer +than it does and doesn’t communicate what’s preventing the action +from completing. Use it when you can’t move the user to the next state. + +##### Disabled +Use the disabled state sparingly. + +The customer shouldn't have to guess why a button is disabled. +It should be immediately obvious to the customer why a button +might be disabled (*e.g.*, if it follows a single empty text +field). Otherwise, show the button in its default state, then +provide helpful error text after it's pressed. + + + +### Composing a button +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. +* 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. + + +### When to use a button +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). + + + + + Prioritize actions on a screen. Only one primary button should be used + on each screen so users are clear about what the intended action is. + + + Don’t use many primary buttons on a screen, which may distract users. + + + + + + Use the right variant to communicate meaning and hierarchy. + + + Don’t use a button variant for an action it’s not intended for. + + + + + + + Write button text that is clear, starts with a verb, and + helps users confidently trigger an action. + + + Don’t use product or brand icons in buttons since they don’t communicate action. + + + + + +## API + +### Installation ```bash yarn add @twilio-paste/button ``` -## Usage +### Usage ```jsx import {Button} from '@twilio-paste/button'; @@ -44,11 +254,9 @@ import {Button} from '@twilio-paste/button'; ``` - - {``} - +### Storybook + +[View Button in Storybook](https://twilio-labs.github.io/paste/?path=/story/components-button--text-only) ### Props diff --git a/packages/paste-website/src/pages/components/index.mdx b/packages/paste-website/src/pages/components/index.mdx index 71fdb41ccc..c70b0808cb 100644 --- a/packages/paste-website/src/pages/components/index.mdx +++ b/packages/paste-website/src/pages/components/index.mdx @@ -18,19 +18,14 @@ import {Breadcrumb, BreadcrumbItem} from '../../components/breadcrumb'; Components -

- The components listed here are on our roadmap. Only a few of them are available today. -

- -

- If you’re planning on using an alpha or beta component, please check in with the Paste team through the #help-design-system channel on Slack. -

- -

- Don't see a component you need listed here? Create an issue on GitHub, and we'll evaluate it. Not all component - requests are accepted for the design system. We’ll have guidelines soon for what to do if your component isn’t - supported. -

+The components listed here are on our roadmap. Only a few of them are available today. + +If you’re planning on using an alpha or beta component, please check in with the Paste team through the #help-design-system channel on Slack. + +Don't see a component you need listed here? [Create an issue on GitHub](https://github.com/twilio-labs/paste/issues), and we'll evaluate it. Not all component +requests are accepted for the design system. We’ll have guidelines soon for what to do if your component isn’t +supported. +