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

ITHAKA core styling

---
title: Icons
description: Icons help provide context for users to improve usability.
sass: ./scss/_icons.scss
---

## How to Use
We’re using [Font Awesome](http://fontawesome.io/icons/) icon library, locked at version 4.7, for our icons.
Icon classes provide the default color and orientation. Additional styling needs to be applied to change colors.
The default icon font size (`$bonsai-icon-size`) is `$bonsai-spacing-base * 5`.


### Basic Example

```html_example
<i class="icon-trash" aria-hidden="true" aria-label="Click to delete list"></i>
```
<br />

### Size Example

```html_example
<i class="icon-check icon-small" aria-hidden="true"></i>
<i class="icon-check icon-large" aria-hidden="true"></i>
```
<br />

### Color Example

View the [colors documentation](/styleguide/colors.html) for a full range of color options.

```html_example
<i class="icon-thumbs-o-up blue-color" aria-label="Thumbs up. These topics are helpful."></i>
```
<br />

### Full Table of Icons

<table class="unstriped hover">
    <thead>
        <tr>
            <th>Icon</th>
            <th>CSS class</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><i class="icon-arrow-circle-down" aria-hidden="true"></i></td>
            <td><code>icon-arrow-circle-down</code></td>
        </tr>
        <tr>
            <td><i class="icon-arrow-circle-right" aria-hidden="true"></i></td>
            <td><code>icon-arrow-circle-right</code></td>
        </tr>
        <tr>
            <td><i class="icon-arrow-circle-up" aria-hidden="true"></i></td>
            <td><code>icon-arrow-circle-up</code></td>
        </tr>
        <tr>
            <td><i class="icon-arrow-down" aria-hidden="true"></i></td>
            <td><code>icon-arrow-down</code></td>
        </tr>
        <tr>
            <td><i class="icon-arrow-left" aria-hidden="true"></i></td>
            <td><code>icon-arrow-left</code></td>
        </tr>
        <tr>
            <td><i class="icon-arrow-right" aria-hidden="true"></i></td>
            <td><code>icon-arrow-right</code></td>
        </tr>
        <tr>
            <td><i class="icon-arrow-up" aria-hidden="true"></i></td>
            <td><code>icon-arrow-up</code></td>
        </tr>
        <tr>
            <td><i class="icon-check" aria-hidden="true"></i></td>
            <td><code>icon-check</code></td>
        </tr>
        <tr>
            <td><i class="icon-check-circle" aria-hidden="true"></i></td>
            <td><code>icon-check-circle</code></td>
        </tr>
        <tr>
            <td><i class="icon-check-circle-o" aria-hidden="true"></i></td>
            <td><code>icon-check-circle-o</code></td>
        </tr>
        <tr>
            <td><i class="icon-chevron-down" aria-hidden="true"></i></td>
            <td><code>icon-chevron-down</code></td>
        </tr>
        <tr>
            <td><i class="icon-chevron-left" aria-hidden="true"></i></td>
            <td><code>icon-chevron-left</code></td>
        </tr>
        <tr>
            <td><i class="icon-chevron-right" aria-hidden="true"></i></td>
            <td><code>icon-chevron-right</code></td>
        </tr>
        <tr>
            <td><i class="icon-circle" aria-hidden="true"></i></td>
            <td><code>icon-circle</code></td>
        </tr>
        <tr>
            <td><i class="icon-clipboard" aria-hidden="true"></i></td>
            <td><code>icon-clipboard</code></td>
        </tr>
        <tr>
            <td><i class="icon-close" aria-hidden="true"></i></td>
            <td><code>icon-close</code></td>
        </tr>
        <tr>
            <td><i class="icon-download" aria-hidden="true"></i></td>
            <td><code>icon-download</code></td>
        </tr>
        <tr>
            <td><i class="icon-exclamation" aria-hidden="true"></i></td>
            <td><code>icon-exclamation</code></td>
        </tr>
        <tr>
            <td><i class="icon-exclamation-circle" aria-hidden="true"></i></td>
            <td><code>icon-exclamation-circle</code></td>
        </tr>
        <tr>
            <td><i class="icon-facebook" aria-hidden="true"></i></td>
            <td><code>icon-facebook</code></td>
        </tr>
        <tr>
            <td><i class="icon-facebook-official" aria-hidden="true"></i></td>
            <td><code>icon-facebook-official</code></td>
        </tr>
        <tr>
            <td><i class="icon-file-text-o" aria-hidden="true"></i></td>
            <td><code>icon-file-text-o</code></td>
        </tr>
        <tr>
            <td><i class="icon-info-circle" aria-hidden="true"></i></td>
            <td><code>icon-info-circle</code></td>
        </tr>
        <tr>
            <td><i class="icon-laptop" aria-hidden="true"></i></td>
            <td><code>icon-laptop</code></td>
        </tr>
        <tr>
            <td><i class="icon-long-arrow-up" aria-hidden="true"></i></td>
            <td><code>icon-long-arrow-up</code></td>
        </tr>
        <tr>
            <td><i class="icon-long-arrow-down" aria-hidden="true"></i></td>
            <td><code>icon-long-arrow-down</code></td>
        </tr>
        <tr>
            <td><i class="icon-minus" aria-hidden="true"></i></td>
            <td><code>icon-minus</code></td>
        </tr>
        <tr>
            <td><i class="icon-phone" aria-hidden="true"></i></td>
            <td><code>icon-phone</code></td>
        </tr>
        <tr>
            <td><i class="icon-plus" aria-hidden="true"></i></td>
            <td><code>icon-plus</code></td>
        </tr>
        <tr>
            <td><i class="icon-plus-circle" aria-hidden="true"></i></td>
            <td><code>icon-plus-circle</code></td>
        </tr>
        <tr>
            <td><i class="icon-question" aria-hidden="true"></i></td>
            <td><code>icon-question</code></td>
        </tr>
        <tr>
            <td><i class="icon-question-circle" aria-hidden="true"></i></td>
            <td><code>icon-question-circle</code></td>
        </tr>
        <tr>
            <td><i class="icon-quote-left" aria-hidden="true"></i></td>
            <td><code>icon-quote-left</code></td>
        </tr>
        <tr>
            <td><i class="icon-quote-right" aria-hidden="true"></i></td>
            <td><code>icon-quote-right</code></td>
        </tr>
        <tr>
            <td><i class="icon-search" aria-hidden="true"></i></td>
            <td><code>icon-search</code></td>
        </tr>
        <tr>
            <td><i class="icon-shopping-cart" aria-hidden="true"></i></td>
            <td><code>icon-shopping-cart</code></td>
        </tr>
        <tr>
            <td><i class="icon-thumbs-down" aria-hidden="true"></i></td>
            <td><code>icon-thumbs-down</code></td>
        </tr>
        <tr>
            <td><i class="icon-thumbs-up" aria-hidden="true"></i></td>
            <td><code>icon-thumbs-up</code></td>
        </tr>
        <tr>
            <td><i class="icon-thumbs-o-down" aria-hidden="true"></i></td>
            <td><code>icon-thumbs-o-down</code></td>
        </tr>
        <tr>
            <td><i class="icon-thumbs-o-up" aria-hidden="true"></i></td>
            <td><code>icon-thumbs-o-up</code></td>
        </tr>
        <tr>
            <td><i class="icon-times-circle" aria-hidden="true"></i></td>
            <td><code>icon-times-circle</code></td>
        </tr>
        <tr>
            <td><i class="icon-trash" aria-hidden="true"></i></td>
            <td><code>icon-trash</code></td>
        </tr>
        <tr>
            <td><i class="icon-twitter" aria-hidden="true"></i></td>
            <td><code>icon-twitter</code></td>
        </tr>
        <tr>
            <td><i class="icon-unlock-alt" aria-hidden="true"></i></td>
            <td><code>icon-unlock-alt</code></td>
        </tr>
    </tbody>
</table>

## Guidelines
1. Use icons sparingly and always with a label, tooltip, or description.
1. Icons should be large enough for a user to tap with their finger.
1. If it takes longer than 5 seconds to think of an icon, there probably isn't a good option to effectively convey meaning.

## Accessibility
1. See [Font Awesome Accessibility Guide](http://fontawesome.io/accessibility/) to ensure your icons are accessible.
1. Add `aria-hidden="true"` to icons that are purely decoration.
1. In addition, it's a good idea to provide an additional element, such as a `<span>` with description that is only picked up by screen readers (`.visuallyhidden`). Furthermore, adding a `title` attribute to the icon can provide a visible description to sighted users.
1. For interactive icons, do not add `aria-hidden="true"`, but instead use the `aria-label="{your description here}"`.