Merge pull request #382 from JasonEtco/btn-link-fixes

Update Button docs

Author: broccolini

modules/primer-buttons/README.md

@@ -42,41 +42,9 @@ status: Stable
 
 Buttons are used for **actions**, like in forms, while textual hyperlinks are used for **destinations**, or moving from one page to another.
 
-#### Buttons
+{:toc}
 
-```html
-<button class="m-1 btn" type="button">Close</button>
-<button class="m-1 btn btn-primary" type="button">Comment</button>
-<button class="m-1 btn btn-danger" type="button">Rename repository</button>
-<button class="m-1 btn btn-blue" type="button">Sign up for free</button>
-<button class="m-1 btn btn-purple" type="button">Try if for free</button>
-<br>
-<button class="m-1 btn hover" type="button">Close</button>
-<button class="m-1 btn btn-primary hover" type="button">Comment</button>
-<button class="m-1 btn btn-danger hover" type="button">Rename repository</button>
-<button class="m-1 btn btn-blue hover" type="button">Sign up for free</button>
-<button class="m-1 btn btn-purple hover" type="button">Try if for free</button>
-<br>
-<button class="m-1 btn focus" type="button">Close</button>
-<button class="m-1 btn btn-primary focus" type="button">Comment</button>
-<button class="m-1 btn btn-danger focus" type="button">Rename repository</button>
-<button class="m-1 btn btn-blue focus" type="button">Sign up for free</button>
-<button class="m-1 btn btn-purple focus" type="button">Try if for free</button>
-<br>
-<button class="m-1 btn selected" type="button">Close</button>
-<button class="m-1 btn btn-primary selected" type="button">Comment</button>
-<button class="m-1 btn btn-danger selected" type="button">Rename repository</button>
-<button class="m-1 btn btn-blue selected" type="button">Sign up for free</button>
-<button class="m-1 btn btn-purple selected" type="button">Try if for free</button>
-<br>
-<button class="m-1 btn disabled" type="button">Close</button>
-<button class="m-1 btn btn-primary disabled" type="button">Comment</button>
-<button class="m-1 btn btn-danger disabled" type="button">Rename repository</button>
-<button class="m-1 btn btn-blue disabled" type="button">Sign up for free</button>
-<button class="m-1 btn btn-purple disabled" type="button">Try if for free</button>
-```
-
-#### Default buttons
+## Default button
 
 Use the standard—yet classy—`.btn` for form actions and primary page actions. These are used extensively around the site.
 
@@ -94,7 +62,7 @@ You can find them in two sizes: the default `.btn` and the smaller `.btn-sm`.
 <button class="btn btn-sm" type="button">Small button</button>
 ```
 
-#### Primary
+## Primary button
 
 Primary buttons are green and are used to indicate the *primary* action on a page. When you need your buttons to stand out, use `.btn.btn-primary`. You can use it with both button sizes—just add `.btn-primary`.
 
@@ -103,7 +71,7 @@ Primary buttons are green and are used to indicate the *primary* action on a pag
 <button class="btn btn-sm btn-primary" type="button">Small primary button</button>
 ```
 
-#### Danger
+## Danger button
 
 Danger buttons are red. They help reiterate that the intended action is important or potentially dangerous (e.g., deleting a repo or transferring ownership). Similar to the primary buttons, just add `.btn-danger`.
 
@@ -112,7 +80,7 @@ Danger buttons are red. They help reiterate that the intended action is importan
 <button class="btn btn-sm btn-danger" type="button">Small danger button</button>
 ```
 
-#### Outline
+## Outline button
 
 Outline buttons downplay an action as they appear like boxy links. Just add `.btn-outline` and go.
 
@@ -121,7 +89,7 @@ Outline buttons downplay an action as they appear like boxy links. Just add `.bt
 <button class="btn btn-sm btn-outline" type="button">Outline button</button>
 ```
 
-#### Large button
+## Large button
 Use `.btn-large` to increase the padding and border radius of a button. This is useful for prominent calls to action in hero sections.
 
 [Type scale utilities](https://styleguide.github.com/primer/utilities/typography/#type-scale-utilities) can be used to alter the font-size if needed. Padding is applied in em's so that it scales proportionally with the font-size.
@@ -146,7 +114,7 @@ Use `.btn-large` with a type scale utility to transform the text to a bigger siz
 
 ```
 
-#### Disabled state
+## Disabled state
 
 Disable `<button>` elements with the boolean `disabled` attribute and `<a>` elements with the `.disabled` class.
 
@@ -172,7 +140,7 @@ Similar styles are applied to primary, danger, and outline buttons:
 <a class="btn btn-outline disabled" href="#url" role="button">Disabled button</a>
 ```
 
-#### Block buttons
+## Block button
 
 Make any button full-width by adding `.btn-block`. It adds `width: 100%;`, changes the `display` from `inline-block` to `block`, and centers the button text.
 
@@ -181,7 +149,17 @@ Make any button full-width by adding `.btn-block`. It adds `width: 100%;`, chang
 <p><button class="btn btn-sm btn-block" type="button">Small block button</button></p>
 ```
 
-#### With counts
+## Link button
+
+Create a button that looks like a link with `.btn-link`. Rather than using an `<a>` to trigger JS, this style on a `<button>` should be used for better accessibility.
+
+**The `.btn-link` class is not designed to be used with `.btn`; the overlapping styles are not compatible.**
+
+```html
+<p><button class="btn-link" type="button">Link button</button></p>
+```
+
+## Button with counts
 
 You can easily append a count to a **small button**. Add the `.with-count` class to the `.btn-sm` and then add the `.social-count` after the button.
 
@@ -221,7 +199,7 @@ You can also use the [counter](../../product/components/labels) component within
 </button>
 ```
 
-#### Button groups
+## Button groups
 
 Have a hankering for a series of buttons that are attached to one another? Wrap them in a `.BtnGroup` and the buttons will be rounded and spaced automatically.
 
@@ -258,7 +236,7 @@ Add `.BtnGroup-form` to `<form>`s within `.BtnGroup`s for proper spacing and rou
 </div>
 ```
 
-#### Hidden text button
+## Hidden text button
 
 Use `.hidden-text-expander` to indicate and toggle hidden text.
 
@@ -271,7 +249,7 @@ Use `.hidden-text-expander` to indicate and toggle hidden text.
 You can also make the expander appear inline by adding `.inline`.
 
 
-#### Using button styles with the details summary element
+## Using button styles with the details summary element
 
 You can add `.btn` and `.btn-*` classes to any
 [`<summary>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/summary)

modules/primer-buttons/stories.js

@@ -65,3 +65,8 @@ storiesOf('Button', module)
       <button className="btn btn-large btn-outline-blue" type="button">Large button button</button>
     </div>
   ))
+  .add('btn-link', () => (
+      <div className='p-4 d-flex flex-justify-between'>
+        <button className='btn-link'>Button</button>
+      </div
+  ))