ant-design/docs/spec/buttons.en-US.md

207 lines
8.4 KiB
Markdown
Raw Normal View History

---
docs: v5 site upgrade (#38328) * build: try to use dumi as doc tool * docs: migrate demo structure to dumi way * refactor: use type export & import * docs: migrate demo previewer to dumi * docs: create empty layout & components * docs: apply custom rehype plugin * docs: create empty extra pages * docs: Add Banner component * chore: move theme tsconfig.json * docs: home page init * docs: migrate header (#37896) * docs: header * docs: update * docs: home init * clean up * test: fix site lint * chore: tsc ignore demo * chore: dumi demo migrate script * chore: cards * docs: home layout * docs: Update locale logic * docs: fix getLink logic * chore: fix ci (#37899) * chore: fix ci * ci: remove check-ts-demo * ci: preview build * test: ignore demo.tsx * chore: update script * test: update snapshot * test: update node and image test * chore: add .surgeignore * docs: layout providers (#37908) * docs: add components sidebar (#37923) * docs: sidebar * docs: update docs title * docs: update design doc * chore: code clean * docs: handle changelog page * docs: add title * docs: add subtitle * docs: active header nav * chore: code clean * docs: overview * chore: code clean * docs: update intl (#37918) * docs: update intl * chore: code clean * docs: update favicons * chore: update testPathIgnorePatterns * chore: code clean * chore: code clean * chore: copy 404.html (#37996) * docs: Home page theme picker * chore: Update migrate script * docs: home page update * docs: theme editor style * docs: theme lang * chore: update migrate.js * docs: fix demo (#38094) * chore: update migrate.js * docs: update md * docs: update demo * test: fix snapshot * chore: move debug to code attr in migrate script * chore: update md Co-authored-by: PeachScript <scdzwyxst@gmail.com> * feat: overview page * feat: Migrate `404` page (#38118) * feat: migrate IconSearch component (#37916) * feat<site/IconSearch>: copy IconDisplay from site to .dumi * feat<site/IconSearch>: change docs of icon * feat<site/IconSearch>: tweak * feat<site/IconSearch>: use useIntl instead of injectIntl * feat<site/IconSearch>: fix ts type error * feat<site/IconSearch>: use intl.formatMessage to render text * docs: Adjust home btn sizw * docs: Update doc * feat: v5 site overview page (#38131) * feat: site * fix: fix * feat: v5 site overview page * fix: fix path * fix: fix * fix: fix * docs: fix margin logic * feat: v5 site change-log page (#38137) * feat: v5 site change-log page (#38162) * docs: site redirect to home pag * docs: theme picker * docs: use react-intl from dumi (#38183) * docs: Theme Picker * docs: update dumi config * docs: home back fix * docs: picker colorful * docs: locale of it * docs: update components desc * docs: site of links * docs: update components list * docs: update desc * feat: Migrate `DemoWrapper` component (#38166) * feat: Migrate `DemoWrapper` component * feat: remove invalid comments and add comment for `key` prop * docs: FloatButton pure panel * chore: update demo * chore: update dumi config * Revert "chore: update demo" This reverts commit 028265d3ba5987df5f13c3e9d42cf76cb1812b2e. * chore: test logic adjust to support cnpm modules * chore: add locale alias * docs: /index to / * docs: add locale redirect head script * chore: adjust compact * docs: fix missing token * feat: compact switch * chore: code clean * docs: update home * docs: fix radius token * docs: hash of it * chore: adjust home page * docs: Add background map * docs: site theme bac logic * docs: avatar * docs: update logo color * docs: home banner * docs: adjust tour size * docs: purepanl update * docs: transfooter * docs: update banner gif * docs: content (#38361) * docs: title & EditButton * docs: content * chore: fix toc * docs: resource page * docs: transform resource data from hast * docs: filename & Resource Card * chore: enable prerender * chore: remove less * docs: toc style * chore: fix lint * docs: fix Layout page * docs: fix CP page * chore: update demos * docs: workaround for export dynamic html * chore: enable demo eslint * docs: table style * fix: header shadow * chore: update snapshot * fix: toc style * docs: add title * docs: Adjust site * feat: helmet * docs: site css * fix: description * feat: toc debug * docs: update config-provider * feat: use colorPanel * fix: colorPanel value * feat: anchor ink ball style * feat: apply theme editor * fix: code block style * chore: update demo * chore: fix lint * chore: code clean * chore: update snapshot * feat: ts2js * chore: description * docs: site ready for ssr includes: - move client render logic to useEffect in site theme - extract antd cssinjs to a single css file like bisheng - workaround to support react@18 pipeableStream for emotion * chore: bump testing lib * docs: font size of title * chore: remove react-sortable-hoc * chore: update snapshot * chore: update script Co-authored-by: PeachScript <scdzwyxst@gmail.com> Co-authored-by: MadCcc <1075746765@qq.com> Co-authored-by: zqran <uuxnet@gmail.com> Co-authored-by: TrickyPi <530257315@qq.com> Co-authored-by: lijianan <574980606@qq.com>
2022-11-09 12:28:04 +08:00
group: Design Patterns
type: Global Rules
order: 6
title: Button
---
## Design Principal
- Guide users to achieve the desired actions.
- Prevent user to make mistakes.
## Types
### Common Button Types
<div>
<img alt="buttons" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*wsXrT7yQH2MAAAAAAAAAAABkARQnAQ">
</div>
#### ① Default Button
Default buttons are used for non-primary actions. If not sure which button type to choose from, the default button is always a safe bet.
#### ② Primary Button
Emphasize on "complete" or "recommend" action. There is at most one primary button per a button group.
#### ③ Text Button
Low emphasis and light-weight button type, such as actions in a table.
#### ④ Icon Button
Icon provides a visual clue.
- It could fit more buttons in a small space.
- Buttons with icon only need to provide Tooltip to indicate the meaning of the button.
#### ⑤ Text Button with Icon
Provides supplementary meaning to the button.
### Emphasis
<ImagePreview>
<img class="preview-img no-padding" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*guusTZ6ZPxkAAAAAAAAAAABkARQnAQ">
</ImagePreview>
Common button types could be used to showcase to different **emphasis**.
### Do & Don't
<ImagePreview>
<img class="preview-img no-padding bad" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*di8jS5EWYSIAAAAAAAAAAABkARQnAQ" alt="Don't" description="Don't put more than 1 primary button in the same group.">
<img class="preview-img no-padding good" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*3WUkT5pD1SUAAAAAAAAAAABkARQnAQ" alt="Do" description="1. Emphasize on the primary action. <br/>2. If there is no primary action, then default buttons is the safest choice.">
</ImagePreview>
<ImagePreview>
<img class="preview-img no-padding bad" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*zBtTRq2xbTYAAAAAAAAAAABkARQnAQ" alt="Don't" description="Put 2 icons in the same button.">
<img class="preview-img no-padding good" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*EpwSTpaGPBgAAAAAAAAAAABkARQnAQ" alt="Do" description="1. Should place the buttons in the order of importance. <br/>2. The less important actions should be place on right or at bottom.">
<img class="preview-img no-padding good" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*3WUkT5pD1SUAAAAAAAAAAABkARQnAQ" alt="Do" description="1. Emphasize on the primary action. <br/>2. If there is no primary action, then default buttons is the safest choice.">
</ImagePreview>
### Special Button Types
#### Dashed Button
<ImagePreview>
<img class="preview-img no-padding" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*gPmNQ6_YCcoAAAAAAAAAAABkARQnAQ">
</ImagePreview>
Guide users to add content in an area.
#### Danger Button
<ImagePreview>
<img class="preview-img no-padding" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*OvNaQJrmqVMAAAAAAAAAAABkARQnAQ">
</ImagePreview>
<ImagePreview>
<img class="preview-img no-padding good" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*ujcXTqJ_IwwAAAAAAAAAAABkARQnAQ" alt="Do" description="If user's intention is to delete, use danger button to warn this action has risks.">
</ImagePreview>
<ImagePreview>
<img class="preview-img no-padding good" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*o7EySrBPX9oAAAAAAAAAAABkARQnAQ" alt="Do" description="When system does not recommend the deletion action, we could set 'Cancel' as the primary action.">
</ImagePreview>
Warns users that there are risks involved in the action.
#### Ghost Button
Used in the dark or colored background.
<ImagePreview>
<img class="preview-img no-padding" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*-wORTrNJ6YUAAAAAAAAAAABkARQnAQ">
</ImagePreview>
#### Call to Action
<ImagePreview>
<img class="preview-img no-padding" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*32zdRqTjDhYAAAAAAAAAAABkARQnAQ">
</ImagePreview>
Usually appeared alone and intend to used as a command. For example, it is used in the landing page or welcome banner. It could be as wide as its parent container. It is recommend to have just 1 "Call to Action" button in 1 screen.
## Placement
<ImagePreview>
<img class="preview-img no-padding" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*B8D0RJnirLkAAAAAAAAAAABkARQnAQ">
</ImagePreview>
Place buttons in the users' reading pattern for the ease of discovery, such as the "F-Shaped Reading Pattern" and "Z-Shaped Reading Pattern".
### How to Decide Button Placement?
#### Page/Card/Section presents a subject, where it could be broken into 3 areas:
<ImagePreview>
<img class="preview-img no-padding" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*iVZpRpdN_2AAAAAAAAAAAABkARQnAQ">
</ImagePreview>
- Header: subject's heading, summary and navigation
- Body: detailed content
- Footer: supplementary information or toolbar
Place buttons in different areas could have different meanings.
### When to Put Buttons in the Footer?
<ImagePreview>
<img class="preview-img no-padding" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*KGGWQLCBfm0AAAAAAAAAAABkARQnAQ">
</ImagePreview>
- Body section has collapsed or hidden content, such as it could not show the entire content in one screen;
- Body section has complex content. For example, it has multiple subgroups and each subgroup has its own actions. Now it is needed to separate "Complete" action from body section to avoid confusion.
In short, footer's purpose is to have a separation from body.
## Ordering
### Button Ordering
<ImagePreview>
<img class="preview-img no-padding" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*NcPDQI3IX8YAAAAAAAAAAABkARQnAQ">
</ImagePreview>
Recommend to start from the reading flow, collapsed content should always be on the right.
**How to Decide Button Ordering**
- Conversation Flow: place buttons in the order similar to a conversation between computers and users. **Ask users the needed actions or your desired actions, then present the risks involved.**
- Navigation Flow: for example, if a button represents going back, should be placed on the left implying it is going to the previous step.
### Button Group
<ImagePreview>
<img class="preview-img no-padding good" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*tK-AQaE5h1YAAAAAAAAAAABkARQnAQ" alt="Do">
<img class="preview-img no-padding bad" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*_gU7ToHiZz4AAAAAAAAAAABkARQnAQ" alt="Don't" description="When button group has no space in between, it is easy to confuse it with Toggle Button.">
</ImagePreview>
When multiple buttons form a group, align buttons in one line with spaces in between.
### Grouping Buttons
When there are too many buttons on the screen, we could group relevant buttons together and use similar design for that group. If one of the buttons is primary action, we could still use emphasis.
<ImagePreview>
<img class="preview-img no-padding" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*x7YsTafH5osAAAAAAAAAAABkARQnAQ">
</ImagePreview>
**Collapse buttons in the order of importance**
<br />
<ImagePreview>
<img class="preview-img no-padding good" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*Qn-mQKxaQ5kAAAAAAAAAAABkARQnAQ" alt="Do">
<img class="preview-img no-padding bad" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*3bUZRbPiVBEAAAAAAAAAAABkARQnAQ" alt="Don't" description="If buttons are in the same group, no need to add dividers between them.">
</ImagePreview>
**Flat display of all the buttons:** could separate different groups using space; or use divider to group similar buttons.
## Label
<ImagePreview>
<img class="preview-img no-padding good" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*33KsR66zTY8AAAAAAAAAAABkARQnAQ" alt="Do">
</ImagePreview>
<ImagePreview>
<img class="preview-img no-padding bad" src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*238RTb4kaPwAAAAAAAAAAABkARQnAQ" alt="Don't" description="Should use verb">
</ImagePreview>
Labels should clearly indicate to users what would happen when buttons got clicked.
- Should use verb (except dropdown buttons)
- Should be relevant to the context and be concise.
Ant Design use "OK / Cancel" as default label, but you could still use below methods to customize the label text:
- Describe the action result.
> Publish, Login, Register.
- If primary action means negative, stress the consequences.
> Are you sure to delete it? Delete / Cancel