Add guidance for secondary and destructive buttons

Co-authored-by: Tim Paul <contact@timpaul.co.uk>
Co-authored-by: amyhupe <amy.hupe@digital.cabinet-office.gov.uk>

src/components/button/index.md.njk

@@ -36,12 +36,46 @@ Align the primary action button to the left edge of your form.
 
 There are 2 ways to use the button component. You can use HTML or, if you are using [Nunjucks](https://mozilla.github.io/nunjucks/) or the [GOV.UK Prototype Kit](https://govuk-prototype-kit.herokuapp.com), you can use the Nunjucks macro.
 
+### Default buttons
+
+Use a default button for the main call to action on a page.
+
+Avoid using multiple default buttons on a single page. Having more than one main call to action reduces their impact, and makes it harder for users to know what to do next.
+
+{{ example({group: "components", item: "button", example: "default", html: true, nunjucks: true, open: false}) }}
+
 ### Start buttons
 
-Use a start button as the main call to action on your service’s start page.
+Use a start button for the main call to action on your service’s [start page](/patterns/start-pages/).
 
 {{ example({group: "components", item: "button", example: "start", html: true, nunjucks: true, open: false}) }}
 
+### Secondary buttons
+
+Use secondary buttons for secondary calls to action on a page.
+
+Pages with too many calls to action make it hard for users to know what to do next. Before adding lots of secondary buttons, try to simplify the page or break the content down across multiple pages.
+
+{{ example({group: "components", item: "button", example: "secondary", html: true, nunjucks: true, open: false}) }}
+
+You can use secondary buttons in combination with default buttons.
+
+{{ example({group: "components", item: "button", example: "secondary-combo", html: true, nunjucks: true, open: false}) }}
+
+### Warning buttons
+
+Warning buttons are designed to make users think carefully before they use them. They only work if used very sparingly. Most services should not need one.
+
+{{ example({group: "components", item: "button", example: "warning", html: true, nunjucks: true, open: false}) }}
+
+Only use warning buttons for actions with serious destructive consequences that cannot be easily undone by a user. For example, permanently deleting an account.
+
+When letting users carry out an action like this, it's a good idea to include an additional step which asks them to confirm it.
+
+In this instance, use another style of button for the initial call to action, and a warning button for the final confirmation.
+
+Do not only rely on the red colour of a warning button to communicate the serious nature of the action. This is because not all users will be able to see the colour or will understand what it signifies. Make sure the context and button text make clear what will happen if the user selects it.
+
 ### Disabled buttons
 
 Disabled buttons have poor contrast and can confuse some users, so avoid them if possible.
@@ -56,21 +90,21 @@ Sometimes, users double click buttons because they:
 
 - have used operating systems where they have to double click items to make them work
 - are experiencing a slow connection which means they are not given feedback on their action quickly enough
-- have motor impairments such as hand tremors which cause them to click the button involuntarily 
+- have motor impairments such as hand tremors which cause them to click the button involuntarily
 
-In some cases, this can mean their information is sent twice. 
+In some cases, this can mean their information is sent twice.
 
-For example, the GOV.UK Notify team discovered that a number of users were receiving invitations twice, because the person sending them was double clicking the “send” button. 
+For example, the GOV.UK Notify team discovered that a number of users were receiving invitations twice, because the person sending them was double clicking the “send” button.
 
-If you are working in production and research shows that users are frequently sending information twice, you can configure the button to ignore the second click. 
+If you are working in production and research shows that users are frequently sending information twice, you can configure the button to ignore the second click.
 
 To do this, set the `data-prevent-double-click` attribute to `true`. You can do this directly in the HTML or, if you’re using Nunjucks, you can use the Nunjucks macro as shown in this example.
 
 {{ example({group: "components", item: "button", example: "preventDoubleClick", html: true, nunjucks: true, open: false}) }}
 
 This feature will prevent double clicks for users that have JavaScript enabled, however you should also think about the issue server-side to protect against attacks.
 
-In the case of slow connections, aim to give the user information about what’s happening, for example, by showing a loading spinner or a modal, before using `data-prevent-double-click`. 
+In the case of slow connections, aim to give the user information about what’s happening, for example, by showing a loading spinner or a modal, before using `data-prevent-double-click`.
 
 ## Research on this component
 

src/components/button/link/index.njk

@@ -0,0 +1,10 @@
+---
+title: Link button
+layout: layout-example.njk
+---
+{% from "button/macro.njk" import govukButton %}
+
+{{ govukButton({
+  text: "Cancel",
+  classes: "govuk-button--link"
+}) }}

src/components/button/quiet-primary/index.njk

@@ -0,0 +1,10 @@
+---
+title: Quiet primary button
+layout: layout-example.njk
+---
+{% from "button/macro.njk" import govukButton %}
+
+{{ govukButton({
+  text: "Copy link",
+  classes: "govuk-button--alt"
+}) }}

src/components/button/secondary-combo/index.njk

@@ -0,0 +1,16 @@
+---
+title: Secondary button combo
+layout: layout-example.njk
+---
+{% from "button/macro.njk" import govukButton %}
+
+{{ govukButton({
+  text: "Save and continue",
+  classes: "govuk-!-margin-right-1"
+}) }}
+
+{{ govukButton({
+  text: "Save as draft",
+  classes: "govuk-button--secondary"
+}) }}
+

src/components/button/secondary/index.njk

@@ -0,0 +1,10 @@
+---
+title: Secondary button
+layout: layout-example.njk
+---
+{% from "button/macro.njk" import govukButton %}
+
+{{ govukButton({
+  text: "Find address",
+  classes: "govuk-button--secondary"
+}) }}

src/components/button/stacking-example/index.njk

@@ -0,0 +1,24 @@
+---
+title: Stacking buttons example
+layout: layout-example.njk
+---
+{% from "button/macro.njk" import govukButton %}
+
+<div class="govuk-grid-row">
+  <div class="govuk-grid-column-two-thirds">
+    <h1 class="govuk-heading-l">Two-thirds column</h1>
+    <p class="govuk-body">This is a paragraph inside a two-thirds wide column</p>
+  </div>
+  <div class="govuk-grid-column-one-third">
+    {{ govukButton({
+      text: "Publish",
+      classes: "govuk-!-width-full govuk-!-margin-bottom-2"
+    }) }}
+
+    {{ govukButton({
+      text: "Preview",
+      classes: "govuk-button--secondary govuk-!-width-full"
+    }) }}
+
+  </div>
+</div>

src/components/button/warning/index.njk

@@ -0,0 +1,10 @@
+---
+title: Warning button
+layout: layout-example.njk
+---
+{% from "button/macro.njk" import govukButton %}
+
+{{ govukButton({
+  text: "Delete account",
+  classes: "govuk-button--warning"
+}) }}