diff --git a/src/pages/components/button/images/button-style-danger-ghost-interactive-states.png b/src/pages/components/button/images/button-style-danger-ghost-interactive-states.png new file mode 100644 index 00000000000..95d25652275 Binary files /dev/null and b/src/pages/components/button/images/button-style-danger-ghost-interactive-states.png differ diff --git a/src/pages/components/button/images/button-style-danger-ghost.png b/src/pages/components/button/images/button-style-danger-ghost.png index 00ce2c19cb1..c7050c563cb 100644 Binary files a/src/pages/components/button/images/button-style-danger-ghost.png and b/src/pages/components/button/images/button-style-danger-ghost.png differ diff --git a/src/pages/components/button/images/button-style-danger-primary-interactive-states.png b/src/pages/components/button/images/button-style-danger-primary-interactive-states.png new file mode 100644 index 00000000000..454ad3d15be Binary files /dev/null and b/src/pages/components/button/images/button-style-danger-primary-interactive-states.png differ diff --git a/src/pages/components/button/images/button-style-danger-primary.png b/src/pages/components/button/images/button-style-danger-primary.png new file mode 100644 index 00000000000..6a55106159c Binary files /dev/null and b/src/pages/components/button/images/button-style-danger-primary.png differ diff --git a/src/pages/components/button/images/button-style-danger-tertiary-interactive-states.png b/src/pages/components/button/images/button-style-danger-tertiary-interactive-states.png new file mode 100644 index 00000000000..f3223a5e944 Binary files /dev/null and b/src/pages/components/button/images/button-style-danger-tertiary-interactive-states.png differ diff --git a/src/pages/components/button/images/button-style-danger-tertiary.png b/src/pages/components/button/images/button-style-danger-tertiary.png index bb5a1930521..3ba4c47c6ac 100644 Binary files a/src/pages/components/button/images/button-style-danger-tertiary.png and b/src/pages/components/button/images/button-style-danger-tertiary.png differ diff --git a/src/pages/components/button/images/button-style-danger.png b/src/pages/components/button/images/button-style-danger.png deleted file mode 100755 index 2abcc211bb7..00000000000 Binary files a/src/pages/components/button/images/button-style-danger.png and /dev/null differ diff --git a/src/pages/components/button/images/button-style-ghost+icon-only.png b/src/pages/components/button/images/button-style-ghost+icon-only.png deleted file mode 100644 index 79a2fe15c2c..00000000000 Binary files a/src/pages/components/button/images/button-style-ghost+icon-only.png and /dev/null differ diff --git a/src/pages/components/button/images/button-style-ghost-icon-only-interactive-states.png b/src/pages/components/button/images/button-style-ghost-icon-only-interactive-states.png new file mode 100644 index 00000000000..d8878499901 Binary files /dev/null and b/src/pages/components/button/images/button-style-ghost-icon-only-interactive-states.png differ diff --git a/src/pages/components/button/images/button-style-ghost-icon-only.png b/src/pages/components/button/images/button-style-ghost-icon-only.png new file mode 100644 index 00000000000..229d0104c7b Binary files /dev/null and b/src/pages/components/button/images/button-style-ghost-icon-only.png differ diff --git a/src/pages/components/button/images/button-style-ghost-interactive-states.png b/src/pages/components/button/images/button-style-ghost-interactive-states.png new file mode 100644 index 00000000000..8d95a54d4a7 Binary files /dev/null and b/src/pages/components/button/images/button-style-ghost-interactive-states.png differ diff --git a/src/pages/components/button/images/button-style-ghost.png b/src/pages/components/button/images/button-style-ghost.png old mode 100755 new mode 100644 index 6a05bacc93f..7e9962abf81 Binary files a/src/pages/components/button/images/button-style-ghost.png and b/src/pages/components/button/images/button-style-ghost.png differ diff --git a/src/pages/components/button/images/button-style-primary-icon-only-interactive-states.png b/src/pages/components/button/images/button-style-primary-icon-only-interactive-states.png new file mode 100644 index 00000000000..06e476008d0 Binary files /dev/null and b/src/pages/components/button/images/button-style-primary-icon-only-interactive-states.png differ diff --git a/src/pages/components/button/images/button-style-primary-icon-only.png b/src/pages/components/button/images/button-style-primary-icon-only.png new file mode 100644 index 00000000000..37da5b56eb1 Binary files /dev/null and b/src/pages/components/button/images/button-style-primary-icon-only.png differ diff --git a/src/pages/components/button/images/button-style-primary-interactive-states.png b/src/pages/components/button/images/button-style-primary-interactive-states.png new file mode 100644 index 00000000000..577f49dd35c Binary files /dev/null and b/src/pages/components/button/images/button-style-primary-interactive-states.png differ diff --git a/src/pages/components/button/images/button-style-primary.png b/src/pages/components/button/images/button-style-primary.png old mode 100755 new mode 100644 index 903f6244497..bcf6361e646 Binary files a/src/pages/components/button/images/button-style-primary.png and b/src/pages/components/button/images/button-style-primary.png differ diff --git a/src/pages/components/button/images/button-style-secondary-icon-only-interactive-states.png b/src/pages/components/button/images/button-style-secondary-icon-only-interactive-states.png new file mode 100644 index 00000000000..1ae0178e3d3 Binary files /dev/null and b/src/pages/components/button/images/button-style-secondary-icon-only-interactive-states.png differ diff --git a/src/pages/components/button/images/button-style-secondary-icon-only.png b/src/pages/components/button/images/button-style-secondary-icon-only.png new file mode 100644 index 00000000000..9ba4312b1b3 Binary files /dev/null and b/src/pages/components/button/images/button-style-secondary-icon-only.png differ diff --git a/src/pages/components/button/images/button-style-secondary-interactive-states.png b/src/pages/components/button/images/button-style-secondary-interactive-states.png new file mode 100644 index 00000000000..f586808d388 Binary files /dev/null and b/src/pages/components/button/images/button-style-secondary-interactive-states.png differ diff --git a/src/pages/components/button/images/button-style-secondary.png b/src/pages/components/button/images/button-style-secondary.png old mode 100755 new mode 100644 index 52471471440..6276c445b02 Binary files a/src/pages/components/button/images/button-style-secondary.png and b/src/pages/components/button/images/button-style-secondary.png differ diff --git a/src/pages/components/button/images/button-style-sizes.png b/src/pages/components/button/images/button-style-sizes.png index 43dacd3d033..eb54f9f201a 100644 Binary files a/src/pages/components/button/images/button-style-sizes.png and b/src/pages/components/button/images/button-style-sizes.png differ diff --git a/src/pages/components/button/images/button-style-structure-button-groups.png b/src/pages/components/button/images/button-style-structure-button-groups.png new file mode 100644 index 00000000000..49697be028b Binary files /dev/null and b/src/pages/components/button/images/button-style-structure-button-groups.png differ diff --git a/src/pages/components/button/images/button-style-structure-ghost.png b/src/pages/components/button/images/button-style-structure-ghost.png new file mode 100644 index 00000000000..e90476c2aa7 Binary files /dev/null and b/src/pages/components/button/images/button-style-structure-ghost.png differ diff --git a/src/pages/components/button/images/button-style-structure.png b/src/pages/components/button/images/button-style-structure.png index c3676627446..aafbd48f62b 100644 Binary files a/src/pages/components/button/images/button-style-structure.png and b/src/pages/components/button/images/button-style-structure.png differ diff --git a/src/pages/components/button/images/button-style-tertiary-icon-only-interactive-states.png b/src/pages/components/button/images/button-style-tertiary-icon-only-interactive-states.png new file mode 100644 index 00000000000..cb74d349c4c Binary files /dev/null and b/src/pages/components/button/images/button-style-tertiary-icon-only-interactive-states.png differ diff --git a/src/pages/components/button/images/button-style-tertiary-icon-only.png b/src/pages/components/button/images/button-style-tertiary-icon-only.png new file mode 100644 index 00000000000..5e5efb7ae2e Binary files /dev/null and b/src/pages/components/button/images/button-style-tertiary-icon-only.png differ diff --git a/src/pages/components/button/images/button-style-tertiary-interactive-states.png b/src/pages/components/button/images/button-style-tertiary-interactive-states.png new file mode 100644 index 00000000000..77b6a1637bc Binary files /dev/null and b/src/pages/components/button/images/button-style-tertiary-interactive-states.png differ diff --git a/src/pages/components/button/images/button-style-tertiary.png b/src/pages/components/button/images/button-style-tertiary.png old mode 100755 new mode 100644 index 79c64380844..eaf806a2929 Binary files a/src/pages/components/button/images/button-style-tertiary.png and b/src/pages/components/button/images/button-style-tertiary.png differ diff --git a/src/pages/components/button/images/button-usage-RTL.png b/src/pages/components/button/images/button-usage-RTL.png new file mode 100644 index 00000000000..42a15104e7b Binary files /dev/null and b/src/pages/components/button/images/button-usage-RTL.png differ diff --git a/src/pages/components/button/images/button-usage-ub-inline-loading.gif b/src/pages/components/button/images/button-usage-ub-inline-loading.gif new file mode 100644 index 00000000000..8f951a263ff Binary files /dev/null and b/src/pages/components/button/images/button-usage-ub-inline-loading.gif differ diff --git a/src/pages/components/button/images/button-usage-ub-validation.gif b/src/pages/components/button/images/button-usage-ub-validation.gif new file mode 100644 index 00000000000..a44a5c57187 Binary files /dev/null and b/src/pages/components/button/images/button-usage-ub-validation.gif differ diff --git a/src/pages/components/button/images/button_usage_1.png b/src/pages/components/button/images/button_usage_1.png deleted file mode 100644 index 4309740ac4a..00000000000 Binary files a/src/pages/components/button/images/button_usage_1.png and /dev/null differ diff --git a/src/pages/components/button/images/button_usage_10.png b/src/pages/components/button/images/button_usage_10.png index 434b89bfea7..b80ff0a03bd 100644 Binary files a/src/pages/components/button/images/button_usage_10.png and b/src/pages/components/button/images/button_usage_10.png differ diff --git a/src/pages/components/button/images/button_usage_11.png b/src/pages/components/button/images/button_usage_11.png index 8b6eb1536b8..e8ba4fa227a 100644 Binary files a/src/pages/components/button/images/button_usage_11.png and b/src/pages/components/button/images/button_usage_11.png differ diff --git a/src/pages/components/button/images/button_usage_12.png b/src/pages/components/button/images/button_usage_12.png index b7212cb0b99..80458bcc9d4 100644 Binary files a/src/pages/components/button/images/button_usage_12.png and b/src/pages/components/button/images/button_usage_12.png differ diff --git a/src/pages/components/button/images/button_usage_13.png b/src/pages/components/button/images/button_usage_13.png index 9dc6166dbbe..b1bac839fa1 100644 Binary files a/src/pages/components/button/images/button_usage_13.png and b/src/pages/components/button/images/button_usage_13.png differ diff --git a/src/pages/components/button/images/button_usage_14.png b/src/pages/components/button/images/button_usage_14.png index 99f996f82d4..4cebe6488a3 100644 Binary files a/src/pages/components/button/images/button_usage_14.png and b/src/pages/components/button/images/button_usage_14.png differ diff --git a/src/pages/components/button/images/button_usage_15.png b/src/pages/components/button/images/button_usage_15.png index 9ab48a39f95..2426a5a411a 100644 Binary files a/src/pages/components/button/images/button_usage_15.png and b/src/pages/components/button/images/button_usage_15.png differ diff --git a/src/pages/components/button/images/button_usage_15_test.png b/src/pages/components/button/images/button_usage_15_test.png deleted file mode 100644 index 9ab48a39f95..00000000000 Binary files a/src/pages/components/button/images/button_usage_15_test.png and /dev/null differ diff --git a/src/pages/components/button/images/button_usage_2.png b/src/pages/components/button/images/button_usage_2.png index fa40dce0023..a9f9d9160cd 100644 Binary files a/src/pages/components/button/images/button_usage_2.png and b/src/pages/components/button/images/button_usage_2.png differ diff --git a/src/pages/components/button/images/button_usage_26.png b/src/pages/components/button/images/button_usage_26.png index ced9411735f..be05d7244e6 100644 Binary files a/src/pages/components/button/images/button_usage_26.png and b/src/pages/components/button/images/button_usage_26.png differ diff --git a/src/pages/components/button/images/button_usage_27.png b/src/pages/components/button/images/button_usage_27.png index 1881aa3c441..0523b47a657 100644 Binary files a/src/pages/components/button/images/button_usage_27.png and b/src/pages/components/button/images/button_usage_27.png differ diff --git a/src/pages/components/button/images/button_usage_3.png b/src/pages/components/button/images/button_usage_3.png index 8b87a701901..9c313552f98 100644 Binary files a/src/pages/components/button/images/button_usage_3.png and b/src/pages/components/button/images/button_usage_3.png differ diff --git a/src/pages/components/button/images/button_usage_30.png b/src/pages/components/button/images/button_usage_30.png deleted file mode 100644 index bb3425baaed..00000000000 Binary files a/src/pages/components/button/images/button_usage_30.png and /dev/null differ diff --git a/src/pages/components/button/images/button_usage_31.png b/src/pages/components/button/images/button_usage_31.png deleted file mode 100644 index a4d89864720..00000000000 Binary files a/src/pages/components/button/images/button_usage_31.png and /dev/null differ diff --git a/src/pages/components/button/images/button_usage_5.png b/src/pages/components/button/images/button_usage_5.png index 93e63e3de48..898dfc2cc6e 100644 Binary files a/src/pages/components/button/images/button_usage_5.png and b/src/pages/components/button/images/button_usage_5.png differ diff --git a/src/pages/components/button/images/button_usage_6.png b/src/pages/components/button/images/button_usage_6.png index bead6990bc0..ebf3ac75b99 100644 Binary files a/src/pages/components/button/images/button_usage_6.png and b/src/pages/components/button/images/button_usage_6.png differ diff --git a/src/pages/components/button/images/button_usage_7.png b/src/pages/components/button/images/button_usage_7.png deleted file mode 100644 index 4970dd86d4d..00000000000 Binary files a/src/pages/components/button/images/button_usage_7.png and /dev/null differ diff --git a/src/pages/components/button/images/button_usage_8.png b/src/pages/components/button/images/button_usage_8.png index f3457449093..662ea38146e 100644 Binary files a/src/pages/components/button/images/button_usage_8.png and b/src/pages/components/button/images/button_usage_8.png differ diff --git a/src/pages/components/button/images/button_usage_8_test.png b/src/pages/components/button/images/button_usage_8_test.png deleted file mode 100644 index f3457449093..00000000000 Binary files a/src/pages/components/button/images/button_usage_8_test.png and /dev/null differ diff --git a/src/pages/components/button/images/button_usage_9.png b/src/pages/components/button/images/button_usage_9.png index bcbe5ccc1df..dba12bd87e6 100644 Binary files a/src/pages/components/button/images/button_usage_9.png and b/src/pages/components/button/images/button_usage_9.png differ diff --git a/src/pages/components/button/images/button_usage_9_test.png b/src/pages/components/button/images/button_usage_9_test.png deleted file mode 100644 index bcbe5ccc1df..00000000000 Binary files a/src/pages/components/button/images/button_usage_9_test.png and /dev/null differ diff --git a/src/pages/components/button/images/button_usage_button_with_icon_1.png b/src/pages/components/button/images/button_usage_button_with_icon_1.png new file mode 100644 index 00000000000..60fc71e371d Binary files /dev/null and b/src/pages/components/button/images/button_usage_button_with_icon_1.png differ diff --git a/src/pages/components/button/images/button_usage_button_with_icon_10.png b/src/pages/components/button/images/button_usage_button_with_icon_10.png new file mode 100644 index 00000000000..c2a5c1b1867 Binary files /dev/null and b/src/pages/components/button/images/button_usage_button_with_icon_10.png differ diff --git a/src/pages/components/button/images/button_usage_button_with_icon_11.png b/src/pages/components/button/images/button_usage_button_with_icon_11.png new file mode 100644 index 00000000000..c84cd2b6f9c Binary files /dev/null and b/src/pages/components/button/images/button_usage_button_with_icon_11.png differ diff --git a/src/pages/components/button/images/button_usage_button_with_icon_12.png b/src/pages/components/button/images/button_usage_button_with_icon_12.png new file mode 100644 index 00000000000..b623f4c8ecf Binary files /dev/null and b/src/pages/components/button/images/button_usage_button_with_icon_12.png differ diff --git a/src/pages/components/button/images/button_usage_button_with_icon_13.png b/src/pages/components/button/images/button_usage_button_with_icon_13.png new file mode 100644 index 00000000000..0223b58ba48 Binary files /dev/null and b/src/pages/components/button/images/button_usage_button_with_icon_13.png differ diff --git a/src/pages/components/button/images/button_usage_button_with_icon_2.png b/src/pages/components/button/images/button_usage_button_with_icon_2.png new file mode 100644 index 00000000000..16b7ca5fe64 Binary files /dev/null and b/src/pages/components/button/images/button_usage_button_with_icon_2.png differ diff --git a/src/pages/components/button/images/button_usage_button_with_icon_3.png b/src/pages/components/button/images/button_usage_button_with_icon_3.png new file mode 100644 index 00000000000..be0ad678346 Binary files /dev/null and b/src/pages/components/button/images/button_usage_button_with_icon_3.png differ diff --git a/src/pages/components/button/images/button_usage_button_with_icon_4.png b/src/pages/components/button/images/button_usage_button_with_icon_4.png new file mode 100644 index 00000000000..ba3b7484cff Binary files /dev/null and b/src/pages/components/button/images/button_usage_button_with_icon_4.png differ diff --git a/src/pages/components/button/images/button_usage_button_with_icon_5.png b/src/pages/components/button/images/button_usage_button_with_icon_5.png new file mode 100644 index 00000000000..474f60edb74 Binary files /dev/null and b/src/pages/components/button/images/button_usage_button_with_icon_5.png differ diff --git a/src/pages/components/button/images/button_usage_button_with_icon_6.png b/src/pages/components/button/images/button_usage_button_with_icon_6.png new file mode 100644 index 00000000000..d004472e2fa Binary files /dev/null and b/src/pages/components/button/images/button_usage_button_with_icon_6.png differ diff --git a/src/pages/components/button/images/button_usage_button_with_icon_7.png b/src/pages/components/button/images/button_usage_button_with_icon_7.png new file mode 100644 index 00000000000..800cbe14c43 Binary files /dev/null and b/src/pages/components/button/images/button_usage_button_with_icon_7.png differ diff --git a/src/pages/components/button/images/button_usage_button_with_icon_8.png b/src/pages/components/button/images/button_usage_button_with_icon_8.png new file mode 100644 index 00000000000..3495883bc5c Binary files /dev/null and b/src/pages/components/button/images/button_usage_button_with_icon_8.png differ diff --git a/src/pages/components/button/images/button_usage_button_with_icon_9.png b/src/pages/components/button/images/button_usage_button_with_icon_9.png new file mode 100644 index 00000000000..e0427dc98cb Binary files /dev/null and b/src/pages/components/button/images/button_usage_button_with_icon_9.png differ diff --git a/src/pages/components/button/images/button_usage_danger_ghost.png b/src/pages/components/button/images/button_usage_danger_ghost.png new file mode 100644 index 00000000000..b5aba37f9bc Binary files /dev/null and b/src/pages/components/button/images/button_usage_danger_ghost.png differ diff --git a/src/pages/components/button/images/button_usage_danger_primary.png b/src/pages/components/button/images/button_usage_danger_primary.png new file mode 100644 index 00000000000..d747b499f3f Binary files /dev/null and b/src/pages/components/button/images/button_usage_danger_primary.png differ diff --git a/src/pages/components/button/images/button_usage_danger_tertiary.png b/src/pages/components/button/images/button_usage_danger_tertiary.png new file mode 100644 index 00000000000..612ef6494d9 Binary files /dev/null and b/src/pages/components/button/images/button_usage_danger_tertiary.png differ diff --git a/src/pages/components/button/images/button_usage_ghost_1.png b/src/pages/components/button/images/button_usage_ghost_1.png new file mode 100644 index 00000000000..dcd8ad924d4 Binary files /dev/null and b/src/pages/components/button/images/button_usage_ghost_1.png differ diff --git a/src/pages/components/button/images/button_usage_ghost_2.png b/src/pages/components/button/images/button_usage_ghost_2.png new file mode 100644 index 00000000000..0010401fad3 Binary files /dev/null and b/src/pages/components/button/images/button_usage_ghost_2.png differ diff --git a/src/pages/components/button/images/button_usage_ghost_3.png b/src/pages/components/button/images/button_usage_ghost_3.png new file mode 100644 index 00000000000..53c5b916e97 Binary files /dev/null and b/src/pages/components/button/images/button_usage_ghost_3.png differ diff --git a/src/pages/components/button/images/button_usage_ghost_4.png b/src/pages/components/button/images/button_usage_ghost_4.png new file mode 100644 index 00000000000..885eb1f4d65 Binary files /dev/null and b/src/pages/components/button/images/button_usage_ghost_4.png differ diff --git a/src/pages/components/button/images/button_usage_ghost_5.png b/src/pages/components/button/images/button_usage_ghost_5.png new file mode 100644 index 00000000000..389c1303864 Binary files /dev/null and b/src/pages/components/button/images/button_usage_ghost_5.png differ diff --git a/src/pages/components/button/images/button_usage_ghost_6.png b/src/pages/components/button/images/button_usage_ghost_6.png new file mode 100644 index 00000000000..ad8b340feb0 Binary files /dev/null and b/src/pages/components/button/images/button_usage_ghost_6.png differ diff --git a/src/pages/components/button/images/button_usage_ghost_7.png b/src/pages/components/button/images/button_usage_ghost_7.png new file mode 100644 index 00000000000..d8e5bff8513 Binary files /dev/null and b/src/pages/components/button/images/button_usage_ghost_7.png differ diff --git a/src/pages/components/button/images/button_usage_ghost_8.png b/src/pages/components/button/images/button_usage_ghost_8.png new file mode 100644 index 00000000000..ec7e4981d97 Binary files /dev/null and b/src/pages/components/button/images/button_usage_ghost_8.png differ diff --git a/src/pages/components/button/images/button_usage_ghost_9.png b/src/pages/components/button/images/button_usage_ghost_9.png new file mode 100644 index 00000000000..b11a77d2aed Binary files /dev/null and b/src/pages/components/button/images/button_usage_ghost_9.png differ diff --git a/src/pages/components/button/images/button_usage_icon_only_button_1.png b/src/pages/components/button/images/button_usage_icon_only_button_1.png new file mode 100644 index 00000000000..e0608d00c9c Binary files /dev/null and b/src/pages/components/button/images/button_usage_icon_only_button_1.png differ diff --git a/src/pages/components/button/images/button_usage_icon_only_button_2.png b/src/pages/components/button/images/button_usage_icon_only_button_2.png new file mode 100644 index 00000000000..d9ce36c258d Binary files /dev/null and b/src/pages/components/button/images/button_usage_icon_only_button_2.png differ diff --git a/src/pages/components/button/images/button_usage_icon_only_button_3.png b/src/pages/components/button/images/button_usage_icon_only_button_3.png new file mode 100644 index 00000000000..10dd9fadd2c Binary files /dev/null and b/src/pages/components/button/images/button_usage_icon_only_button_3.png differ diff --git a/src/pages/components/button/images/button_usage_icon_only_button_4.png b/src/pages/components/button/images/button_usage_icon_only_button_4.png new file mode 100644 index 00000000000..db0a1cb9016 Binary files /dev/null and b/src/pages/components/button/images/button_usage_icon_only_button_4.png differ diff --git a/src/pages/components/button/images/button_usage_icon_only_button_5.png b/src/pages/components/button/images/button_usage_icon_only_button_5.png new file mode 100644 index 00000000000..672b48bf31b Binary files /dev/null and b/src/pages/components/button/images/button_usage_icon_only_button_5.png differ diff --git a/src/pages/components/button/images/button_usage_icon_only_button_6.png b/src/pages/components/button/images/button_usage_icon_only_button_6.png new file mode 100644 index 00000000000..c3aca167edb Binary files /dev/null and b/src/pages/components/button/images/button_usage_icon_only_button_6.png differ diff --git a/src/pages/components/button/images/button_usage_overflow_1.png b/src/pages/components/button/images/button_usage_overflow_1.png new file mode 100644 index 00000000000..16feb13a3f2 Binary files /dev/null and b/src/pages/components/button/images/button_usage_overflow_1.png differ diff --git a/src/pages/components/button/images/button_usage_overflow_2.png b/src/pages/components/button/images/button_usage_overflow_2.png new file mode 100644 index 00000000000..a9f6249a902 Binary files /dev/null and b/src/pages/components/button/images/button_usage_overflow_2.png differ diff --git a/src/pages/components/button/images/button_usage_primary_1.png b/src/pages/components/button/images/button_usage_primary_1.png new file mode 100644 index 00000000000..5f3535f9537 Binary files /dev/null and b/src/pages/components/button/images/button_usage_primary_1.png differ diff --git a/src/pages/components/button/images/button_usage_primary_2.png b/src/pages/components/button/images/button_usage_primary_2.png new file mode 100644 index 00000000000..44bdb062d17 Binary files /dev/null and b/src/pages/components/button/images/button_usage_primary_2.png differ diff --git a/src/pages/components/button/images/button_usage_primary_3.png b/src/pages/components/button/images/button_usage_primary_3.png new file mode 100644 index 00000000000..a4bb415f173 Binary files /dev/null and b/src/pages/components/button/images/button_usage_primary_3.png differ diff --git a/src/pages/components/button/images/button_usage_secondary_1.png b/src/pages/components/button/images/button_usage_secondary_1.png new file mode 100644 index 00000000000..4131f3dc698 Binary files /dev/null and b/src/pages/components/button/images/button_usage_secondary_1.png differ diff --git a/src/pages/components/button/images/button_usage_secondary_2.png b/src/pages/components/button/images/button_usage_secondary_2.png new file mode 100644 index 00000000000..662ea38146e Binary files /dev/null and b/src/pages/components/button/images/button_usage_secondary_2.png differ diff --git a/src/pages/components/button/images/button_usage_secondary_3.png b/src/pages/components/button/images/button_usage_secondary_3.png new file mode 100644 index 00000000000..0aadb84f609 Binary files /dev/null and b/src/pages/components/button/images/button_usage_secondary_3.png differ diff --git a/src/pages/components/button/images/button_usage_tertiary_1.png b/src/pages/components/button/images/button_usage_tertiary_1.png new file mode 100644 index 00000000000..033063aef9c Binary files /dev/null and b/src/pages/components/button/images/button_usage_tertiary_1.png differ diff --git a/src/pages/components/button/images/button_usage_tertiary_2.png b/src/pages/components/button/images/button_usage_tertiary_2.png new file mode 100644 index 00000000000..66b606d5011 Binary files /dev/null and b/src/pages/components/button/images/button_usage_tertiary_2.png differ diff --git a/src/pages/components/button/images/button_usage_tertiary_3.png b/src/pages/components/button/images/button_usage_tertiary_3.png new file mode 100644 index 00000000000..c4927c4d3b3 Binary files /dev/null and b/src/pages/components/button/images/button_usage_tertiary_3.png differ diff --git a/src/pages/components/button/images/button_usage_tertiary_4.png b/src/pages/components/button/images/button_usage_tertiary_4.png new file mode 100644 index 00000000000..dfc907225eb Binary files /dev/null and b/src/pages/components/button/images/button_usage_tertiary_4.png differ diff --git a/src/pages/components/button/images/button_usage_tertiary_5.png b/src/pages/components/button/images/button_usage_tertiary_5.png new file mode 100644 index 00000000000..1755d74563d Binary files /dev/null and b/src/pages/components/button/images/button_usage_tertiary_5.png differ diff --git a/src/pages/components/button/images/button_usage_tertiary_6.png b/src/pages/components/button/images/button_usage_tertiary_6.png new file mode 100644 index 00000000000..e64d2c8bfbe Binary files /dev/null and b/src/pages/components/button/images/button_usage_tertiary_6.png differ diff --git a/src/pages/components/button/images/button_usage_tertiary_7.png b/src/pages/components/button/images/button_usage_tertiary_7.png new file mode 100644 index 00000000000..d2d36235f49 Binary files /dev/null and b/src/pages/components/button/images/button_usage_tertiary_7.png differ diff --git a/src/pages/components/button/images/button_usage_ub_focus.png b/src/pages/components/button/images/button_usage_ub_focus.png new file mode 100644 index 00000000000..e3dfe4c3884 Binary files /dev/null and b/src/pages/components/button/images/button_usage_ub_focus.png differ diff --git a/src/pages/components/button/images/button_usage_ub_interaction.png b/src/pages/components/button/images/button_usage_ub_interaction.png new file mode 100644 index 00000000000..7d2fce009e4 Binary files /dev/null and b/src/pages/components/button/images/button_usage_ub_interaction.png differ diff --git a/src/pages/components/button/images/button_usage_ub_loading_3.png b/src/pages/components/button/images/button_usage_ub_loading_3.png new file mode 100644 index 00000000000..ca4f8cc62ee Binary files /dev/null and b/src/pages/components/button/images/button_usage_ub_loading_3.png differ diff --git a/src/pages/components/button/images/button_usage_ub_validation_4.png b/src/pages/components/button/images/button_usage_ub_validation_4.png new file mode 100644 index 00000000000..6c789395d27 Binary files /dev/null and b/src/pages/components/button/images/button_usage_ub_validation_4.png differ diff --git a/src/pages/components/button/style.mdx b/src/pages/components/button/style.mdx index 75ff2c2674a..41a42a99c28 100755 --- a/src/pages/components/button/style.mdx +++ b/src/pages/components/button/style.mdx @@ -6,207 +6,435 @@ description: tabs: ['Usage', 'Style', 'Code', 'Accessibility'] --- + + +The following page documents visual specifications such as color, typography, +structure, and size. + + + + + +Color +Typography +Structure +Sizes +Feedback + + + ## Color -### Primary button - -| Element | Property | Color token | -| ------------------ | ---------------- | ------------------------- | -| Label | text color | `$text-on-color` | -| Icon | svg | `$icon-on-color` | -| Container | background-color | `$button-primary` | -| Container:hover | background-color | `$button-primary-hover` | -| Container:active | background-color | `$button-primary-active` | -| Container:focus | border | `$focus` | -| | inset | `$focus-inset` | -| Container:disabled | background-color | `$button-disabled` | -| Label:disabled | text color | `$text-on-color-disabled` | -| Icon:disabled | svg | `$icon-on-color-disabled` | +### Primary button color + +| Element | Property | Color token | +| --------- | ---------------- | ----------------- | +| Label | text color | `$text-on-color` | +| Icon | svg | `$icon-on-color` | +| Container | background-color | `$button-primary` | -![Primary button states and color](images/button-style-primary.png) + + + + +![Primary button color](images/button-style-primary.png) + + + + + +![Primary icon only button color](images/button-style-primary-icon-only.png) + + + + -### Secondary button - -| Element | Property | Color token | -| ------------------ | ---------------- | -------------------------- | -| Label | text color | `$text-on-color` | -| Icon | svg | `$icon-on-color` | -| Container | background-color | `$button-secondary` | -| Container:hover | background-color | `$button-secondary-hover` | -| Container:active | background-color | `$button-secondary-active` | -| Container:focus | border | `$focus` | -| | inset | `$focus-inset` | -| Container:disabled | background-color | `$button-disabled` | -| Label:disabled | text color | `$text-on-color-disabled` | -| Icon:disabled | svg | `$icon-on-color-disabled` | +Primary button interactive state color + +| State | Element | Property | Color token | +| -------- | --------- | ---------------- | ------------------------- | +| Hover | Container | background-color | `$button-primary-hover` | +| Focus | Container | border | `$focus` | +| | | inset | `$focus-inset` | +| Active | Container | background-color | `$button-primary-active` | +| Disabled | Label | text-color | `$text-on-color-disabled` | +| | Icon | svg | `$icon-on-color-disabled` | +| | Container | background-color | `$button-disabled` | -![Secondary button states and color](images/button-style-secondary.png) + + + + +![Primary button interactive states color](images/button-style-primary-interactive-states.png) + + + + + +![Primary icon only button interactive states color](images/button-style-primary-icon-only-interactive-states.png) + + + + -### Tertiary button - -| Element | Property | Color token | -| ------------------ | ---------------- | ------------------------- | -| Label | text color | `$button-tertiary` | -| Icon | svg | `$button-tertiary` | -| Container | background-color | `transparent` | -| | border | `$button-tertiary` | -| Label:hover | text color | `$text-inverse` | -| Icon:hover | svg | `$icon-inverse` | -| Container:hover | background-color | `$button-tertiary-hover` | -| Label:active | text color | `$text-inverse` | -| Icon:active | svg | `$icon-inverse` | -| Container:active | background-color | `$button-tertiary-active` | -| Container:focus | background-color | `$button-tertiary-hover` | -| | border | `$focus` | -| | inset | `$focus-inset` | -| Container:disabled | background | `transparent` | -| | border | `$button-disabled` | -| Label:disabled | text color | `$text-disabled` | -| Icon:disabled | svg | `$icon-disabled` | +### Secondary button color + +| Element | Property | Color token | +| --------- | ---------------- | ------------------- | +| Label | text color | `$text-on-color` | +| Icon | svg | `$icon-on-color` | +| Container | background-color | `$button-secondary` | -![Tertiary button states and color](images/button-style-tertiary.png) + + + + +![Secondary button color](images/button-style-secondary.png) + + + + + +![Secondary icon only button color](images/button-style-secondary-icon-only.png) + + + + -### Ghost button - -| Element | Property | Color token | -| ---------------- | ---------------- | --------------------- | -| Label | text color | `$link-primary` | -| Icon | svg | `$link-primary` | -| Container | background-color | Transparent | -| Label:hover | text color | `$link-primary-hover` | -| Icon:hover | svg | `$link-primary-hover` | -| Container:hover | background-color | `$background-hover` | -| Container:active | background-color | `$background-active` | -| Container:focus | border | `$focus` | -| Label:disabled | text color | `$text-disabled` | -| Label:disabled | svg | `$icon-disabled` | +Secondary button interactive state color + +| State | Element | Property | Color token | +| -------- | --------- | ---------------- | -------------------------- | +| Hover | Container | background-color | `$button-secondary-hover` | +| Focus | Container | border | `$focus` | +| | | inset | `$focus-inset` | +| Active | Container | background-color | `$button-secondary-active` | +| Disabled | Label | text-color | `$text-on-color-disabled` | +| | Icon | svg | `$icon-on-color-disabled` | +| | Container | background-color | `$button-disabled` | -![Ghost button states and color](images/button-style-ghost.png) + + + + +![Secondary button interactive states color](images/button-style-secondary-interactive-states.png) + + + + + +![Secondary icon only button interactive states color](images/button-style-secondary-icon-only-interactive-states.png) + + + + -
+### Tertiary button color -#### Ghost button – Icon only +| Element | Property | Color token | +| --------- | ---------------- | ------------------ | +| Label | text color | `$button-tertiary` | +| Icon | svg | `$button-tertiary` | +| Container | background-color | `transparent` | +| | border | `$button-tertiary` | -
+ + + + + + + +![Tertiary button color](images/button-style-tertiary.png) + + -| Element | Property | Color token | -| ------------------ | ---------------- | ---------------------- | -| Icon | svg | `$icon-primary` | -| Container | background-color | Transparent | -| Container:hover | background-color | `$background-hover` | -| Container:active | background-color | `$background-active` | -| Container:focus | border | `$focus` | -| Container:selected | background-color | `$background-selected` | -| Icon:disabled | svg | `$icon-disabled` | + + +![Tertiary icon only button color](images/button-style-tertiary-icon-only.png) + + + + + + + + +Tertiary button interactive state color + +| State | Element | Property | Color token | +| -------- | --------- | ---------------- | ------------------------- | +| Hover | Label | text-color | `$text-inverse` | +| | Icon | svg | `$icon-inverse` | +| | Container | background-color | `$button-tertiary-hover` | +| Focus | Container | background-color | `$button-tertiary-hover` | +| | | border | `$focus` | +| | | inset | `$focus-inset` | +| Active | Label | text-color | `$text-inverse` | +| | Icon | svg | `$icon-inverse` | +| | Container | background-color | `$button-tertiary-active` | +| Disabled | Label | text-color | `$text-disabled` | +| | Icon | svg | `$icon-disabled` | +| | Container | background-color | `transparent` | +| | | border | `$button-disabled` | -![Icon only ghost button states and color](images/button-style-ghost+icon-only.png) + + + + +![Tertiary button interactive states color](images/button-style-tertiary-interactive-states.png) + + + + + +![Tertiary icon only button interactive states color](images/button-style-tertiary-icon-only-interactive-states.png) + + + + -### Primary danger button - -| Element | Property | Color token | -| ------------------ | ---------------- | ------------------------- | -| Label | text color | `$text-on-color` | -| Icon | svg | `$icon-on-color` | -| Container | background-color | `$button-danger-primary` | -| Container:hover | background-color | `$button-danger-hover` | -| Container:active | background-color | `$button-danger-active` | -| Container:focus | border | `$focus` | -| | inset | `$focus-inset` | -| Container:disabled | background-color | `$button-disabled` | -| Label:disabled | text color | `$text-on-color-disabled` | -| Icon:disabled | svg | `$icon-on-color-disabled` | +### Ghost button color + +Ghost button color + +| Element | Property | Color token | +| --------- | ---------------- | --------------- | +| Label | text color | `$link-primary` | +| Icon | svg | `$link-primary` | +| Container | background-color | `transparent` | + +Ghost icon only button color + +| Element | Property | Color token | +| --------- | ---------------- | --------------- | +| Icon | svg | `$icon-primary` | +| Container | background-color | `transparent` | -![Primary danger button states and color](images/button-style-danger.png) + + + + +![Ghost button color](images/button-style-ghost.png) + + + + + +![Ghost icon only button color](images/button-style-ghost-icon-only.png) + + + + -### Tertiary danger button - -| Element | Property | Color token | -| ------------------ | ---------------- | -------------------------- | -| Label | text color | `$button-danger-secondary` | -| Icon | svg | `$button-danger-secondary` | -| Container | border | `$button-danger-secondary` | -| Container:hover | background-color | `$button-danger-hover` | -| Label:hover | text color | `$text-on-color` | -| Icon:hover | svg | `$icon-on-color` | -| Container:active | background-color | `$button-danger-active` | -| Label:active | text color | `$text-on-color` | -| Icon:active | svg | `$icon-on-color` | -| Container:focus | border | `$focus` | -| | inset | `$focus-inset` | -| Container:disabled | background-color | `$button-disabled` | -| Label:disabled | text color | `$text-disabled` | -| Icon:disabled | svg | `$icon-disabled` | +Ghost button interactive state color + +| State | Element | Property | Color token | +| -------- | --------- | ---------------- | --------------------- | +| Hover | Label | text-color | `$link-primary-hover` | +| | Icon | svg | `$link-primary-hover` | +| | Container | background-color | `$background-hover` | +| Focus | Container | background-color | `$focus` | +| Active | Container | background-color | `$background-hover` | +| Disabled | Label | text-color | `$text-disabled` | +| | Icon | svg | `$icon-disabled` | + +Ghost icon only button interactive state color + +| State | Element | Property | Color token | +| -------- | --------- | ---------------- | ---------------------- | +| Hover | Container | background-color | `$background-hover` | +| Focus | Container | border | `$focus` | +| Active | Container | background-color | `$background-active` | +| Selected | Container | background-color | `$background-selected` | +| Disabled | Icon | svg | `$icon-disabled` | -![Tertiary danger button states and color](images/button-style-danger-tertiary.png) + + + + +![Ghost button interactive states color](images/button-style-ghost-interactive-states.png) + + + + + +![Ghost icon only button interactive states color](images/button-style-ghost-icon-only-interactive-states.png) + + + + + + + + +### Danger primary button color + +| Element | Property | Color token | +| --------- | ---------------- | ------------------------ | +| Label | text color | `$text-on-color` | +| Icon | svg | `$icon-on-color` | +| Container | background-color | `$button-danger-primary` | + + + + +![Danger primary color](images/button-style-danger-primary.png) + + + + +Danger primary button color + +Danger primary button interactive state color + +| State | Element | Property | Color token | +| -------- | --------- | ---------------- | ------------------------- | +| Hover | Container | background-color | `$button-danger-hover` | +| Focus | Container | border | `$focus` | +| | | inset | `$focus-inset` | +| Active | Container | background-color | `$button-danger-active` | +| Disabled | Label | text-color | `$text-on-color-disabled` | +| | Icon | svg | `$icon-on-color-disabled` | +| | Container | background-color | `$button-disabled` | + + + + +![Danger primary button interactive states color](images/button-style-danger-primary-interactive-states.png) + + + + +Danger primary button interactive state color + +### Danger tertiary button color + +| Element | Property | Color token | +| --------- | ---------- | -------------------------- | +| Label | text color | `$button-danger-secondary` | +| Icon | svg | `$button-danger-secondary` | +| Container | border | `$button-danger-secondary` | + + + + +![Danger tertiary color](images/button-style-danger-tertiary.png) + + + + +Danger tertiary button color + +Danger tertiary button interactive state color + +| State | Element | Property | Color token | +| -------- | --------- | ---------------- | ----------------------- | +| Hover | Label | text-color | `$text-on-color` | +| | Icon | svg | `$icon-on-color` | +| | Container | background-color | `$button-danger-hover` | +| Focus | | border | `$focus` | +| | | inset | `$focus-inset` | +| Active | Label | text-color | `$text-on-color` | +| | Icon | svg | `$icon-on-color` | +| | Container | background-color | `$button-danger-active` | +| Disabled | Label | text-color | `$text-disabled` | +| | Icon | svg | `$icon-disabled` | +| | Container | background-color | `$button-disabled` | + + + + +![Danger tertiary button interactive state color](images/button-style-danger-tertiary-interactive-states.png) -### Ghost danger button - -| Element | Property | Color token | -| ------------------ | ---------------- | -------------------------- | -| Label | text color | `$button-danger-secondary` | -| Icon | svg | `$button-danger-secondary` | -| Container:hover | background-color | `$button-danger-hover` | -| Label:hover | text color | `$text-on-color` | -| Icon:hover | svg | `$icon-on-color` | -| Container:active | background-color | `$button-danger-active` | -| Label:active | text color | `$text-on-color` | -| Icon:active | svg | `$icon-on-color` | -| Container:focus | border | `$focus` | -| | inset | `$focus-inset` | -| Container:disabled | background-color | `$button-disabled` | -| Label:disabled | text color | `$text-disabled` | -| Icon:disabled | svg | `$icon-disabled` | +Danger tertiary button interactive state color + +### Danger ghost button color + +| Element | Property | Color token | +| --------- | ---------------- | -------------------------- | +| Label | text color | `$button-danger-secondary` | +| Icon | svg | `$button-danger-secondary` | +| Container | background-color | `transparent` | -![Ghost danger button states and color](images/button-style-danger-ghost.png) +![Danger ghost button color](images/button-style-danger-ghost.png) +Danger ghost button color + +Danger ghost button button interactive state color + +| State | Element | Property | Color token | +| -------- | --------- | ---------------- | ----------------------- | +| Hover | Label | text-color | `$text-on-color` | +| | Icon | svg | `$icon-on-color` | +| | Container | background-color | `$button-danger-hover` | +| Focus | | border | `$focus` | +| | | inset | `$focus-inset` | +| Active | Label | text-color | `$text-on-color` | +| | Icon | svg | `$icon-on-color` | +| | Container | background-color | `$button-danger-active` | +| Disabled | Label | text-color | `$text-disabled` | +| | Icon | svg | `$icon-disabled` | +| | Container | background-color | `$button-disabled` | + + + + +![Danger ghost button interactive state color](images/button-style-danger-ghost-interactive-states.png) + + + + +Danger ghost button interactive state color + ## Typography Button text should be set in sentence case, with only the first word in a phrase @@ -219,46 +447,81 @@ and any proper nouns capitalized. ## Structure -A button cannot have any element or text within 16 pixels / 1 rem of its -borders. For button groups, the primary button is positioned on the outside of -the set, while the secondary button is positioned inside. 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. - -| Element | Property | px / rem | Spacing token | -| ----------------------- | --------------------------- | -------- | ------------- | -| Button | padding-left | 16 / 1 | `$spacing-05` | -| | padding-right | 64 / 4 | – | -| Button:small | padding-left | 16 / 1 | `$spacing-05` | -| | padding-right | 64 / 4 | – | -| Ghost button | padding-left, padding-right | 16 / 1 | `$spacing-05` | -| Icon only button | margin-left, margin-right | 16 / 1 | `$spacing-05` | -| Icon | svg | 16 x 16 | – | -| Icon: expressive button | size | 20 x 20 | – | -| Focus | box-shadow: inset | 1px | – | +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 + +| Element | Property | px / rem | Spacing token | +| ------------------- | --------------------------- | -------- | ------------- | +| Button without icon | padding-left | 16 / 1 | `$spacing-05` | +| | padding-right | 64 / 4 | `$spacing-10` | +| Button with icon | padding-left, padding-right | 16 / 1 | `$spacing-05` | +| | spacing | 32 / 2 | `$spacing-07` | +| Icon only button | padding-left, padding-right | 16 / 1 | `$spacing-05` | +| Icon | svg | 16 x 16 | – | +| Icon: expressive | size | 20 x 20 | – | +| Focus | box-shadow: inset | 1px | – | + + + + +![Button structure](images/button-style-structure.png) + + + + +Structure measurements for a button | px / rem + +### Ghost button structure + +Ghost and Danger ghost button follow the same structure measurements. + +| 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 icon only button | padding-left, padding-right | 16 / 1 | `$spacing-05` | -![General button structure](images/button-style-structure.png) +![Ghost button structure](images/button-style-structure-ghost.png) -Structure measurements for buttons | px / rem +Structure measurements for ghost button | px / rem -### Recommended +### Button groups structure The following specs are not built into any of the button components but are recommended by design as the proper distance between buttons. -| Attribute | Property | px / rem | Spacing token | -| ---------------- | ------------------------- | -------- | ------------- | -| External: button | margin | 1px | - | -| Button pairings | margin-left, margin-right | 0 | – | +For button groups, the primary button is positioned on the outside of the set, +while the secondary button is positioned inside. -### Sizes +| Element | Property | px / rem | Spacing token | +| ------------- | ------------------------- | -------- | ------------- | +| Button groups | border (fluid) | 1px | – | +| | spacing (fixed) | 16px | `$spacing-05` | +| | margin-left, margin-right | 0 | – | + + + + +![Button groups structure](images/button-style-structure-button-groups.png) + + + + +Structure measurements for button groups | px / rem + +## Sizes There are six button sizes: small, medium, large productive, large expressive, extra large, and 2XL. The large expressive button is used in editorial and @@ -273,12 +536,20 @@ information about specific use cases for each button size. | | Large productive | 48 / 3 | | | Large expressive | 48 / 3 | | Full bleed button | Extra large | 64 / 4 | -| | 2xl | 80 / 5 | +| | 2XL | 80 / 5 | -![Button sizes](images/button_usage_3.png) +![Button sizes](images/button-style-sizes.png) + +Button sizes + +## Feedback + +Help us improve this component by providing feedback, asking questions, and +leaving any other comments on +[GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md). diff --git a/src/pages/components/button/usage.mdx b/src/pages/components/button/usage.mdx index 2112795737e..88f03a06a7c 100755 --- a/src/pages/components/button/usage.mdx +++ b/src/pages/components/button/usage.mdx @@ -8,6 +8,21 @@ tabs: ['Usage', 'Style', 'Code', 'Accessibility'] import A11yStatus from 'components/A11yStatus'; +import { + Add, + Copy, + Download, + Edit, + Export, + Pause, + Play, + Restart, + StopOutline, + SubtractAlt, + TrashCan, + Upload, +} from '@carbon/react/icons'; + Buttons are used to initialize an action. Button labels express what action will @@ -31,6 +46,11 @@ releasing this work in a future version of Carbon. Formatting Content Universal behaviors +Primary button +Secondary button +Tertiary button +Ghost button +Danger button Modifiers Related References @@ -84,13 +104,13 @@ communicate calls to action to the user and allow users to interact with pages in a variety of ways. Button labels express what action will occur when the user interacts with it. -#### When to use +### When to use Use buttons to communicate actions users can take and to allow users to interact -with the page. Each page should have only one primary button, and any remaining +with the page. Each page should have only one primary button. Any remaining calls to action should be represented as lower emphasis buttons. -#### When not to use +### When not to use Do not use buttons as navigational elements. Instead, use [links](https://www.carbondesignsystem.com/components/link/usage) when the @@ -99,37 +119,29 @@ 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 products, so that they message the correct +function to the user. It is, therefore, very important that the different +variants are implemented consistently across productsto convey the correct actions. - - - -![Button variants](images/button_usage_1.png) - - - - -| Variant | Purpose | -| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| _Primary_ | For the principal call to action on the page. Primary buttons should only appear once per screen (not including the application header, modal dialog, or side panel). | -| _Secondary_ | For secondary actions on each page. Secondary buttons can only be used in conjunction with a primary button. As part of a pair, the secondary button's function is to perform the negative action of the set, such as "Cancel" or "Back". Do not use a secondary button in isolation and do not use a secondary button for a positive action. | -| _Tertiary_ | For less prominent, and sometimes independent, actions. Tertiary buttons can be used in isolation or paired with a primary button when there are multiple calls to action. Tertiary buttons can also be used for sub-tasks on a page where a primary button for the main and final action is present. | -| _Danger_ | For actions that could have destructive effects on the user’s data (for example, delete or remove). Danger button has three styles: primary, tertiary, and ghost. | -| _Ghost_ | For the least pronounced actions; often used in conjunction with a primary button. In a situation such as a progress flow, a ghost button may be paired with a primary and secondary button set, where the primary button is for forward action, the secondary button is for "Back", and the ghost button is for "Cancel". | +| Variant | Purpose | +| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Primary](#primary-button) | For the principal call to action on the page. Primary buttons should only appear once per screen (not including the application header, modal dialog, or side panel). | +| [Secondary](#secondary-button) | For secondary actions on each page. Secondary buttons can only be used in conjunction with a primary button. As part of a pair, the secondary button's function is to perform the negative action of the set, such as "Cancel" or "Back". Do not use a secondary button in isolation and do not use a secondary button for a positive action. | +| [Tertiary](#tertiary-button) | For less prominent, and sometimes independent, actions. Tertiary buttons can be used in isolation or paired with a primary button when there are multiple calls to action. Tertiary buttons can also be used for sub-tasks on a page where a primary button for the main and final action is present. | +| [Ghost](#ghost-button) | For the least pronounced actions; often used in conjunction with a primary button. In a situation such as a progress flow, a ghost button may be paired with a primary and secondary button set, where the primary button is for forward action, the secondary button is for "Back", and the ghost button is for "Cancel". | +| [Danger](#danger-button) | For actions that could have destructive effects on the user’s data (for example, delete or remove). Danger button has three styles: primary, tertiary, and ghost. | ## Formatting ### Anatomy -A button’s text 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 contained button the text is always left-aligned, not centered. By default -Carbon uses sentence case for all button labels. +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. -If a text label is not used, an icon should be present to signify what the -button does. +If a label is not used, an icon should be present to signify what the button +does. @@ -139,59 +151,48 @@ button does. +Anatomy of buttons + -#### 1. Contained button +#### 1. Button -A. Text label
B. Container
C. Icon (optional) +A. Label
B. Container
C. Icon (optional) #### 3. Ghost button -A. Text label
C. Icon (optional) +A. Label
C. Icon (optional) -#### 2. Outlined button +#### 2. Tertiary button A. Text label
B. Container
C. Icon (optional) #### 4. Icon button -B. Container (optional)
C. Icon +B. Container
C. Icon - - - -![Do left-align text in a button, even if the button is wide.](images/button_usage_5.png) - - - - -![Do not center text in a button, even if the button is wide.](images/button_usage_6.png) - - - - ### Button sizes -Buttons are named according to their size and usage in the Carbon Sketch kit and -in the code. The table below adds more context around the use case for each -size. For guidance on button heights as well as type sizes and tokens, see -[Sizes](/components/button/style#sizes.mdx) on the Style tab. +The button is available in six different sizes: small, medium, large productive, +large expressive, extra large, and 2XL. The table below adds more context around +the use case for each size. For guidance on button heights as well as type sizes +and tokens, see [Sizes](/components/button/style#sizes.mdx) on the Style tab. -| Button size | Use case | -| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Small | Use when there is not enough vertical space for the default or field-sized button. | -| Medium | Use when buttons are paired with 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 side panels or modals. _Note: This variant is not offered in the kit because it does not have a coded counterpart. Carbon only offers this button in the context of the modal component._ | -| 2XL | Use when buttons bleed to the edge of a larger component, like side panels or modals. _Note: This variant is not offered in the kit because it does not have a coded counterpart. Carbon only offers this button in the context of the modal component._ | +| Button size | Use case | +| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| Small | Use when vertical space is limited or in areas with a confined layout. | +| 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. | +| 2XL | Use when buttons bleed to the edge of a larger component, like in the context of large tearsheets. | @@ -201,12 +202,19 @@ size. For guidance on button heights as well as type sizes and tokens, see +Sizes of buttons in relation to its usage. + ### Emphasis You don’t necessarily need to use the buttons in the order that their labels -imply. For example, you don’t always need to use the secondary button as the -second button in your layout. The most important thing is to establish a visual -hierarchy between the buttons in your UI. Keep these best practices in mind. +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. #### A single, high-emphasis button @@ -220,28 +228,15 @@ A high-emphasis button can be accompanied by medium- and low-emphasis buttons that perform less important actions. Keep in mind that you should only group together calls to action that have a relationship to one another. -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. - - - - -![Button emphasis](images/button_usage_7.png) - - - - -![Do use high-emphasis and medium-emphasis buttons in a button group.](images/button_usage_8_test.png) +![Do use high-emphasis and medium-emphasis buttons in a button group.](images/button_usage_8.png) -![Do not use two high-emphasis buttons in a button group.](images/button_usage_9_test.png) +![Do not use two high-emphasis buttons in a button group.](images/button_usage_9.png) @@ -280,36 +275,39 @@ button locations include: -| 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 panels, 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 | +Alignment of buttons across various layouts. -#### Fluid versus default buttons +| 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. | -Button alignment is also closely related to whether the button is treated as a -default or a fluid element within a layout. When we say “fluid”, we mean that -the button becomes a part of a larger, compound component by bleeding to two or -more edges of its container. Rather than defining the a fluid button’s width in -columns or mini units, its width is defined as a percentage (often 50%) of the -container’s width. Also, as a general rule, fluid primary buttons are never -left-aligned in a layout or a container—they’re always either right-aligned, or -span the full width of the container. +#### Fixed versus fluid buttons -Fluid components like button never exist in isolation. As you can see in the -examples above, they are always part of another component, like modal or form. -Other fluid components include tiles and most recently, form inputs such as -[text inputs](/components/text-input/usage). +Button alignment is also closely related to whether the button is treated as a +fixed or a fluid element within a layout. When we say “fixed,” there is a +[fixed padding](/components/button/style#contained-button-structure.mdx) of 16px +to the left and a 64px padding to the right of the button label. The button +label determines the button’s width. + +When we say “fluid,” we mean that the button becomes a part of a larger, +compound component by bleeding to two or more edges of its container. Rather +than defining the fluid button in columns or mini units, its width is defined as +a percentage (often 50%) of the container’s width. + +Within the layout of a page, primary, secondary, or tertiary variants of buttons +can have fluid widths. In more contained spaces, like in tearsheets or modals, a +ghost button can have a fluid width when paired with other buttons in a group. +Also, as a general rule, fluid buttons are never left-aligned in a layout or a +container—they’re either right-aligned or span the full width of the container. -![Example of a fluid input field and fluid button](images/button_usage_11.png) +![Login screen using a fluid input field and a fluid button.](images/button_usage_11.png) - - Example of a login screen using a fluid input field and a fluid button - +Login screen using a fluid input field and a fluid button. @@ -329,46 +327,43 @@ Other fluid components include tiles and most recently, form inputs such as #### Fluid button border -Many product designers have approached us looking for more guidance around -borders between all fluid buttons. There is a 1px border between all fluid -buttons that call 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. -![Example of $button-separator token border between fluid buttons](images/button_usage_14.png) +![Example of $button-separator token border between fluid buttons.](images/button_usage_14.png) - Example of $button-separator token border between fluid buttons + Example of $button-separator token border between fluid buttons. -#### Fluid-width default buttons +#### Fluid width buttons -The default button’s width is set to the size of the text label with 64px fixed -padding on the right side and 16px fixed padding on the left. However, there is -a hybrid scenario where a floating default-style button can span a designated -number of columns on the responsive column grid, giving it a fluid width. These -are called "fluid-width default buttons." +There is a hybrid scenario where a floating primary, secondary, or tertiary +button can span a designated number of columns on the responsive column grid, +giving it a fluid width. These are called “fluid width buttons.” -Fluid-width default buttons are always preferable to fixed-width default buttons -in a layout. When possible set the default button container’s relative position -to the responsive layout grid and match button width to the width of other -elements on the page. Ideally, when using groups of related buttons (not -including ghost buttons), they should all be the same width. See button groups -below for more detailed information. +Fluid width buttons are always preferable to fixed width default buttons in a +layout. When possible set the button container’s relative position to the +responsive layout grid and match the button width to the width of other elements +on the page. Ideally, when using groups of related buttons (not including ghost +buttons unless in a tearsheet or modal), they should all be the same width. See +button groups below for more detailed information. -![Example of a primary button matching the width of a card in a layout](images/button_usage_15_test.png) +![Example of a primary button matching the width of a card in a layout.](images/button_usage_15.png) - Example of a primary button matching the width of a card in a layout + Example of a primary button matching the width of a card in a layout. @@ -488,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 panels. 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 @@ -520,11 +515,13 @@ button style. ## Content -### Text labels +### Main elements + +#### Button label -A button’s text 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 @@ -542,107 +539,805 @@ recommended action labels. -![Do use the verb + noun content formula in buttons whenever possible](images/button_usage_26.png) +![Do use the verb + noun content formula in buttons whenever possible.](images/button_usage_26.png) -![Do not use only a noun as a button label](images/button_usage_27.png) +![Do not use only a noun as a button label.](images/button_usage_27.png) + + + + +Label alignment + + + + +![Do left-align text in a button, even if the button is wide.](images/button_usage_5.png) + + + + +![Do not center align the label in a button, even if the button is wide.](images/button_usage_6.png) +#### Internationalization (RTL) + +For RTL (right-to-left) languages, the entire button is mirrored horizontally. +The label is right-aligned and the icon is left-aligned. + + + + +![Primary button without and with RTL.](images/button-usage-RTL.png) + + + + +Primary button without and with RTL. + +### Overflow content + +When the button’s label is too long to fit within the available space of the +button, the label should overflow and wrap to the second line. We do not +recommend truncating a button label. + +As mentioned above, it is best practice to keep button label succinct and follow +the {verb} + {noun} content formula. + + + + +![Do wrap the button label to a second line if there’s overflow content.](images/button_usage_overflow_1.png) + + + + +![Do not truncate the label of a button if there’s insufficient space inside the button.](images/button_usage_overflow_2.png) + + + + +### Further guidance + +For further content guidance, see Carbon’s +[content guidelines](https://carbondesignsystem.com/guidelines/content/overview/). + ## Universal behaviors -### Primary button +### Primary button focus The Primary button is the default action. When dialogs appear, the primary button typically takes focus. On a form, if focus is on a component that is not actionable with the `Enter` key, pressing `Enter` will activate the primary button. + + + +![Primary button takes default focus when there’s no other actionable component in a dialog.](images/button_usage_ub_focus.png) + + + + + + Primary button takes default focus when there’s no other actionable component + in a dialog. + + +### States + +The default and interactive states of buttons should follow the +button [Style](/components/button/style#color.mdx) tab guidelines. + ### Interactions #### Mouse Users can trigger a button by clicking anywhere within the button container. + + + +![Mouse interaction for button.](images/button_usage_ub_interaction.png) + + + + +Mouse interaction for button. + #### Keyboard Users can trigger a button by pressing `Enter` or `Space` while the button has focus. For additional keyboard interactions, see the -[accessibility tab](/components/button/accessibility). +[Accessibility](/components/button/accessibility) tab. + +### Validation + +The icon only +[copy button](https://carbondesignsystem.com/components/code-snippet/usage/#copy-to-clipboard) +of code snippet conveys validation after interaction through a tooltip. +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.](images/button-usage-ub-validation.gif) + +![Icon only copy button of code snippet conveying validation through a tooltip.](images/button_usage_ub_validation_4.png) + + + + + + + Icon only copy button of code snippet conveying validation through a tooltip. + + +### Loading + +Buttons can have +[inline loading](https://carbondesignsystem.com/components/inline-loading/usage/) +that provides visual feedback that the action is in process. The button would be +disabled when inline loading is in progress. + + + + + + +![Inline loading in the context of a button.](images/button-usage-ub-inline-loading.gif) + +![Inline loading in the context of a button.](images/button_usage_ub_loading_4.png) + + + + + +Inline loading in the context of a button. + +## Primary button + +Primary button is used for the principal call to action on the page. Primary +button should only appear once per screen (the only exceptions are temporary +flows with primary actions). Primary button helps give the user focus and gives +them context behind the expected next step. + + + + +![Primary button in the context of a product UI.](images/button_usage_primary_1.png) + + + + +Primary button in the context of a product UI. + +#### Temporary flows with primary action + +There may be times when there is a primary button on a page, but through +interaction with the page content, another flow may be launched that has its own +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 +is advised. + + + + +![A temporary user flow where a data table with primary action has an open side panel with its own primary action.](images/button_usage_primary_2.png) + + + + + + A temporary user flow where a data table with primary action has an open side + panel with its own primary action. + + +### Best practices + +#### Not every page needs a primary button + +Sometimes the primary purpose of the page is to interact with other components +or read over content, rather than to trigger an action. In this case, use +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.](images/button_usage_primary_3.png) + + + + + + The primary intent of this page is to present content, with actions like + filtering and editing represented by tertiary and ghost buttons. + + +## Secondary button + +As mentioned in the [Emphasis section](#emphasis),  secondary buttons are +tonally heavy but have less visual prominence than their primary counterparts +due to their lower saturation. As a result, secondary buttons are intended to be +used in conjunction with a primary button. When used in a pair, the secondary +button executes the set's negative action, like "Cancel" or "Back." + + + + +![Secondary button in the context of a product UI.](images/button_usage_secondary_1.png) + + + + +Secondary button in the context of a product UI. + +Secondary buttons should not be used in isolation or for a positive/primary +action. [Button groups](#button-groups) contain more guidance on how to use +secondary buttons. + + + + +![Do use the secondary button in conjunction with the primary button.](images/button_usage_secondary_2.png) + + + + +![Do not use the secondary button in isolation or for a positive/primary action.](images/button_usage_secondary_3.png) + + + + +## Tertiary button + +Tertiary buttons have less prominence than a primary button and slightly more +prominence than a ghost button. Tertiary buttons work well on their own or as +part of a button group. + + + + +![Tertiary button in the context of a product UI.](images/button_usage_tertiary_1.png) + + + + +Tertiary button in the context of a product UI. + +Tertiary buttons should stay aligned with the content of the page. Always make +sure the tertiary button has adequate padding on all sides. As mentioned in the +[fluid button guidance](#alignment), tertiary buttons should not be used in +fluid arrangements. + + + + +![Do align the tertiary button with the rest of the content.](images/button_usage_tertiary_2.png) + + + + +![Do not use a tertiary button in a fluid arrangement.](images/button_usage_tertiary_3.png) + + + + +### Best practices + +#### Tertiary buttons for page headers + +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. + +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 +action. + + + + +![Do use a tertiary button in the page header if there is a primary button in the content section.](images/button_usage_tertiary_4.png) + + + + +![Do not use a primary button in the page header and the content section.](images/button_usage_tertiary_5.png) + + + + +#### Tertiary buttons in button groups + +In [Button groups](#button-groups), where there is one primary and two other +actions with shared importance, consider using tertiary buttons. + + + + +![Example of tertiary buttons used in button groups.](images/button_usage_tertiary_6.png) + + + + +Example of tertiary buttons used in button groups. + +#### Tertiary buttons in empty states + +For empty states that appear on pages that already have the primary action +defined, a tertiary button is the ideal solution to launch a new task flow. + + + + +![Example of a tertiary button used with empty state content.](images/button_usage_tertiary_7.png) + + + + +Example of a tertiary button used with empty state content. + +## Ghost button + +Ghost buttons have the least prominence among the button variants. Ghost buttons +are more subtle, making them ideal for supplementary actions. They work best +when they are flush against a container or horizontally grouped with other +elements. + + + + +![Ghost button in the context of a product UI.](images/button_usage_ghost_1.png) + + + + +Ghost button in the context of a product UI. + +#### 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 +label aligns with the text elsewhere on the page. + + + + +![Do align the ghost button label with the rest of the content.](images/button_usage_ghost_2.png) + + + + +![Do not align the edge of the ghost button with the rest of the content, even if it looks partially aligned.](images/button_usage_ghost_3.png) + + + + +Ghost buttons can be useful for small supplementary actions in side panel. In +this context, extending the width of the ghost button to the full width of the +container makes this treatment seem intentional. Aligning to the full width of a +container is only recommended when the containers are smaller in size such as +side panel of 480px (medium) and below. + + + + +![Do extend the ghost button to the full width of the side panel.](images/button_usage_ghost_4.png) + + + + +![Do not leave a ghost button hanging halfway in the side panel.](images/button_usage_ghost_5.png) + + + + +Ghost buttons can also be aligned horizontally and inline with other components +on the page. + + + + +![Example of a ghost button aligned horizontally and inline with a component.](images/button_usage_ghost_6.png) + + + + + + Example of a ghost button aligned horizontally and inline with a component. + + +### Best practices + +#### Ghost buttons for data table actions + +Buttons in the table toolbar are often depicted as a primary button, but this +might not always be the case. Use a ghost button instead if there is another +button on the page that requires primary styling. + + + + +![A ghost button represents the data table's primary action to avoid conflict with the primary button in the page header.](images/button_usage_ghost_7.png) + + + + + + A ghost button represents the data table's primary action to avoid conflict + with the primary button in the page header. + + +#### Ghost buttons in productive cards + +In dashboards with multiple productive cards, ghost buttons work well as they +draw less attention than a tertiary button. For a ghost button to appear aligned +in vertical arrangements within a container, it is recommended that it touches +at least two edges of the container. + +See +the [cards component](https://pages.github.ibm.com/carbon/ibm-products/components/card/overview/) +for more details. + + + + +![Example of a ghost button used in cards.](images/button_usage_ghost_8.png) + + + + +Example of a ghost button used in cards. + +#### Ghost button used as a cancel action + +Ghost buttons work well as a cancel button in progressive flows, as they draw +less attention; users have to purposefully find and click it to cancel. In +tearsheets, the buttons are fluid which wouldn’t be a suitable application for a +tertiary button. + + + + +![Example of ghost button used in a modal.](images/button_usage_ghost_9.png) + + + + +Example of ghost button used in a modal. + +## Danger button + +Danger button is used for actions that could have destructive effects, such as +“Delete”, “Remove”, or “Stop”. + +The danger button has three different styles: +[primary](/components/button/style#danger-primary-button-color.mdx), +[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 +button may be more appropriate. + + + + +![Danger button in the context of a product UI.](images/button_usage_danger_primary.png) + + + + +Danger button in the context of a product UI. + + + + +![Do use a tertiary danger button for lower emphasis destructive actions.](images/button_usage_danger_tertiary.png) + + + + +![Do use a ghost danger button for lower emphasis destructive actions.](images/button_usage_danger_ghost.png) + + + ## Modifiers -### Buttons with icons +### Button with icon -Icons can be placed next to labels to both clarify an action and call attention -to a button. There are certain instances where an icon will suffice in place of -a text label, but use icon buttons cautiously. +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 -- Glyphs are distinguished by their solid shape and knocked-out details -- Glyphs should always appear to the right of the text + buttons. +- Glyphs are distinguished by their solid shape and knocked-out details. +- Glyphs should always appear to the right of the text. - Glyphs used in buttons must be directly related to the action that the user is - taking -- Glyphs must be the same color value as the text within a button + taking. +- Glyphs must match the color value of the text within a button. -![Do place the icon on the right side of the button after the text](images/button_usage_28.png) +![Do place the icon on the right side of the button after the text](images/button_usage_button_with_icon_1.png) + + + + +![Do not place the icon to the left of the text on the button.](images/button_usage_button_with_icon_2.png) + + + + + + + +![Do use 8px spacing between the label and the icon in a ghost button.](images/button_usage_button_with_icon_3.png) + + + + +![Do not leave too much space between the label and the icon in a ghost button.](images/button_usage_button_with_icon_4.png) + + + + +#### Universal actions with well-established icons + +When deciding whether to add an icon to a button, it’s important to consider how +recognizable the icon is and whether, in other contexts, a similar icon may be +used for a different meaning. We want to avoid the same icon being used for +completely different actions. + +For this reason, we have defined a set of universal actions suitable for adding +an icon alongside the button label. These have clearly defined and widely +recognized icons within IBM Software and beyond. + +| Name of action | Associated icon | Name in icon library | +| -------------- | -------------------------------------------------- | -------------------- | +| Create/Add | | Add | +| Edit | | Edit | +| Copy | | Copy | +| Delete | | Trash can | +| Remove | | Subtract alt | +| Export | | Export | +| Upload | | Upload | +| Download | | Download | +| Play/Start | | Play | +| Pause | | Pause | +| Stop | | Stop outline | +| Refresh | | Restart | + +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 +[Carbon icon library](https://carbondesignsystem.com/elements/icons/library/). + +#### Do not use a defined icon to represent a different universal action + +Using icons in the above list for other actions can confuse the expected outcome +and experience. + + + + +![Do use a defined icon to represent a universal action.](images/button_usage_button_with_icon_5.png) + + + + +![Do not add an icon for an action that would not be associated with it.](images/button_usage_button_with_icon_6.png) + + + + +#### Launch icon + +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, +see [this section](https://pages.github.ibm.com/carbon/ibm-products/guidelines/content/navigation-labels/)  +of our content guide. + + + + +![Example of a tertiary button with icon indicating that clicking the button would launch a new page.](images/button_usage_button_with_icon_7.png) + + + + + + Example of a tertiary button with icon indicating that clicking the button + would launch a new page. + + +### Best practices + +#### Be consistent with icon usage for buttons in a button group + +Using icons in button groups is optional. We recommend showing an icon for each +button in a button group or showing no icons for consistency. A benefit of +pairing an icon with a button label is that it visually describes its action and +directs more attention to it. However, in some cases, using too many buttons +with icons in a group can create unwanted noise in the UI and tend to +overcomplicate a simple experience. + +Only use icons in button groups for the universal actions listed in the table +above or for other actions where a particular icon is commonly paired and +associated. + + + + +![Do follow a consistent approach across button groups for introducing icons.](images/button_usage_button_with_icon_8.png) + + + + +![Do follow a consistent approach across button groups for introducing icons.](images/button_usage_button_with_icon_9.png) + + + + + + + +![Do not introduce icons only for a few buttons in a button group.](images/button_usage_button_with_icon_10.png) + + + + +![Do not introduce icons only for a few buttons in a button group.](images/button_usage_button_with_icon_11.png) - + -![Do not place the icon on the left side of the button before the text](images/button_usage_29.png) +#### 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. + + + + +![Do use the default icon which is “Play”.](images/button_usage_button_with_icon_12.png) + + + + +![Do not use the filled icon variations.](images/button_usage_button_with_icon_13.png) -### Icon-only buttons +### Icon only buttons -Icon 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 +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. + -![Example of an icon-only ghost button in a data table](images/button_usage_30.png) +![Example of an icon only ghost button in a toolbar showing a tooltip on hover.](images/button_usage_icon_only_button_1.png) -Example of an icon-only ghost button in a data table + + Example of an icon only ghost button in a toolbar showing a tooltip on hover. + -### Danger button variations +#### Tooltips for icon only buttons -The danger button has three different styles: primary, tertiary, and ghost. -Determining which danger button style to use will depend on the level of -emphasis you want to give to the danger action. Destructive actions that are -considered 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. +Regardless of how recognizable an icon may or may not be, or whether that action +lies within the universal actions list, a tooltip is always required with text +explaining what the icon button would do if clicked. -![Danger button variations](images/button_usage_31.png) +![Example of an icon only ghost button showing a tooltip on hover.](images/button_usage_icon_only_button_2.png) -Examples of the primary, tertiary, and ghost danger buttons + + Example of an icon only ghost button showing a tooltip on hover. + +#### Colors of icon only ghost buttons + +Carbon builds type, color and spacing tokens into its components, improving the +ease of component usage. Do not change the color token for icon only ghost +buttons. The same applies for specifications across components. Learn more about +icon only ghost button colors in the +[Style](/components/button/style#ghost-button-color.mdx) tab. + + + + +![Do use the system’s defined color for ghost icon only buttons.](images/button_usage_icon_only_button_3.png) + + + + +![Do not change the color for ghost icon only buttons.](images/button_usage_icon_only_button_4.png) + + + + +#### Danger buttons cannot be used in an icon only form + +Danger can be a critical action and should be applied to a button that holds +higher emphasis along with a visual label. As mentioned in +the [danger button guidance](#danger-button),  it is best to use a danger button +in a primary, tertiary, or ghost button form. + + + + +![Do use a visual label in a danger button for a destructive action.](images/button_usage_icon_only_button_5.png) + + + + +![Do not use a danger button in an icon only form for a destructive action.](images/button_usage_icon_only_button_6.png) + + + + ## Related +- [Button labels](https://pages.github.ibm.com/cdai-design/pal/content/button-labels) +- [Fixed button bars](https://pages.github.ibm.com/carbon/ibm-products/patterns/fixed-button-bars/usage/) +- [Form pattern](/patterns/forms-pattern) +- [Icons](https://carbondesignsystem.com/elements/icons/library/) - [Link component](/components/link/usage) +- [Menu buttons](https://carbondesignsystem.com/components/menu-buttons/usage/) - [Modal component](/components/modal/usage) -- [Form pattern](/patterns/forms-pattern) ## References @@ -655,6 +1350,9 @@ danger button or the ghost danger button may be more appropriate. - Artem Syzonenko [_Buttons on the web: placement and order_](https://uxdesign.cc/buttons-placement-and-order-bb1c4abadfcb) (UX Collective, 2019) +- Wiedenbeck, S (1999). The use of icons and labels in an end-user application + program: An empirical study of learning and retention. Behavior & Information + Technology, 18(2), p68–82 ## Feedback