@ithaka/bonsai/documentation/pages/components/button.md

ITHAKA core styling

---
title: Buttons
description: A button refers to any graphical control element that provides the user a simple way to trigger an event.  The sole requirement of a button interaction is that the user can execute a command by click or touching action
foundation: http://foundation.zurb.com/sites/docs/button.html
sass: ./scss/_buttons.scss
---

## How to Use

### Basic
```html_example
<button class="button">Primary button</button> 
<button class="button secondary">Secondary button</button> 
<button class="button disabled">Disabled button</button>
<button type="button" class="button secondary disabled">Secondary disabled</button>
<button disabled type="button" class="button">Disabled via HTML</button>
<button class="button region">Button region</button>
```

### Ghost
Ghost buttons are white with a transparent background and work best on a dark background container
```html_example
<div class="medium-4">
    <div class="card very-dark-gray-background">
        <div class="card-header white-color">
            Card Heading
        </div>
        <div class="card-section white-color">
            <p>
                Lorem ipsum dolor sit amet, consectetur adipiscing
                elit. Integer placerat massa quis arcu sodales, in
                sollicitudin velit tincidunt.
            </p>
            <button class="button ghost">Ghost Button</button>
        </div>
    </div>
</div>
```

#### Accessibility
1. Buttons should display a visible focus state when users tab to them.
2. Ensure that disabled buttons are clearly labelled as such and do not rely on color to express their meaning.
3. Ensure a minimum contrast ratio of 4.5:1 (for small text, 3:1 for large) for all states of the button. This includes default, hover, selected, and disabled.

### Sizes
```html_example
<button type="button" class="button small">Small</button>
<button type="button" class="button">Regular</button>
<button type="button" class="button large">Large</button>
<div>
    <button type="button" class="button expanded">Sooo expanded</button>
</div>
```

#### Accessibility
1. Consider touch target size, at least 48 CSS pixels tall/wide, and spacing for smaller view ports. (45-57 pixels is the average width of an index finger. thumbs are 72 pixels.).


### Links as Buttons
```html_example
<a href="#" class="button">Primary link</a>
<a href="#" class="button secondary">Secondary link</a>
<a href="#" class="button disabled">Disabled link</a>
<a href="#" class="button secondary disabled">Secondary disabled link</a>
<a href="#" class="button region">Region link</a>
```

#### Accessibility
1. When styling links to look like buttons, remember that screen readers handle links slightly differently than they do buttons. Pressing the Space key triggers a button, but pressing the Enter key triggers a link.

### Inline Buttons
```html_example
<div class="input-group">
    <input id="input-with-button" type="text" class="input-group-field" placeholder="I have an inline button">
    <label for="input-with-button" class="visuallyhidden">Input with inline button</label>
    <div class="input-group-button">
        <button class="button"><i class="icon-search"></i></button>
    </div>
</div>
<div class="input-group">
    <input id="input-with-secondary-button" type="text" class="input-group-field" placeholder="I have an inline button">
    <label for="input-with-secondary-button" class="visuallyhidden">Input with inline button</label>
    <div class="input-group-button">
        <button class="button secondary"><i class="icon-search"></i></button>
    </div>
</div>
```

### Composite Buttons

Here is a button that includes both an icon and a tooltip

```html_example
<button class="button region has-tip" data-tooltip aria-haspopup="true" data-click-open="false" title="I'm a button with an icon and tooltip">
    <span class="fa-stack fa-1x add-note">
        <i class="icon-sticky-note fa-stack-2x"></i>
        <i class="icon-plus white-color icon-small fa-stack-2x"></i>
    </span>
    <span class="block">Icon button</span>
</button>
<button class="button region has-tip" data-tooltip aria-haspopup="true" data-click-open="false" title="I'm a disabled button region" disabled=true>
    <span class="fa-stack fa-1x add-note">
        <i class="icon-sticky-note fa-stack-2x"></i>
        <i class="icon-plus white-color icon-small fa-stack-2x"></i>
    </span>
    <span class="block">Disabled button region</span>
</button>
```

## Guidelines
1. Use primary buttons for actions that go to the next step and use secondary buttons for actions that happen on the current page.
2. Less popular or less important actions may be visually styled as links.
3. Use sentence case for button labels. _*Note: as of 2017-08-11 JSTOR is still using title case_
4. Button labels should be as short as possible with “trigger words” that your users will recognize to clearly explain what will happen when the button is clicked (for example, “download,” “view” or “sign up”). Make the first word of the button’s label a verb. For example, instead of “Complaint Filing” label the button “File a complaint.”
5. When using icons as buttons, it is acceptable to not have a label only if the icon is a standard icon, like download. 
6. If there is any question about the meaning of the icon, pair it with a label.
7. If there is any information on hover over a button, make sure that information is available in another method for a user

## Avoid
1. Don't use too many button styles on a page.
2. Don't use `div` or `img` tags to create buttons (even disabled ones). Screen readers don't automatically know either is a usable button.