From 54a90166a5e07aa11a89dc52b3b95144a4497304 Mon Sep 17 00:00:00 2001
From: Jess <53754871+jessover9000@users.noreply.github.com>
Date: Thu, 14 May 2020 11:39:34 +0200
Subject: [PATCH] @grafana/ui: Buttons documentation (#23144)

* Add info: when to use which and how to mix buttons

* Update description for Button.mdx

- add note about scenario without primary action
- add note about secondary button being the default

* Refine docs info for secondary and destructive

Co-authored-by: Tobias Skarhed <tobias.skarhed@gmail.com>
---
 packages/grafana-ui/src/components/Button/Button.mdx | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/packages/grafana-ui/src/components/Button/Button.mdx b/packages/grafana-ui/src/components/Button/Button.mdx
index 3a7126f061d..730a238e4f6 100644
--- a/packages/grafana-ui/src/components/Button/Button.mdx
+++ b/packages/grafana-ui/src/components/Button/Button.mdx
@@ -7,7 +7,9 @@ import { Button } from './Button';
 
 ## Primary
 
-Used for "call to action".
+Used for "call to action", i.e. triggering the main action. There should never be more than one on a page. If you need multiple buttons for different actions, decide which action is the most important and make that the primary `Button`. All other `Button` components should be secondary.
+
+If there is no primary action, all `Button` components should be secondary.
 
 <Preview>
   <div>
@@ -25,7 +27,10 @@ Used for "call to action".
 
 ## Secondary
 
-The secondary button, used for "cancel" or aborting.
+The secondary `Button` is the default button style and can trigger various actions. How it is used depends on its surroundings:
+
+1. When next to the primary `Button`, the Secondary style can for example be used for "Cancel" or "Abort" actions. 
+2. When there is no main important action on a given page, all `Button` components should use the secondary style.
 
 <Preview>
   <div>
@@ -43,7 +48,7 @@ The secondary button, used for "cancel" or aborting.
 
 ## Destructive
 
-Used for removing or deleting entities.
+Used for triggering a removing or deleting action. Because of its dominant coloring, it should be used sparingly. If you need multiple Destructive `Button` components in one view, we recommend using a secondary `Button` or Link variant instead and only use the Destructive variant to double confirm.
 
 <Preview>
   <div>