**[ This description is mirrored from README.md at [github.com/BrightspaceUI/icons](https://github.com//BrightspaceUI/icons/blob/v6.7.1/README.md) on 2019-05-22 ]** # d2l-icons [](https://www.webcomponents.org/element/BrightspaceUI/icons) [![Bower version][bower-image]][bower-url] [![Build status][ci-image]][ci-url] `d2l-icons` contains SVGs, [Polymer](https://www.polymer-project.org/)-based web components and [Sass mixins](http://sass-lang.com) to incorporate D2L iconography into your application. ## Installation `d2l-icons` can be installed from [Bower][bower-url]: ```shell bower install d2l-icons ``` ## Icon Categories Each icon is grouped into a category, and every icon in a particular category has the same native size. Currently, there are 5 icon categories: | Category Name | Description | Samples | Size | List | | :----: | --- | :---: | :---: | :---: | | tier1 | minimal level of detail, solid style |        | `18px` x `18px` | [Full set](d2l-icons.md#tier1) | | tier2 | medium level of detail, linear style |        | `24px` x `24px` | [Full set](d2l-icons.md#tier2) | | tier3 | medium level of detail, linear style |        | `30px` x `30px` | [Full set](d2l-icons.md#tier3) | | html-editor | for use in the HTML editor |        | `18px` x `18px` | [Full set](d2l-icons.md#html-editor) | | emoji | for all your emoji needs, same detail/style as tier1 |        | `18px` x `18px` | [Full set](d2l-icons.md#emoji) | **[> Browse ALL categories and icons](d2l-icons.md)** **Note:** Always choose the icon whose native size best matches your desired icon size, ideally exactly. ## Usage There are many ways to consume icons -- the best technique depends on your application, technology stack and use case. ### Polymer Icon Sets If your application is using Google's [Polymer](https://www.polymer-project.org/) framework, `d2l-icons` exposes [iron-iconset-svg](https://elements.polymer-project.org/elements/iron-iconset-svg) collections for usage with the Polymer [iron-icon](https://elements.polymer-project.org/elements/iron-icon) web component. An iconset collection is available for each category (tier1, tier2, etc.), named `{category}-icons.html`. Also, an HTML import which imports ALL categories is also available by including `d2l-icons.html`. Here's an example which consumes the "bookmark-filled" icon from the "tier1" category using an `iron-icon` web component: ```html ``` You'll need to set the size (ideally 18px, 24px or 30px) and color (ferrite, `#494c4e`) of the icon. [d2l-colors](https://github.com/Brightspace/d2l-colors-ui) comes in handy: ```html ``` If you'd like a different color when the user hovers: ```css iron-icon:hover { color: var(--d2l-color-celestine-minus-1); } ``` Advantages: - color can be manipulated using CSS - size can be manipulated using CSS Disadvantages: - requires Google Polymer - default color (ferrite) must be set - size must be set - no automatic support for right-to-left icons ### <d2l-icon> Web Component Using Google's [iron-iconset-svg](https://elements.polymer-project.org/elements/iron-iconset-svg) and [iron-icon](https://elements.polymer-project.org/elements/iron-icon) directly (see above) works just fine, however we've created a wrapper component called `` which will automatically set the correct icon size, color, and mirror the icon horizontally for right-to-left languages. ```html ``` It can be used identically to ``: ```html ``` The color will default to ferrite, and the size will be set automatically based on the category name. To swap the color on-hover: ```css d2l-icon:hover { color: var(--d2l-color-celestine-minus-1); } ``` If you'd like to use a non-standard size, set the `d2l-icon-height/width` variables in a [custom style block](https://www.polymer-project.org/1.0/docs/devguide/styling#custom-style): ```html ``` Advantages: - color (ferrite) is automatically set - size is automatically set based on the icon category - color can be manipulated using CSS - size can be manipulated using CSS - automatic support for right-to-left icons Disadvantages: - requires Google Polymer ### Directly with an `` element Simply point an HTML `` element's `src` attribute at the icon's SVG file. You can reference the files directly from `bower_components`, or copy the icons you need as part of your application's build process. HTML: ```html ``` Don't forget to provide alternate text if the icon isn't accompanied by any other text. Advantages: - easy -- no other tech needed - color (ferrite) is automatically set - size is automatically set - size can be manipulated using CSS Disadvantages: - no ability to change the color - no automatic support for right-to-left icons ### Background Images In cases where the icon is purely decorative (it doesn't provide any additional information) and is accompanied by text and/or a tooltip, applying the icon using a background image can be a good approach. It hides the icon from assistive technology (like a screen reader), allowing the accompanying text to stand alone. First, create some CSS that points at the image you'd like and sets the correct size: ``` .my-app-bookmark-icon { background: url('bower_components/d2l-icons/tier1/bookmark-filled.svg'); background-size: 18px 18px; /* needed for IE */ display: inline-block; height: 18px; width: 18px; } ``` Then apply the CSS class to an element: ```html Bookmark ``` Advantages: - easy -- no other tech needed - color (ferrite) is automatically set - size can be manipulated using CSS Disadvantages: - no ability to change the color - size must be set - no automatic support for right-to-left icons #### Background images with invisible text If you would prefer the text accompanying the icon to be invisible, the background image approach can be combined with off-screen text. The text will be positioned outside of the visible screen area using CSS, essentially hiding it for everyone except those using assistive devices. To position something off-screen, you can either use the [d2l-offscreen](https://github.com/BrightspaceUI/offscreen) component, or follow [WebAIM's text-indent technique](http://webaim.org/techniques/css/invisiblecontent/). For example, a button which contains only an icon: ```html Bookmark ``` We've used the `title` attribute in this example to display tooltips on-hover. #### Sass Mixins If you'd like to use the [Sass](http://sass-lang.com) extension language in your application, `d2l-icons` provides an `icons.scss` file you can import which contains mixins to generate the background image CSS. Import the mixin file and [include it](http://sass-lang.com/documentation/file.SASS_REFERENCE.html#including_a_mixin) in a CSS class for each of the icons you'd like to use: ```scss @import "bower_components/d2l-icons/icons.scss"; .my-app-bookmark-icon { @include d2l-icon-tier1-bookmark-hollow(); } .my-app-print-icon { @include d2l-icon-tier1-print(); } ``` The name of the mixin will correspond to its location within the `images` directory, plus the subdirectory/category (e.g. `tier1`, `tier2`), plus the icon's filename -- all separated by hyphens. Finally, consume the CSS class in your markup as before. ```html ``` Advantages: - color (ferrite) is automatically set - size is automatically set Disadvantages: - requires Sass - no ability to change the color - no automatic support for right-to-left icons ## Coding styles ### Updating or contributing new icons #### First, do you need to contribute? Before contributing to our shared set of icons, ask yourself whether your new icon is common enough to be included here. Will it be used in many other applications, or is it unique to yours? To keep our icon sets small and improve performance, only icons that have the potential to be reused many times should be a part of this library. #### SVG format When contributing changes to icons, the SVG files should be properly formatted. Follow these rules: - native icon sizes need to be one of: 18, 24 or 30 - the `